如果你和我一样每次拿到一份新的中文大模型 API 文档第一反应不是逐字读原理而是先找参数速查表、术语表和能直接跑的示例代码那这份附录 CDE 应该能帮你省掉不少折腾。很多人第一次调 DeepSeek、智谱 GLM、通义千问这类接口时卡住的往往不是模型能力而是不知道 temperature 该填多少、max_tokens 和上下文长度到底是什么关系、报了 401 该先查哪里。这份组合资料就是把这些最琐碎但最重要的问题一次性整理好C 是参数速查表D 是术语表E 是中文模型 API 上手实操。适合正在写第一版 LLM 应用、或者想快速接入某个中文模型 API 的开发者也适合作为团队的 onboarding 材料。1. 这组附录到底解决什么问题先说明白这份附录的定位。它不是一篇讲大模型原理的论文也不是某个垂直框架的官方文档而是把“接入中文模型 API 这件事”压缩成三张能随时查阅的表格。C 负责参数D 负责术语E 负责带你把第一个请求跑通。三者的关系很像做饭时的调料表、食材名词表和一道示范菜你先记住盐放多少、生抽和酱油的区别再跟着做一遍就基本不会翻车。1.1 三张表三种用法C 参数速查表解决的是“写代码时不知道该填什么参数”的问题。比如 temperature 到底填 0.1 还是 0.9max_tokens 设置多大才够用response_format 什么时候需要写成 json_object这些在表里都能快速定位。D 术语表解决的是“读文档时看到一堆名词眼熟但不确定”的问题。Token、上下文长度、流式输出、函数调用、嵌入向量这些词单独拿出来可能都知道一点但组合在一起就容易懵。术语表用一两句话把每个词的使用场景讲清楚至少能保证你不理解错方向。E 是中文模型 API 上手指南解决的是“文档看了半天代码还是写不出来”的问题。它给出一套最小可用示例从获取 API Key、配置环境变量到发起对话请求一步步走通。这三张表叠加起来就是一份可以放在手边的“救命索引”。1.2 为什么单独整理一份中文模型的版本市面上有很多英文模型 API 的教程但中文模型 API 有自己的特殊性。首先是接口兼容性多数中文模型都宣称兼容 OpenAI 格式但 base_url、模型 ID、认证方式却各有差异直接照搬英文文档很容易碰到 401。其次是计费逻辑不同中文模型往往按 token 计费但各家免费额度、限流策略、模型命名规则差别很大。再有一点中文场景下很多参数会被忽略。System Prompt 里要不要加“请用中文回答”结构化输出时是不是必须用 JSON这些问题在英文教程里往往不是重点但实际做中文产品时非常关键。所以我单独整理了一份更贴合国内开发习惯的版本尤其是附录 E 里的示例全部走官方直连的 base_url不依赖任何第三方网关。2. 参数速查表写请求前先翻这一张参数速查表的核心价值不是把所有字段堆上来而是把高频使用的参数挑出来告诉你它们各自管什么、什么时候要动。下面这张表是我整理时反复校准过的覆盖了绝大多数 OpenAI 兼容接口的发请求场景。2.1 必背的核心参数参数作用常见默认值什么时候需要调整model决定使用哪个模型通常是必填无换模型、切换推理/对话模式时messages发送给模型的对话上下文通常必填无多轮对话、带历史记录时temperature控制输出的随机性值越大越天马行空1.0做创作、头脑风暴时调高做抽取、分类时调低top_p核采样控制候选词范围1.0想要更稳定的输出时调低如 0.3max_tokens限制本次输出的最大 token 数各家不同控制输出长度、成本时必调stream是否流式返回false想要打字机效果、或输出很长时stop停止生成的标记null想让模型在特定位置结束时使用response_format指定输出格式null强制输出 JSON 时用frequency_penalty惩罚重复词值越大越不容易复读0写文案、扩展内容时适当调高presence_penalty鼓励模型讨论新话题0想让回答更发散时调高user调用方标识用于追踪和风控null多人共用 API Key 时建议传入这里的默认值要特别注意各平台可能不一样。有的平台默认 temperature 是 0.8有的默认是 1.0有的 max_tokens 不设置就不会限制输出。所以我建议把“默认值”当成参考真正写代码时务必查看你所调用模型的官方文档。2.2 参数不是单独生效的很多人容易犯一个错误把 temperature 和 top_p 同时调得很高觉得这样“随机性更强”。其实 temperature 控制的是概率分布的平滑程度top_p 控制的是从累计概率多高的区间里采样。两者都调等于同时拧两个阀门效果往往互相干扰。我常用的做法是固定一个调整另一个。另一个容易被忽略的联动关系是 max_tokens 和上下文长度。模型最大上下文长度指的是输入和输出加在一起不能超过上限而 max_tokens 只限制输出部分。比如一个模型的最大上下文是 8192 tokens你一次性塞进去 7800 tokens 的输入再把 max_tokens 设成 4000必然报错。参数速查表上必须把这两者的关系标清楚否则你会在 400 错误上浪费很多时间。还有 response_format 和 prompt 的关系。很多中文模型支持response_format{type: json_object}但强制 JSON 模式时往往要求 messages 里包含“json”或“JSON”这样的字样模型才知道要用 JSON 来回复。速查表里我会补一句注释用了 JSON 模式prompt 里也最好带上示例结构。2.3 我常用的几组参数模板速查表只给参数含义还不够我给几组直接抄作业的模板。场景temperaturetop_pmax_tokens其他参数结构化抽取 / 分类0.10.22000response_format 用 json_object客服问答 / 知识库问答0.20.3800system prompt 写明回答约束文案创作 / 头脑风暴0.80.94000presence_penalty 0.3代码生成 / 代码解释0.20.42048stop 可以设置代码块结束符这套模板不是唯一答案但能帮你避免一开始就乱调参数。先说清楚任务属性抽取、分类这类任务需要稳定温度越低越好创作类任务需要多样温度可以放到 0.8 左右但也没必要直接拉到 1.5 以上否则输出会开始语无伦次。代码生成看起来像“任务”实际上也需要一定灵活度0.2 到 0.4 是我试下来比较稳的区间。3. 术语表把这 12 个词先焊进脑子里附录 D 的术语表看起来像“单词本”但它的真正作用是在你读错误信息、看官方文档、和同事讨论需求的时候不产生歧义。很多排查问题卡壳根源根本不是代码错误而是概念理解有偏差。3.1 高频术语速记表术语一句话解释典型使用场景Token模型处理文本的最小单位中文场景下 1 个汉字约等于 1~2 个 token计费、限流、上下文长度计算Context Length模型上下文窗口输入 token 与输出 token 的总和上限判断请求是否超长Temperature控制概率分布的平滑程度影响输出随机性创意写作、稳定抽取Top-p核采样只从累计概率达到 p 的候选词里选配合 temperature 控制多样性System Prompt给模型的角色和任务设定优先级较高客服、翻译、代码助手等固定人设Few-shot Prompt在 messages 里放几个例子让模型模仿格式解析、少样本分类Streaming流式输出按增量返回内容打字机效果、长文本实时展示Function Calling让模型输出结构化工具调用参数调用外部工具、执行动作JSON Mode强制模型输出合法 JSON接入业务系统、数据解析Embedding把文本转成向量用于相似度计算知识库检索、语义搜索RAG检索增强生成先从知识库召回再让模型回答私有知识库问答Fine-tuning在基座模型上用自有数据继续训练固定风格、特定格式输出这些术语里QPS、TPM 这类限流指标也很重要。QPS 是每秒请求数TPM 是每分钟 token 数很多报错写的是429 rate limit实际上就是这两个指标超了。3.2 容易混的三组概念第一组是 temperature 和 top_p。它们都能影响随机性但机制不同。temperature 影响的是整个概率分布的“胖瘦”top_p 是截断小概率尾巴。实际使用中我建议只调一个不要同时反复调。想稳定输出就降 temperature想控制候选范围就降 top_p。第二组是 max_tokens 和上下文长度。上下文长度是模型能同时看到的 token 总量max_tokens 只是输出的上限。你输入很长时max_tokens 再大也救不回来必须先压缩输入或改用能处理长上下文的模型版本。第三组是 System Prompt 和 User Prompt。System 是设定规则、人设的User 是用户真实输入。很多新手把一堆背景资料塞进 User Prompt导致 system 的设置失效。正确做法是固定的行为规则放 system动态内容放 user二者职责清晰。3.3 怎么用术语表反查文档术语表的用法不是拿来背诵而是当字典。遇到不认识的词先看术语表里有没有再回到官方文档搜索对应英文关键词。很多中文模型文档翻译不太统一有的叫“上下文窗口”有的叫“最大长度”但背后的英文都是 context length。你在术语表里定位到英文原文后再翻文档就不会迷失了。4. 中文模型 API 上手从零跑通第一个请求附录 E 是全篇最实战的部分。我以 DeepSeek 为例因为它的接口格式在中文模型里很有代表性而且有一个非常友好的免费额度。后面的代码同样适用于智谱 GLM、通义千问等兼容 OpenAI 格式的接口只需要改三个地方API Key、base_url、model 名称。4.1 前置准备第一步去官方开放平台注册账号创建 API Key。这里要特别注意API Key 通常在创建时只会完整显示一次关掉弹窗之后就再也看不到了。创建后立刻复制到本地最好直接存进环境变量。第二步安装 Python SDK。绝大多数中文模型都支持 OpenAI 兼容协议所以用 openai 这个包就够了。建议版本不低于 1.0因为旧版的openai.ChatCompletion.create写法已经过时了。第三步配置环境变量。Linux 和 macOS 可以用 exportWindows 可以用 set。我习惯把 Key 放在.env文件里用python-dotenv加载避免把密钥写进代码仓库。4.2 最小可用代码以 DeepSeek 为例一个最小可用的对话请求长这样import os from openai import OpenAI client OpenAI( api_keyos.environ[DEEPSEEK_API_KEY], base_urlhttps://api.deepseek.com, ) resp client.chat.completions.create( modeldeepseek-chat, messages[ {role: system, content: 你是帮用户做菜谱结构化的助手回答只输出 JSON。}, {role: user, content: 整理成结构化菜谱西红柿炒蛋两个西红柿、三个鸡蛋、两勺油、一勺盐先炒蛋后炒柿。}, ], temperature0.2, max_tokens1024, response_format{type: json_object}, ) print(resp.choices[0].message.content) print(用量:, resp.usage)这套代码的关键点有三个。第一是base_url必须和 Key 来自同一个平台。用 DeepSeek 的 Key 去请求别的平台大概率会返回 401。第二是response_format在强制 JSON 模式时prompt 最好明确提到 JSON 结构否则某些模型会不稳定。第三是resp.usage里会有 prompt_tokens、completion_tokens、total_tokens这是后续算成本的重要字段。换成智谱 GLM 只需要改client OpenAI( api_keyos.environ[ZHIPU_API_KEY], base_urlhttps://open.bigmodel.cn/api/paas/v4, ) resp client.chat.completions.create( modelglm-4-plus, messages[...], )换成通义千问则是client OpenAI( api_keyos.environ[DASHSCOPE_API_KEY], base_urlhttps://dashscope.aliyuncs.com/compatible-mode/v1, ) resp client.chat.completions.create( modelqwen-plus, messages[...], )只要掌握这套格式切换到其他中文模型基本就是改配置的事不用重学一套 SDK。4.3 流式输出和 JSON 模式的写法很多应用需要打字机效果也就是把模型回复一个字一个字地显示出来。这时把streamTrue传进去stream client.chat.completions.create( modeldeepseek-chat, messages[ {role: user, content: 介绍上海周末适合去的一个小众景点500 字以内。} ], streamTrue, ) for chunk in stream: delta chunk.choices[0].delta if delta and delta.content: print(delta.content, end, flushTrue)需要注意流式模式下返回的是生成器不是完整的响应对象。chunk.choices[0].delta.content只包含当前增量。想拿到完整的 usage 统计需要额外看平台是否支持stream_options相关参数或者用不带 stream 的请求在最后补充统计一次。JSON 模式的写法其实很简单在请求参数里加response_format{type: json_object}即可。但要注意有些平台要求在 messages 里出现“json”字样否则可能报错或退化成普通文本。我在 prompts 里通常这样写“请以 JSON 格式输出结构如下”然后把目标 JSON schema 写清楚。4.4 看用量、算账单API 调用的成本是按 token 算的所以一定要养成看resp.usage的习惯。假设某次请求返回prompt_tokens: 15000 completion_tokens: 500 total_tokens: 15500假设该模型的定价是输入 4 元/百万 token输出 16 元/百万 token那么本次调用的成本就是15000 / 1000000 * 4 500 / 1000000 * 16 0.06 0.008 0.068 元也就是说一次 1.5 万 token 输入、500 token 输出的请求大概六分八厘钱。别看单次便宜如果每天调用十万次成本就是几千块钱。附录 E 里我给的建议是上线前先压测统计平均 token 消耗再根据日活估算预算不要等月底账单出来才心疼。5. 高频报错排查清单照着抄就行错误信息是学 API 最好的老师也是劝退新人最多的地方。这一节我把常见报错整理成一个排查清单基本覆盖了从第一次申请 Key 到业务上线的全过程。5.1 401Key 相关错误报错特征真实原因处理方法unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****Key 不对、复制少字符、或串了平台的 Key从官方控制台重新创建立刻复制避免手敲authentication fails, your api key: ****Key 无效或权限异常检查 Key 是否过期确认账号状态换 base_url 后突然 401Key 和 base_url 不匹配确认 base_url 与 Key 属于同一服务商遇到 401第一反应不要急着换库或换框架先检查三件事环境变量是否真的加载成功Key 是否复制完整base_url 是否和 Key 来自同一平台。我见过很多次所谓“神秘 401”最后都是.env文件里多了一个空格或者被 IDE 缓存了旧 Key。5.2 400上下文超长、模型不存在、组织被停用报错特征真实原因处理方法this models maximum context length is 1048576 tokens...输入加输出超过上下文上限压缩输入、减少 max_tokens、改用长上下文模型或分段处理model not found或类似提示模型 ID 写错、没有该模型权限查看官方模型列表用最新模型 IDthis organization has been disabled账号或组织被停用通常与欠费或违规有关登录控制台检查余额和账号状态联系客服配置错误: claude provider 缺少 base_url 配置聚合工具里 provider 配置不完整去工具配置页面补全 base_urldify unstructured api url is not configured for doc file processingDify 文件处理服务未配置不是模型 API 问题在 Dify 里配置 unstructured 解析服务上下文超长是最常见的 400 错误。我建议在上线前就统计业务里最长输入可能到多少 token给 max_tokens 留足余量。如果用长上下文模型比如最大 100 万 token 的版本也不是无限随便用数据量太大时成本和高延迟同样会反噬业务。5.3 429、402、503 与网络错误报错特征真实原因处理方法429 rate limit请求频率超过 QPS/TPM 限制降低并发、增加退避重试、提高配额402 insufficient balance账户余额不足充值或领取免费额度503 overloaded服务端过载指数退避重试避开高峰时段500 internal server error服务端异常记录请求 ID重试并联系客服connection dropped (econnreset)网络连接被重置增加超时、重试检查本地网络环境429 的处理不是无限重试而是要采用指数退避。第一次失败等 1 秒第二次 2 秒第三次 4 秒最多等 64 秒。这样既不会把自己客户端拖垮也更容易在服务端恢复后自动成功。econnreset 这种错误很多时候是网络抖动加了超时和重试机制后基本能解决。5.4 排查顺序建议遇到报错时我一般按这个顺序来查效率最高看状态码是 4xx 还是 5xx。4xx 多半是客户端参数问题5xx 是服务端问题。检查 Key、base_url、model 三者是否匹配。检查 messages 长度是否超限。检查账户余额和组织状态。查看官方服务状态页确认不是大面积故障。另外建议先写一个不带业务的 curl 测试请求用最小参数发一次。如果 curl 能通说明 SDK 封装或业务代码里参数有问题如果 curl 也报同样错误说明 Key 或 base_url 配置有问题。这个区分方法能节省大量排查时间。curl https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:你好}]}6. 我踩过坑之后总结的几条经验最后这部分不是文档内容是我实际排查过几十次 API 问题后的体会。希望能帮你少踩一些已经存在的坑。6.1 先想清楚“要让模型干什么”再调参数很多人在参数上调来调去其实问题出在没想清楚任务类型。分类、抽取这类任务模型要的是稳定性所以 temperature 越低越好文案创作要的是多样性温度可以调高一点但也别指望温度能让一个不会写文案的模型突然变会写。参数只是放大或缩小采样空间不能改变模型本身的能力边界。6.2 接入前把环境隔离好我建议任何项目都用.env管理 Key不要硬编码在代码里。在 Python 里用python-dotenv是最简单的做法在 CI/CD 里则把 Key 放到密钥管理服务中。很多人把 Key 提交到 Git 仓库然后又发现被爬虫扫到最后只能吊销重发这个过程比想象中痛苦得多。6.3 给每个应用单独分配 Key如果业务里有多个模块都在调用模型我会给每个模块创建独立 Key而不是全部共用同一个。这样一旦某个模块的 Key 泄露只需要吊销那一个不会影响整个系统。同时平台后台通常能看到每个 Key 的调用量和费用划分清楚后成本定位会容易很多。6.4 这套速查表还能继续生长我整理这套附录时只是一种“把答案放在手边”的思路。后面还可以继续扩展增加 Function Calling 参数速查增加多模态输入参数增加 Embedding 和 RAG 的常用配置组合甚至把不同中文模型的限流和计费差异做成对照表。如果你刚接触中文模型 API建议先把 C、D、E 三部分用过一遍再按自己的业务场景继续往附录里加东西。资料是自己维护的越用越顺手。