Skip to main content

Saturnus

轻量、通用、可扩展的 LLM 开发工具库。

Saturnus 提供模型交互所需的机制与操作工具,由开发者掌握消息历史、应用执行流程和模型选择。

设计原则:稳定字段统一,等价差异映射,特殊能力透传,未知信息保留。

当前范围

第一阶段提供基于 Chat Completions 的异步模型连接与协议兼容层:

  • 根据开发者提供的 Base URL、鉴权配置和模型 ID 调用服务。
  • 支持非流式请求和基础 SSE 流式读取。
  • 校验请求的基本结构及 JSON 数据。
  • 通过显式配置完成字段名称映射、取值转换和自定义请求校验。
  • 支持顶层扩展字段、消息内部扩展字段和自定义请求头。
  • 保留响应 JSON 中的标准字段和未知扩展字段。
  • 区分本地校验错误、通信错误、HTTP 错误和响应协议错误。
  • 提供异步上下文管理和手动资源关闭。

第二阶段增加可选的 ResponseAccumulator,将流式响应块聚合为正文、思考内容和现代函数工具调用,并收集响应标识、模型、时间和用量。聚合器独立于客户端,由开发者决定是否使用,以及何时读取快照、结束聚合或处理工具调用。

第三阶段增加可选的 Messages,便于构造常见角色消息、保存原始消息和编辑消息内部字段。通过 snapshot() 取得普通消息列表后交给客户端,原有字典接口继续可用。

第四阶段增加可选的 ToolRegistry,支持显式注册函数工具、选择独立工具子集、导出工具定义、解析并校验调用参数,以及辅助执行同步或异步处理函数。调用校验错误提供稳定分类和调用信息;执行结果通过 ToolResult 提供输入参数快照与输出,由应用决定如何接回消息和继续执行。

要求 Python 3.11 或更高版本。

Saturnus 不内置模型目录,也不自动发现模型能力。Agent Loop、工具执行时机和消息历史策略由开发者决定。

非流式调用

以下示例从环境变量读取连接配置,并在项目环境中运行。

import asyncio
import os

from saturnus import ChatClient


async def main():
    async with ChatClient(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        timeout=30.0,
    ) as client:
        response = await client.create(
            model=os.environ["LLM_MODEL"],
            messages=[{"role": "user", "content": "你好"}],
        )

    print(response)


asyncio.run(main())

base_url 应为包含主机名的绝对 HTTP(S) 地址,并包含服务要求的路径前缀,例如 https://your-service.example/v1,末尾是否有 / 均可。地址中的查询字符串保持原样。不接受空白字符、控制字符、fragment(#...)或 URL 中的用户名和密码。

endpoint_path 默认为 chat/completions,追加在 Base URL 的路径之后。它必须是非空相对路径,不以 / 开头,不包含 query、fragment、空白字符、控制字符或 .、.. 路径段。例如,Base URL 为 https://your-service.example/v1?api-version=2024-01-01、端点为 deployments/demo/chat/completions 时,最终路径为 /v1/deployments/demo/chat/completions,查询字符串保持原样。

提供 api_key 时,客户端发送 Authorization: Bearer ...。密钥必须是非空 ASCII 字符串,不接受空白字符或控制字符,也不会自动去除首尾空格。

通过 auth_headers 可以配置自定义鉴权,例如 auth_headers={"api-key": "your-key"} 或 auth_headers={"Authorization": "Token your-key"}。这些请求头同样接受基础校验,不能设置由 HTTP 客户端控制的 Content-Type、Content-Length、Transfer-Encoding 和 Host。

api_key 和 auth_headers 不能同时提供,即使 auth_headers 是空字典也会冲突。两者均省略或为 None 时,不添加鉴权头。

timeout 接受有限正数,不接受布尔值、字符串、None、NaN 或 Infinity。它用于配置 HTTPX 各阶段的超时,不代表整个模型生成过程的总时限。

非法连接配置在创建底层 HTTP 客户端之前抛出 ValidationError。

create() 返回完整的 JSON 字典,不要求开发者使用特定的响应对象。

消息构造与编辑

Messages 独立于客户端,只保存应用当前维护的工作消息。下面的代码在已打开客户端的异步上下文中运行:

from saturnus import Messages

messages = Messages()
messages.add_system("你是一个有用的助手")
messages.add_user("你好")

response = await client.create(
    model="your-model",
    messages=messages.snapshot(),
)
messages.add(response["choices"][0]["message"])
messages.add_user("请再简短一些")

非流式响应的 choice.message 可以通过 add() 原样添加。聚合器的 finalize() 结果同样可以取出 choice.message 添加;消息必须包含合法的 role,缺失时由调用方明确补充。扩展字段包括思考内容、工具调用和厂商元数据,均按接收的原始结构保留,不自动决定下一轮是否需要发送。

