中文大模型通用SDK

1. 快速开始

1.1 安装

#### 1.1.1 SDK 安装

pip install cnllm

1.1.2 作为 Agent Skill 安装

一键安装：

npx skills add https://github.com/kanchengw/cnllm

或手动将项目根目录的 SKILL.md 文件复制到 Agent 的技能目录下，在调用中文大模型时， 会优先使用 CNLLM。

BatchResponse(status={...}, usage={...})

print(resp.results)

BatchResponse(status={...},usage={...},batch_info={...})

**to\_dict():** 将响应转换为字典，保留指定字段，未在 keep 声明的字段若保留会产生警告：

2.4 批量调用控制参数

批量调用支持重试策略、并发控制参数配置：

batch\_size： 仅支持批量 Embeddings 调用时配置，默认根据请求数量自适应计算，不建议手动配置。

4. CNLLM 统一接口参数

除下表中作特殊说明的参数，其他参数都接受在客户端初始化和调用入口配置，调用入口处的配置会覆盖客户端初始化的配置。

4.1 CNLLM 请求参数

CNLLM 请求参数与OpenAI 标准参数基本一致，覆盖范围基于国内厂商情况稍有扩展，未覆盖的参数则使用厂商命名并进行透传。 注：并非所有支持模型都支持全部请求参数，请参考厂商官方文档确认，或配置 drop_params="ignore" 以忽略不支持的参数。

4.1.1 基础参数

| 参数 | 类型 | 默认值 | 说明 | | ------------------- | ------------------------------- | ------------------------------- | ------------------------------------------------------ | | model | str | - | 模型名称，客户端初始化必填，调用入口可覆盖 | | api_key | str | - | API 密钥 | | base_url | str | 自动适配 | 可自定义 API 地址 | | messages | list[dict]/list[list[dict]] | - | chat() 输入参数，支持上下文管理/图片识别（仅支持调用入口配置） | | prompt | str/list[str] | - | chat() 输入参数（仅支持调用入口配置） | | requests | list[dict] | - | chat.batch() 输入参数，支持对批量请求中 per-request 独立配置（仅支持调用入口配置） | | input | str/list[str] | - | embeddings() 输入参数（仅支持调用入口配置） | | stream | bool | False | 流式响应 | | thinking ¹ | bool/dict | 由模型端口决定，默认多为 False | 思考模式，支持 True/False，部分模型支持 "auto" | | tools | list | - | 工具/函数定义列表 |

¹ thinking 映射： - GLM、DeepSeek、Baidu、Hunyuan、Xiaomi、Kimi：True → {"type": "enabled"}，False → {"type": "disabled"} - Doubao：True → "enabled"，False → "disabled"，"auto" → "auto" - Qwen：True → enable_thinking: true，False → enable_thinking: false

4.1.2 高级参数

| 参数 | 类型 | 默认值 | 说明 | | ------------------- | ------------------------------- | ------------------------------- | ------------------------------------------------------ | | temperature | float | 由模型端口决定 | 生成随机性 | | max_completion_tokens | int | 由模型端口决定 | 最大生成 token 数（包含思维链） | | max_tokens | int | 由模型端口决定 | 最大生成 token 数（不包含思维链） | | top_p | float | 由模型端口决定 | 核采样阈值 | | stop | str/list | - | 停止序列 | | reasoning_effort | str | 由模型端口决定 | 推理深度控制 | | tool_choice | str/dict | - | 工具选择策略 | | response_format | dict | 由模型端口决定，默认多为 {"type": "text"} | 响应格式 | | n | int | 1 | 生成候选数 | | presence_penalty | float | - | 存在惩罚 | | frequency_penalty | float | - | 频率惩罚 | | logit_bias | dict | - | Token 级别偏差 | | user ¹ | str | - | 用户标识 | | seed | int | - | 随机种子，相同 seed 可复现结果 | | stream_options | dict | - | 流式输出配置，如 {"include_usage": true} | | logprobs | bool | False | 是否返回输出 Token 的对数概率 | | top_logprobs | int | 0 | 每个位置返回概率最高的候选 Token 个数 |

¹ user 映射： - GLM: user → user_id

4.1.3 厂商透传参数

4.1.1/4.1.2 中未覆盖的其他模型支持的参数，CNLLM 会透传到模型端口。

4.2 SDK 控制参数

CNLLM 内部定义的参数，控制内部执行的行为或策略，不向 API 端口传输。

4.2.1 通用参数

¹fallback_models 模型降级策略：

备用模型仅支持客户端初始化时配置，若 model 未成功响应，将顺序尝试传入的fallback_models，对应用的稳健性有要求，建议配置此项，并配置 drop_params="ignore" 避免参数支持性的影响。

fallback_models = {
    "deepseek-chat": {
        "api_key": "ds-key-456",     # 必填
        "base_url": "https://api.deepseek.com/v1",
    },
    "qwen-plus": {
        "api_key": "my-key",         # 不配置 base_url 时，使用默认 URL
    },
}

说明： - 调用入口处再次指定 model 会覆盖客户端配置的主模型，当调用入口的 model 失败时，仍会尝试 fallback_models - chat.batch() 中按 per-req 尝试 fallback - 不可重试的错误（模型不存在、参数缺失、内容过滤）会直接抛出，不触发 fallback - 全部模型失败时抛出 FallbackError，聚合所有失败信息

4.2.2 批量方法参数

仅对 chat.batch() 和 embeddings.batch() 调用生效：

deepseek-v4 系列需配置 thinking=False ，以接收 with_structured_output() 中包含的 tool_choice 参数；其他模型/厂商无此限制

class Person(BaseModel): name: str = Field(description="姓名") age: int = Field(description="年龄")

structured = runnable.with_structured_output(Person) result = structured.invoke("张三28岁") print(result) # → Person(name="张三", age=28)

{'id': '...', 'object': '...', 'created': '...', 'model': '...', 'choices': [{'delta': {'content': '实时累积的模型回复', 'reasoning_content': '实时累积的推理过程'}, 'finish_reason': 'None'}]}

```

reasoning_content chunks (模型推理过程，若有):

{'id': 'chatcmpl-xxx', 'object': 'chat.completion.chunk', 'created': 1234567890, 'model': 'minimax-m2.7', 'choices': [{'index': 0, 'delta': {'reasoning_content': '推理..'}, 'finish_reason': None}]}

5. 框架集成