接口

接口 行为
Messages(messages=None) 从原始消息列表创建独立副本;允许从空列表开始
add(message) 添加一条原始消息字典
add_system(content, *, extra=None) 添加 system 消息
add_user(content, *, extra=None) 添加 user 消息
add_assistant(content=None, *, extra=None) 添加 assistant 消息;省略 content 时明确写入 None
add_tool_result(*, tool_call_id, content, extra=None) 添加 tool 结果消息,要求调用 ID 为非空白字符串
get(index) 返回指定消息的深拷贝
insert(index, message) 在指定位置前插入一条原始消息
replace(index, message) 用一条原始消息完整替换指定消息,不合并旧字段
remove(index) 删除指定位置的消息
snapshot() 返回全部工作消息的深拷贝,可传给客户端
len(messages) 返回消息数量

索引从 0 开始,支持负数索引,-1 指向最后一条消息。已有 n 条消息时,读取、替换和删除接受 -n <= index < n;插入接受 -n <= index <= n,index=n 表示末尾追加,负数表示在对应消息前插入。空容器只能在 0 处插入。越界或非整数索引抛出 ValidationError,不接受布尔值,也不把越界插入位置自动截断到首尾。

添加、插入、替换、删除及各快捷构造方法均返回 None。消息输入、内部数据、get() 结果和 snapshot() 结果彼此隔离;结构校验、JSON 校验或索引检查失败时,已有工作消息保持不变。

消息内部的扩展字段

快捷构造方法的 extra 合并到当前消息的顶层,与请求顶层的 extra_body 分开。例如,目标服务支持 assistant 消息中的 partial 时:

from saturnus import Messages

messages = Messages()
messages.add_assistant("从前有座山", extra={"partial": True})

extra 必须为字典或 None,不能覆盖快捷方法构造的 role、content,工具结果中也不能覆盖 tool_call_id,即使重复值相同也会报错。其他合法 JSON 字段保持原样。需要自定义角色或省略 content 时,直接通过 add() 传入原始字典。

嵌套字段使用普通字典和列表操作,修改副本后显式替换原消息:

messages.add(
    {
        "role": "user",
        "content": "分析这段内容",
        "vendor_options": {"mode": "brief"},
    }
)

message = messages.get(-1)
message["vendor_options"]["mode"] = "detailed"
messages.replace(-1, message)

上述扩展名称仅示意操作方法,是否支持及其实际含义由目标服务决定。Messages 不按模型名称猜测字段,不自动改名、删除或转换嵌套内容。需要反复执行消息第一层字段改名时,可以配置下文 Compatibility 的 message_field_mappings 参数。

校验与工具结果

消息沿用客户端的基础结构要求:role 为非空白字符串,content 可以缺失或为字符串、列表、None,未知角色和扩展字段均可保留。快捷方法显式写入 content,接受相同的基础类型。所有数据必须符合本项目的 JSON 要求。这些检查不代表特定模型支持该消息、内容块或角色组合;空消息容器可以用于组装,发送请求时仍要求非空消息列表。

add_tool_result() 只构造消息。应用自行执行工具并决定输出格式,例如把结果显式序列化成字符串后添加:

import json

messages.add_tool_result(
    tool_call_id="call-1",
    content=json.dumps({"time": "12:00"}),
)

上述 Messages 操作只构造消息,不执行工具、序列化任意 Python 返回值或检查调用 ID 与上下文中的工具调用是否匹配。需要本地工具执行时,可以显式使用下面的 ToolRegistry;消息顺序、历史裁剪、思考内容的回传规则和应用循环由开发者掌握。

工具注册与执行

ToolRegistry 接收显式提供的工具名称、说明、参数 JSON Schema 和处理函数。应用通过 definitions() 获取 Chat Completions 的工具定义,通过 execute() 显式执行模型返回的工具调用。

以下示例中的循环、最大轮数和结束条件由应用定义。运行前配置 LLM_BASE_URL、LLM_API_KEY、LLM_MODEL,并选择支持现代函数工具调用的模型。

import asyncio
import os
from datetime import datetime

from saturnus import ChatClient, Messages, ToolRegistry


def get_time() -> dict[str, str]:
    return {"time": datetime.now().astimezone().isoformat()}


async def main():
    tools = ToolRegistry()
    tools.register(
        name="get_time",
        description="获取运行机器的当前时间",
        parameters={
            "type": "object",
            "properties": {},
            "additionalProperties": False,
        },
        handler=get_time,
    )
    active_tools = tools.select(["get_time"])

    messages = Messages()
    messages.add_user("请调用 get_time,告诉我现在的时间。")

    async with ChatClient(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        timeout=120.0,
    ) as client:
        for _ in range(10):
            response = await client.create(
                model=os.environ["LLM_MODEL"],
                messages=messages.snapshot(),
                extra_body={"tools": active_tools.definitions()},
            )

            choice = response["choices"][0]
            message = choice["message"]
            reason = choice["finish_reason"]
            calls = message.get("tool_calls") or []
            messages.add(message)

            if reason == "stop" and not calls:
                print(message.get("content") or "")
                break

            if reason != "tool_calls" or not calls:
                raise RuntimeError(f"Unexpected completion state: {reason!r}")

            for call in calls:
                result = await active_tools.execute(call)
                messages.add_tool_result(
                    tool_call_id=result.tool_call_id,
                    content=result.content,
                )
        else:
            raise RuntimeError("Agent exceeded maximum turns")


asyncio.run(main())

模型需要的其他请求参数由应用添加到 extra_body。工具定义是否受目标模型支持,以及思考内容的多轮回传规则,由开发者根据服务要求配置。

接口与校验

接口 行为
register(name=..., description=..., parameters=..., handler=...) 校验并保存定义与处理函数,名称重复时拒绝注册
definitions() 按注册顺序返回工具定义的深拷贝,不包含本地处理函数
select(names) 返回包含指定工具的独立注册表,按父注册表的注册顺序导出,校验和执行也受该子集限制
validate_call(call) 检查调用结构、工具名称和参数,返回解析后的参数字典,不执行处理函数
await execute(call) 先校验调用,再执行处理函数并返回 ToolResult

名称必须为非空白字符串,说明必须为字符串,处理函数必须可调用。参数 Schema 必须为字典且顶层为 type="object",同时满足本项目的 JSON 数据要求。注册和导出时均保存独立副本,后续修改原始 Schema 或导出结果不会改变已注册的定义。

未声明 $schema 时采用 JSON Schema Draft 2020-12;声明后使用对应的已识别版本,未知版本明确报错。Schema 自身在注册时检查,实际参数在调用时检查。default 不自动填充参数,format 默认不做格式断言。开发者负责使 Schema 与处理函数接收的关键字参数保持一致;函数签名不匹配时,执行阶段会抛出 ToolExecutionError。

validate_call() 和 execute() 接收完整的现代函数工具调用字典,要求包含非空调用 ID、type="function"、已注册的函数名,以及字符串形式的 function.arguments。参数必须解析为合法 JSON 对象,并满足注册的 Schema。输入调用保持原样,合法的未知扩展字段不影响校验,返回的参数字典与原始调用隔离。

流式场景应先正常读完响应,通过 ResponseAccumulator.finalize() 获得完整的工具调用,再交给工具接口。工具接口不修复残缺 JSON,不从自然语言中猜测调用。

工具子集与披露范围

请求中的工具定义和本地执行应使用同一个作用域。上面的示例通过 active_tools.definitions() 导出定义,并通过 active_tools.execute(call) 执行调用;未选中的工具在该作用域内按未知工具拒绝,即使父注册表中存在同名工具。

select() 接受工具名称列表,拒绝非列表、非字符串、空白名称、重复名称和未知名称。空列表返回空注册表;已有子集继续选择时只能选择自身已有的工具。

选择顺序不影响导出顺序:父注册顺序为 A、B、C 时,选择 [C, A] 或 [A, C] 都按 A、C 导出。定义和 Schema 独立复制,处理函数保留原引用,因此有状态处理对象仍是同一个对象。返回值是普通的 ToolRegistry,应用后续在父表或子表显式注册新工具,互不影响。

开发者可以按任务阶段重新选择工具,构建渐进式披露流程;发现哪些工具、何时切换,以及文件或网络资源的访问约束由应用实现。稳定的定义和顺序有助于减少请求前缀变化,实际缓存复用取决于目标服务,选择接口不承诺缓存命中。

结构化调用校验错误

validate_call() 或 execute() 的调用校验失败时抛出 ToolCallValidationError,它继承 ValidationError,现有的 except ValidationError 继续有效。注册信息或选择配置非法时仍抛出普通 ValidationError。

应用可读取以下稳定字段,无需解析错误说明文本:

字段 含义
code 下表中的错误代码
tool_call_id 有效的原始调用 ID;缺失或不合法时为 None
tool_name 有效的原始函数名;缺失或不合法时为 None,未知工具仍保留其请求名称
argument_path Schema 不匹配时的参数路径列表,元素为字段名或数组索引;其他情况为 None
__cause__ 适用时保留原始 JSON、数据或 Schema 校验异常
code 含义
invalid_call 调用结构、必需字段或调用数据的 JSON 结构非法;包括 arguments 字段本身不是字符串
unknown_tool 当前注册表或子集中没有该工具
invalid_arguments_json arguments 字符串无法解析为本项目接受的有限 JSON 数据
invalid_arguments_type 已解析的合法 JSON 值不是对象
arguments_schema_mismatch 参数不满足已注册的 Schema
schema_validation_error Schema 无法正常求值,例如本地引用无法解析;与参数不满足 Schema 分开处理

argument_path=[] 表示参数根对象,["items", 0, "name"] 表示对应的嵌套位置。缺失必填字段时,路径指向执行该 required 检查的对象,不自动补上缺失的字段名。

错误分类供应用决定停止、展示或回传模型,库不自动恢复。缺失有效调用 ID 时不会生成替代 ID。处理函数尚未执行的调用校验错误直接向外传播;处理函数自身抛出的异常仍归为下面的执行失败。

执行结果与错误

ToolResult 提供:

  • tool_call_id:原始工具调用 ID。
  • arguments:校验成功后、处理函数开始前保存的输入参数深拷贝,适合用于应用快照和调用记录。
  • value:处理函数返回值的独立副本,必须可以表示为合法 JSON。
  • content:供工具结果消息使用的文本;字符串原样保留,其他 JSON 值序列化为字符串。

execute() 每次只执行一次调用校验。arguments 与处理函数接收的数据、value 以及其他执行结果彼此隔离,处理函数修改嵌套参数不会改变输入快照。直接构造 ToolResult 时仍可使用原有的三个字段;省略 arguments 会创建独立的空字典。

结果字段不能重新赋值,但 value 和 arguments 内部的字典和列表可以修改。content 是执行完成时生成的文本快照,不随后续修改重新生成。

异步处理函数在调用方事件循环中等待;同步函数通过线程执行,返回可等待对象时继续等待其结果。

调用结构或参数校验失败时抛出 ToolCallValidationError,处理函数尚未执行。处理函数异常或结果转换失败时抛出 ToolExecutionError,通过 tool_call_id、tool_name 获取调用信息,通过 __cause__ 获取原始异常。

异步取消继续向外传播。取消同步函数的等待不会强制终止已经运行的线程。并发、超时、重试,以及是否把错误转换成工具结果消息,由应用决定。

流式调用

import asyncio
import os

from saturnus import ChatClient


async def main():
    async with ChatClient(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        timeout=60.0,
    ) as client:
        async with client.stream(
            model=os.environ["LLM_MODEL"],
            messages=[{"role": "user", "content": "你好"}],
        ) as chunks:
            async for chunk in chunks:
                for choice in chunk.get("choices", []):
                    text = choice.get("delta", {}).get("content")
                    if isinstance(text, str):
                        print(text, end="", flush=True)

    print()


asyncio.run(main())

stream() 返回异步上下文管理器,其中的迭代器逐个产生 SSE data 事件中的 JSON 对象,保留每个对象的全部字段。

调用者自行读取文本、思考内容、工具调用或用量信息。stream() 本身不拼接完整回复;需要聚合时,显式使用下面的 ResponseAccumulator。

正常完成要求收到数据为 [DONE] 的完整 SSE 事件。事件必须由空行结束;仅在文件末尾出现 data: [DONE] 或其后只有一次换行,不算完成。连接在完整结束事件之前终止时,抛出 ResponseError。

除 [DONE] 外,每个 data 事件的数据必须是合法 JSON 对象。空字符串数据、非对象 JSON 或无效 JSON 都会抛出 ResponseError,并通过 event_data 保留对应的数据原文。SSE 注释和不含 data 字段的事件不会产生响应块。

退出流式 async with 块时会关闭响应,包括读取完成、提前退出、发生异常或任务取消的情况。

流式响应聚合

以下示例正常读完流后,再显式生成最终聚合结果:

import asyncio
import os

from saturnus import ChatClient, ResponseAccumulator


async def main():
    accumulator = ResponseAccumulator()

    async with ChatClient(
        base_url=os.environ["LLM_BASE_URL"],
        api_key=os.environ["LLM_API_KEY"],
        timeout=120.0,
    ) as client:
        async with client.stream(
            model=os.environ["LLM_MODEL"],
            messages=[{"role": "user", "content": "你好"}],
        ) as chunks:
            async for chunk in chunks:
                accumulator.add_chunk(chunk)
                # 可以在这里读取 snapshot(),由应用自行更新界面。

    result = accumulator.finalize()
    for choice in result["choices"]:
        message = choice["message"]
        print("正文:", message.get("content", ""))
        print("思考:", message.get("reasoning_content", ""))
        print("工具调用:", message.get("tool_calls", []))
        print("结束原因:", choice["finish_reason"])

    print("用量:", result.get("usage"))


asyncio.run(main())

同一个响应块可以同时包含正文、思考和工具调用,聚合器会分别处理。正文、思考和函数参数按收到的顺序拼接,不去除空白,也不解析自然语言中的工具调用语句。

接口与结果

接口 行为
add_chunk(chunk) 接收单个响应块字典,先校验整个块,再更新状态;失败时抛出 ValidationError,已有状态和原始块记录保持不变
snapshot() 返回当前聚合结果的独立快照,允许结果尚未完成
raw_chunks 返回已接受的全部原始响应块的深拷贝,包含未知扩展字段
finalize() 检查完成条件,成功后封存并返回独立快照;重复调用返回内容相同的独立快照
is_finalized 表示显式封存是否成功,初始为 False;它不是网络连接状态

add_chunk() 接收流式响应中的 choice.delta 结构,不接收 create() 返回的 choice.message 结构。非流式响应已经是完整字典,可以直接读取,无需经过流式聚合器。

聚合结果包含 choices 列表,每项包含 index、message 和 finish_reason,按 choice index 排序。message 按实际收到的数据提供 role、content、reasoning_content 和 tool_calls。未收到的消息字段不自动补齐;null 文本不参与拼接,choice 尚未结束时收到的空字符串则保留其字段。

根级 id、model 收集首次收到的非 null 值,后续不同值会触发冲突错误。created 保留首次收到的非 null 值,不比较大小,也不用于判断响应身份;各分片中的原始值完整保存在 raw_chunks。null 不创建或清除这些字段。id、model 必须是非空字符串;created 必须是非负整数,不接受布尔值。

usage 必须为字典或 null。它按最新的非 null 字典整体替换,不累加 Token,也不合并不同快照;空字典同样会替换旧值。后续 null 不清除已有用量。未收到 usage 时结果不含该键;只收到 null 时结果包含 usage: None。用量可以随普通 choice 返回,也可以单独放在 choices=[] 的响应块中。

结果是聚合视图,不是原始响应的完整替代。object、logprobs、annotations 及其他未聚合字段保存在 raw_chunks,不会猜测它们的合并语义。输入数据、结果快照和对外返回的原始块副本彼此隔离。

显式配置来源字段

配置参数 默认来源字段 固定输出字段
content_field content message.content
reasoning_field reasoning_content message.reasoning_content
tool_calls_field tool_calls message.tool_calls

例如,服务使用其他字段名,但字段结构和增量语义相同时:

from saturnus import ResponseAccumulator

accumulator = ResponseAccumulator(
    content_field="text_delta",
    reasoning_field="thought_text",
    tool_calls_field="function_calls",
)

这些参数选择 choice.delta 内的字段,不支持嵌套路径;名称必须是非空白字符串,彼此不同,也不能与 role 相同。配置其他名称后,不会回退读取默认字段。未选中的字段作为扩展数据保存在原始块中,不参与对应的聚合结构校验,但仍须是合法 JSON 数据。

字段配置只改变读取位置,不转换结构或语义。上例的 function_calls 仍须是现代工具调用增量数组,不代表支持旧版 function_call 对象。结构或增量语义不同的服务,应由调用方先显式转换,再交给聚合器。请求侧的 Compatibility 不作用于响应。

工具调用与完成边界

当前仅聚合现代 Chat Completions 中 type="function" 的工具调用,按 choice index 和工具 index 分组,各自独立累积。两类 index 都必须是非负整数且不能是布尔值;同一个响应块中不能重复出现 choice index。

工具的 id、type、function.name 按完整身份字段处理,不进行字符串片段拼接;允许暂时缺失或为 null,重复相同身份值不会重复累积,出现冲突则拒绝整个响应块。function.arguments 按字符串增量拼接,保留空字符串以及尚未组成合法 JSON 的内容。最终输出的工具列表按工具 index 排序,不包含流式增量专用的工具 index。

finalize() 要求至少出现一个 choice,并且每个已出现的 choice 都有非空 finish_reason。已有工具调用必须收齐 id、type、函数名和参数字符串;finish_reason="tool_calls" 时至少存在一个工具调用。聚合器不会补全缺失身份、校验参数 JSON 或执行工具;应用在执行前还需检查结束原因、解析参数并进行自己的校验。

length、content_filter 和服务扩展的结束原因原样保留,不会仅因原因不是 stop 就拒绝封存。封存成功表示满足聚合结构的完成条件,不表示答案成功、内容完整或工具参数可以执行。

同一个 choice 的非空 role 不允许改变。choice 收到结束原因后,不能更改该原因或追加正文、思考、工具调用;空文本、null、空工具列表和重复的相同 role、结束原因可作为无新增输出的尾块接受,不改变消息快照。结束后首次补入 role 会被拒绝。结束 choice 的扩展尾块仍保留在 raw_chunks 中,其他 choice 可以继续输出,根级用量也可以继续到达。

聚合器看不到 SSE 的 [DONE],也不知道调用方是否提前退出循环。 应在正常读完整个流后调用 finalize(),不要在 finally 中无条件调用。读取异常、取消或提前退出时,可用 snapshot() 查看部分结果,保持 is_finalized=False。单独收到 finish_reason 不会自动封存。

封存校验失败不会改变状态;尚未结束的 choice 可以继续接收后续块。封存成功后拒绝所有新的 add_chunk(),包括用量块,因此每次模型请求应创建独立的聚合器。

聚合器会在内存中保存拼接数据和全部原始块,snapshot() 和 raw_chunks 还会生成副本。长输出场景应由应用控制读取快照的频率;只需要原始增量时,可以直接使用 stream()。

响应元信息

create() 返回完整字典,stream() 提供响应块迭代器。需要读取 HTTP 状态码或响应头时,使用对应的元信息接口。

以下代码在已打开客户端的异步上下文中运行:

result = await client.create_with_response(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
)

print(result.data)
print(result.response.status_code)
print(result.response.headers.get("x-request-id"))

async with client.stream_with_response(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
) as result:
    print(result.response.status_code)
    print(result.response.headers.get("x-request-id"))

    async for chunk in result.chunks:
        print(chunk)

create_with_response() 返回 ChatResponse,包含完整响应字典 data 和原始 httpx.Response 对象 response。

stream_with_response() 提供 ChatStreamResponse,包含响应块迭代器 chunks 和原始 HTTP 响应 response。进入上下文后即可读取响应头,不会提前消费响应块。通过 chunks 在上下文内部读取流式数据,退出上下文时关闭响应。

这些包装保留原始模型字段,沿用普通接口的请求校验、兼容规则和错误分类。具体响应头是否存在,由目标服务决定。

扩展字段

extra_body 合并到请求 JSON 顶层。例如,在支持该参数的服务上关闭 Thinking:

response = await client.create(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
    extra_body={
        "thinking": {"type": "disabled"},
    },
)

消息可以直接使用字典。Saturnus 保留消息内部未知但合法的 JSON 字段,不保证目标服务支持这些字段。

model、messages 和 stream 由客户端接口控制,不能通过 extra_body 指定;发生冲突时抛出 ValidationError。

请求 JSON 要求对象键为字符串、数组使用列表,不接受 NaN、Infinity、循环引用或其他无法表示为 JSON 的数据。

自定义请求头通过 extra_headers 提供,仅作用于当前请求:

response = await client.create(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
    extra_headers={"X-Request-ID": "example-request"},
)

当前请求头校验支持合法的 ASCII 名称和值,拒绝大小写不敏感的重复名称。以下请求头由客户端控制,不能通过 extra_headers 覆盖:

  • Authorization
  • Content-Type
  • Content-Length
  • Transfer-Encoding
  • Host

通过 auth_headers 配置的所有请求头,也不能被 extra_headers 覆盖。冲突判断不区分大小写。客户端保存鉴权头的独立副本,后续修改原始配置字典不会改变已创建客户端的鉴权。

显式兼容规则

开发者根据目标服务配置 Compatibility,Saturnus 不根据模型名称自动选择规则。

from saturnus import Compatibility

compatibility = Compatibility(
    field_mappings={
        "output_tokens": "max_completion_tokens",
        "thinking_mode": "thinking",
    },
    value_mappings={
        "thinking_mode": {
            "off": {"type": "disabled"},
            "on": {"type": "enabled"},
        },
    },
)

创建客户端时传入 compatibility=compatibility,随后可以使用:

response = await client.create(
    model="your-model",
    messages=[{"role": "user", "content": "你好"}],
    extra_body={
        "output_tokens": 64,
        "thinking_mode": "off",
    },
)

上述配置将两个扩展字段转换为:

{
  "max_completion_tokens": 64,
  "thinking": {"type": "disabled"}
}

顶层 field_mappings、value_mappings 规则具有以下行为:

  • 仅作用于请求顶层字段。
  • 取值映射按转换前的来源字段名称配置,不会自动使用重命名后的目标字段名称查找规则。
  • 仅字符串取值参与取值映射,映射结果可以是任意合法 JSON 值。数字、布尔值、对象、数组和 null 等来源值保持原样。
  • 字段和取值映射各执行一次,不进行链式转换。
  • 未配置的字段和未匹配的取值保持原样。
  • 字段映射的来源、目标,以及取值映射的字段名均不能为空字符串;允许空规则表。
  • 禁止映射 model、messages 和 stream。
  • 映射目标已经存在,或多个实际请求字段指向同一目标时,抛出 ValidationError。
  • 不修改调用者传入的请求数据。apply() 返回独立的数据快照,嵌套消息和扩展对象也与入参隔离。

还可以通过 Compatibility(validator=...) 提供同步校验函数。该函数接收转换后请求的深拷贝;对这份副本的修改不会写回请求。校验成功必须返回 None,校验失败应抛出 ValidationError。异步校验函数不受支持,函数中的其他异常原样向外传播。

兼容配置同样适用于 create()、create_with_response()、stream() 和 stream_with_response()。

按角色映射消息字段

通过 message_field_mappings 明确配置“消息角色 → 来源字段 → 目标字段”。例如,目标服务要求将 assistant 消息中的 thought 改名为 reasoning_content:

from saturnus import Compatibility, Messages

compatibility = Compatibility(
    message_field_mappings={
        "assistant": {"thought": "reasoning_content"},
    },
)

messages = Messages(
    [
        {"role": "user", "content": "你好"},
        {"role": "assistant", "content": "你好呀", "thought": "简短回应"},
    ]
)

request = {"model": "your-model", "messages": messages.snapshot()}
mapped = compatibility.apply(request)

assert mapped["messages"][1] == {
    "role": "assistant",
    "content": "你好呀",
    "reasoning_content": "简短回应",
}
assert messages.get(1)["thought"] == "简短回应"
assert request["messages"][1]["thought"] == "简短回应"

上例通过 apply() 展示转换结果。实际请求只需把配置传入 ChatClient(..., compatibility=compatibility),客户端会在发送时执行规则;应用继续传入 messages.snapshot() 或原始消息列表。

规则按以下约定执行:

  • 角色与字段名称按字符串精确匹配,不自动去除空白或推断模型;允许自定义角色,不提供通配符语义。
  • 只处理每条消息的第一层字段,不遍历 content[]、tool_calls[] 或其他嵌套对象,字段名中的点号等字符不解释为路径。
  • 角色、来源和目标名称必须为非空白字符串;每个角色的规则必须为字典,允许空规则表。None 或空的总配置表示不开启消息映射。
  • role、content 不能作为映射来源或目标。其他字段仅改名,取值保持原有类型和结构,包括 None、对象和列表。
  • 角色不匹配或来源字段不存在时保持原样;来源缺失时不创建目标字段,也不删除已经存在的目标字段。
  • 按原始消息字段映射一次,不进行链式转换。普通字段映射到自身时保持原样。
  • 来源和不同名称的目标同时存在时抛出 ValidationError,即使值相同、目标为 None,或目标还配置了另一条改名规则也一样。
  • 多个实际出现的来源字段映射到同一目标时抛出 ValidationError;不同消息分别处理,互不冲突。
  • 消息结构、JSON 或映射冲突导致失败时,调用方消息和配置保持不变,客户端不会发送请求。冲突错误说明包含消息位置与目标名称。

转换顺序为请求顶层字段及取值映射、消息字段改名、最后执行 validator。校验函数接收全部转换完成后的独立副本,其修改仍不会写回请求。启用消息规则且请求包含 messages 时,还会检查消息列表与每条消息的基本结构。

消息规则可以和顶层规则同时配置,不会修改应用保存的工作消息或服务端返回的数据。响应聚合时的来源字段通过 ResponseAccumulator 单独配置;两种配置不会自动互相推导。字段结构转换、消息内取值映射和嵌套路径转换由应用按实际需求处理。

错误处理

所有库定义的错误继承自 SaturnusError。

错误类型 含义 可读取的信息
ValidationError 本地连接配置、请求数据、兼容配置、消息操作、聚合数据及状态、工具注册或调用参数不合法 错误说明
ToolCallValidationError 工具调用校验失败,继承 ValidationError code、tool_call_id、tool_name、argument_path、__cause__
ToolExecutionError 工具处理函数或结果转换失败 tool_call_id、tool_name、__cause__
TransportError 连接失败、超时或流式读取中断 __cause__ 中的底层异常
APIError 服务端返回非成功 HTTP 状态 response 中的 HTTP 响应及响应体
ResponseError 响应不符合预期协议 response,以及适用时的 event_data

ResponseError 包括非流式响应不是合法 JSON 对象、流式响应类型不正确、事件 JSON 无效或缺少 [DONE] 等情况。非流式响应和流式事件均拒绝非标准 JSON 数值常量 NaN、Infinity 和 -Infinity,并抛出 ResponseError。字符串 "NaN" 等普通文本不受影响。

客户端流式读取不会预先缓存整个响应;选择使用 ResponseAccumulator 时,由聚合器累计数据。解析事件失败时,可以通过 event_data 读取对应事件的数据原文。

资源管理

推荐通过 async with ChatClient(...) 管理客户端生命周期。

需要手动管理时,调用 await client.aclose() 关闭客户端。流式请求还需使用独立的 async with client.stream(...) 或 async with client.stream_with_response(...) 块管理响应生命周期。

自定义 HTTP 传输

客户端接受可选的 transport 参数,类型为 httpx.AsyncBaseTransport。可以传入 httpx.MockTransport 进行测试,或传入自行配置证书、代理等选项的 httpx.AsyncHTTPTransport。

以下示例在异步函数内运行,不访问真实服务:

import httpx

from saturnus import ChatClient

transport = httpx.MockTransport(
    lambda request: httpx.Response(200, json={"choices": []})
)

async with ChatClient(
    base_url="https://llm.example/v1",
    transport=transport,
) as client:
    response = await client.create(
        model="my-model",
        messages=[{"role": "user", "content": "hello"}],
    )

传入的 transport 由 ChatClient 管理生命周期。退出客户端上下文或调用 aclose() 时会关闭它,每个客户端应使用独立的 transport 实例。

退出单次流式上下文只关闭该响应,客户端及其 transport 可以继续用于后续请求。

第一阶段联调记录

2026-10-28,使用同一套客户端接口完成以下真实服务测试:

服务 Base URL 模型 Token 上限字段 非流式 流式
DeepSeek API https://api.deepseek.com deepseek-flash max_tokens 通过 通过
MiMo Token Plan https://token-plan-cn.xiaomimimo.com/v1 mimo-v2.6-flash max_completion_tokens 通过 通过

两项配置均通过显式规则将 output_tokens 映射为目标字段,并透传 thinking: {"type": "disabled"}。每次请求的输出上限为 64 Token,流式读取均正常收到 [DONE]。

此记录仅代表上述模型与配置的联调结果。MiMo Token Plan 使用套餐控制台提供的专属 Base URL 和 API Key。

第二阶段联调记录

2026-10-30,使用上述两项服务配置,通过同一个 ResponseAccumulator 接口完成以下真实流式聚合验收:

服务 模型 正文(Thinking 关闭) 正文与思考(Thinking 开启) 函数工具调用(Thinking 关闭)
DeepSeek API deepseek-flash 通过 通过 通过
MiMo Token Plan mimo-v2.6-flash 通过 通过 通过

六项请求均正常读完 SSE 流后调用 finalize()。验收检查了正文与思考的分别聚合、工具名称与参数字符串,以及已返回的根级元信息和最新用量快照的保留。工具参数由验收脚本单独解析和检查,未执行工具。

MiMo 思考响应的一个样本在相同 id、model 下返回了变化的 created。聚合器按统一规则保留首次收到的非 null 时间值,原始分片中的各个值仍完整保留,不根据厂商名称选择行为。

本地完整代码检查、格式检查、自动化测试、构建和 wheel 安装导入验证通过。上述联调只覆盖表中模型、配置和三种分别测试的模式,不代表所有兼容服务或 Thinking 与工具调用组合均已验证。

本地开发

uv sync --locked
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked pytest -q
uv build

GitHub CI 配置为在 Python 3.11–3.14 下执行代码检查、测试、构建和 wheel 安装导入验证。

自动化测试通过模拟 HTTP 传输运行,不需要真实 API Key。真实服务联调单独进行。

Metadata

Release files for saturnus-llm 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for saturnus-llm 0.1.0
File Size Uploaded Provenance Actions
saturnus_llm-0.1.0.tar.gz 40.6 kB Without provenance Details for saturnus_llm-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for saturnus-llm 0.1.0
File Interpreter ABI Platform Actions
saturnus_llm-0.1.0-py3-none-any.whl Python 3 none any Details for saturnus_llm-0.1.0-py3-none-any.whl

Total release size: 72.5 kB

Release files / saturnus_llm-0.1.0.tar.gz

Download URL saturnus_llm-0.1.0.tar.gz
Size 40.6 kB
Tags Source
SHA-256 checksum
How to use checksums
07bfbedc31968d1895ae0f18b16c3856d5e3a97b9abe068c04fdc64b0fa70aeb
BLAKE2b-256 checksum
How to use checksums
8e452f6e89c72d2d92c8784def0a6f4d8064b4070b1488b281d68bf889aff781
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / saturnus_llm-0.1.0-py3-none-any.whl

Download URL saturnus_llm-0.1.0-py3-none-any.whl
Size 31.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bfa4dc6aae83c36c40f8d4d739e172f31775e3684dfdd02dfbbd370a55351e53
BLAKE2b-256 checksum
How to use checksums
4d084687a0e8cb597fdf90521562383c72740dd2fb71a51f89c240be2914b0bc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for saturnus-llm 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page