1. 这份速查表到底解决什么问题先把场景说清楚。你手上有一份技术手册或者项目文档正文部分讲的是原理、架构、设计思路读起来挺顺。但真正干活的时候你需要的不是为什么这么设计而是这个参数叫什么、默认值是多少、取值范围在哪一页。翻回正文找一来一回十分钟没了。附录CDE就是干这个的——把散落在正文各处的参数、术语、接口调用方式抽出来做成三张可以随时查阅的表。我做过好几个类似的项目文档整理工作最大的体会是正文写得好不好决定别人能不能看懂附录做得好不好决定别人能不能用起来。很多文档正文洋洋洒洒几万字附录就随便列几个参数完事结果用的人还是得回去翻正文。这份速查表的设计思路不一样它把三类信息做了明确分层附录C参数速查表面向调参场景。你已经在跑一个模型或者调一个接口了需要快速知道某个参数改大改小会有什么影响。附录D术语表面向读文档场景。你看到一个新词不确定它在这个项目里的确切含义需要一句话解释。附录E中文模型API上手面向从零接入场景。你还没开始写代码需要知道第一步干什么、第二步干什么。这三块内容看起来独立实际上有一条暗线串着参数是操作层术语是认知层API上手是执行层。操作层告诉你改什么认知层告诉你这是什么执行层告诉你怎么开始。三者缺一不可。提示如果你只想要参数速查表可以直接跳到第2节。但建议至少把第3节的术语表扫一遍因为很多参数名本身就是术语不理解术语很容易把参数用错。下面我按实际使用频率从高到低把这三块拆开讲。每一块都会补充正文里通常不会写的实操细节和踩坑经验。2. 附录C参数速查表的编排逻辑与使用方式2.1 为什么参数表不能只列名称默认值我见过很多参数速查表长这样参数名默认值说明temperature0.7温度max_tokens2048最大token数这种表能用但不好用。问题在于说明那一列太薄了。你看到temperature0.7知道它是温度但温度调高调低到底会怎样调到1.5会出什么问题调到0.1是不是就一定稳定这些信息表里没有你还是得回去翻正文。我的做法是给每个参数加三列调节方向、典型场景、边界警告。调节方向告诉你调大调小分别影响什么典型场景告诉你什么任务该用什么值边界警告告诉你超出什么范围会出问题。这样一张表的信息密度就上来了大部分情况下不用再翻正文。2.2 参数速查表的完整字段设计下面这张表是我在实际项目中反复迭代出来的字段结构你可以直接拿去用字段作用是否必填参数名代码中实际使用的键名必填类型string/int/float/bool/enum必填默认值不传时的行为必填取值范围合法区间或枚举列表必填调节方向调大/调小的效果建议填典型场景什么任务用什么值建议填边界警告超范围或极端值的后果建议填关联参数和哪些参数有联动选填关联参数这一列经常被忽略但实际上非常关键。比如temperature和top_p通常不建议同时调max_tokens和context_length之间有约束关系。这些联动关系如果不在表里标出来用的人很容易踩坑。2.3 中文模型常见参数的实际取值建议结合中文模型的实际使用经验我把几个核心参数的取值建议整理如下。这些值不是拍脑袋定的是经过多轮测试后收敛出来的经验区间参数保守值均衡值激进值适用说明temperature0.1-0.30.5-0.70.8-1.0中文生成任务建议不超过0.9top_p0.70.90.95和temperature二选一调max_tokens51220484096中文按1字≈1.5token估算frequency_penalty00.30.8中文重复问题比英文更明显presence_penalty00.20.6配合frequency_penalty使用这里重点说两个中文场景特有的经验第一中文的token估算和英文不一样。英文大概1个token对应0.75个单词中文大概1个汉字对应1.5到2个token。所以你设max_tokens2048实际能生成的中文大概在1000到1300字之间。如果你需要生成一篇2000字的中文文章max_tokens至少要设到3500以上。这个换算关系在英文文档里通常不会提但中文场景下必须知道。第二frequency_penalty对中文的影响比英文大。中文生成容易出现复读机现象同一个短语反复出现。把frequency_penalty从0调到0.3重复问题会明显改善。但注意不要调太高超过1.0之后语句会变得不自然出现大量同义词替换导致的语义漂移。2.4 参数速查表的维护节奏参数表不是做完就完了。模型版本更新、接口调整、新参数加入都会让表过期。我的建议是每次模型版本升级先跑一遍参数回归测试确认默认值和取值范围有没有变。在表头标注版本号和更新日期让用的人知道这份表对应哪个版本。把废弃参数单独列一个已废弃区块不要直接删掉因为老代码可能还在用。注意参数速查表最怕的不是不全而是过时。一个过时的默认值比没有默认值更危险因为用的人会以为它是对的。3. 附录D术语表的编写原则与中文模型特有术语3.1 术语表不是词典是项目内定义术语表最容易犯的错误是把通用词典的解释抄进来。比如token这个词通用解释是令牌但在模型语境下它指的是文本切分的最小单元。如果你在术语表里写token令牌读的人会更糊涂。术语表的正确写法是只解释这个词在本项目中的含义不解释它的通用含义。如果这个词在本项目中有特殊用法重点说明特殊之处。比如术语通用含义本项目含义token令牌文本切分的最小单元中文约1.5-2字符/tokencontext上下文模型单次调用能处理的最大token总量prompt提示输入给模型的完整文本含系统指令和用户输入completion补全模型生成的输出文本这样写的好处是读的人一眼就能看出哦这个词在这里是这个意思不会和通用含义混淆。3.2 中文模型场景下的高频术语拆解中文模型有一些英文文档里不常见、但中文场景下必须理解的术语。我挑几个最容易搞混的展开说上下文长度context length这个不是能记住多少轮对话而是单次请求的输入输出总token上限。很多人以为上下文长度是128K就能聊128K轮实际上如果你的输入已经占了100K输出最多只能有28K。而且注意上下文长度是输入和输出共享的不是各自独立。温度temperature这个名字很误导它和热度没关系。它控制的是概率分布的平滑程度。温度低概率分布尖锐模型倾向于选概率最高的词温度高概率分布平滑低概率词也有机会被选中。所以温度低不等于更准确只等于更保守。Top-p核采样从概率最高的词开始累加累加到累计概率达到p为止然后只从这个集合里采样。top_p0.9意味着只考虑累计概率前90%的词。它和temperature的区别是temperature调整的是分布形状top_p调整的是候选集大小。频率惩罚frequency penalty根据一个词在已生成文本中出现的次数来降低它的概率。出现越多惩罚越大。注意它惩罚的是已经出现过的词不是高频词。所以它解决的是重复问题不是词汇多样性问题。存在惩罚presence penalty只要一个词出现过就降低它的概率不管出现几次。它比频率惩罚更激进适合需要强多样性的场景。这两个惩罚项经常被搞混我做个对比维度frequency_penaltypresence_penalty惩罚依据出现次数是否出现惩罚力度随次数递增固定适用场景轻度去重强制多样性中文建议值0.2-0.50.1-0.33.3 术语表的交叉引用设计术语表还有一个实用技巧给每个术语加上相关术语和相关参数的交叉引用。比如上下文长度这个术语相关参数是max_tokens相关术语是token。这样读的人看到一个术语可以顺着引用链把相关概念一起理解了。交叉引用不需要很复杂在术语表里加一列参见就行术语解释参见上下文长度单次请求输入输出的token上限token, max_tokens温度控制概率分布平滑程度top_p, 采样频率惩罚按出现次数降低词概率存在惩罚, 重复问题这种设计在纸质文档时代不太现实但在电子文档里非常容易实现而且对读者的帮助很大。4. 附录E中文模型API上手的完整接入路径4.1 从零到跑通第一条请求的最短路径很多人第一次接中文模型API卡的不是代码是不知道先干什么。我把最短路径拆成五步拿到API Key这是身份凭证没有它什么都做不了。注意Key通常只在创建时显示一次务必立刻保存到安全的地方。确认接口地址endpoint不同平台的地址格式不一样有的带版本号有的不带。先确认清楚再写代码。选一个最简单的接口测试不要一上来就调最复杂的接口。先用最简单的文本生成接口跑通确认Key有效、网络通、返回格式对。用curl或Postman发一条请求在写代码之前先用命令行工具验证接口能通。这一步能排除掉大部分环境问题。再写代码封装确认接口通了之后再用Python或JavaScript封装成函数。这个顺序看起来简单但我见过太多人跳过第4步直接写代码结果报错了不知道是代码问题还是接口问题排查半天。4.2 用curl验证接口连通性的标准流程第一步永远是先用命令行验证。以OpenAI兼容格式的接口为例curl -X POST https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer YOUR_API_KEY \ -d { model: your-model-name, messages: [ {role: user, content: 你好请回复OK} ], max_tokens: 10 }这条命令做了几件事指定了接口地址、传了认证头、发了JSON格式的请求体、限制了最大输出token数。如果返回正常你会看到一个JSON结构里面有choices数组第一个元素的message.content就是模型的回复。如果报错按这个顺序排查错误码可能原因排查方向401Key无效或过期检查Key是否复制完整是否有多余空格403权限不足检查Key是否有该模型的调用权限404接口地址错误检查endpoint路径和版本号429请求频率超限降低请求频率或检查配额500服务端错误稍后重试或联系平台确认服务状态提示401和403是最常见的两个错误。401通常是Key本身的问题403通常是权限配置的问题。分清楚这两个能省很多排查时间。4.3 Python封装的实用写法curl验证通过之后用Python封装。我不建议直接用最原始的requests写因为要处理重试、超时、错误码这些事情。下面是一个经过实战检验的封装模板import requests import time from typing import Optional class ChatClient: def __init__(self, api_key: str, base_url: str, model: str): self.api_key api_key self.base_url base_url.rstrip(/) self.model model self.session requests.Session() self.session.headers.update({ Authorization: fBearer {api_key}, Content-Type: application/json }) def chat(self, prompt: str, max_retries: int 3, **kwargs) - Optional[str]: payload { model: self.model, messages: [{role: user, content: prompt}], **kwargs } for attempt in range(max_retries): try: resp self.session.post( f{self.base_url}/chat/completions, jsonpayload, timeout60 ) if resp.status_code 200: return resp.json()[choices][0][message][content] elif resp.status_code 429: wait 2 ** attempt time.sleep(wait) continue else: print(f请求失败: {resp.status_code} {resp.text}) return None except requests.exceptions.Timeout: print(f超时第{attempt1}次重试) continue return None这个封装有几个设计点值得说明第一用Session复用连接。每次请求都新建连接开销很大Session会自动复用TCP连接在高频调用场景下能明显降低延迟。第二429错误用指数退避重试。第一次等1秒第二次等2秒第三次等4秒。这是处理限流的标准做法比固定间隔重试更有效。第三超时设60秒。中文模型生成长文本时耗时较长超时设太短会频繁中断。60秒是个比较稳妥的值如果生成特别长的内容可以调到120秒。第四返回None而不是抛异常。在批量调用场景下单条失败不应该中断整个流程。返回None让调用方决定怎么处理。4.4 中文模型API调用的三个特有坑坑一编码问题。中文内容在传输过程中如果编码不对会出现乱码。确保请求头里Content-Type带charsetutf-8Python里用json参数而不是data参数requests会自动处理编码。坑二max_tokens设太小导致截断。中文的token密度比英文高同样长度的文本中文消耗的token更多。如果你按英文经验设max_tokens500中文可能只能生成200多字就截断了。中文场景建议至少设1024起步。坑三流式输出和普通输出的返回格式不同。普通输出一次性返回完整JSON流式输出是SSE格式每行一个data:开头的片段。如果你开了streamTrue但按普通格式解析会直接报错。流式解析需要逐行读取遇到data: [DONE]结束。def chat_stream(self, prompt: str, **kwargs): payload { model: self.model, messages: [{role: user, content: prompt}], stream: True, **kwargs } resp self.session.post( f{self.base_url}/chat/completions, jsonpayload, streamTrue, timeout120 ) for line in resp.iter_lines(): if not line: continue line line.decode(utf-8) if line.startswith(data: ): data line[6:] if data [DONE]: break import json chunk json.loads(data) delta chunk[choices][0][delta] if content in delta: yield delta[content]流式输出的好处是首字延迟低用户不用等全部生成完才看到内容。做对话类应用建议默认用流式。5. 三份附录的联动使用与版本管理5.1 参数、术语、API三者的实际联动场景单独看三份附录各自独立但实际使用中它们是联动的。我举一个真实场景你要做一个中文摘要功能。第一步查附录E找到文本生成接口的调用方式跑通第一条请求。第二步查附录C确认max_tokens设多少合适——摘要任务输出通常不超过输入的三分之一如果输入是2000字输出大概600字按中文1.5token/字算max_tokens设1000够了。第三步查附录D确认摘要任务在术语表里有没有特殊定义比如是否要求保留原文关键实体。这个流程走下来三份附录各用了一次而且顺序是固定的先API跑通再参数调优最后术语确认。这个顺序不是随便定的它对应的是从能跑到跑得好再到跑得对的递进关系。5.2 版本更新时的同步维护三份附录最大的维护风险是不同步。比如模型升级了参数默认值变了但术语表里还写着旧的定义或者API接口地址变了但参数表里引用的还是旧地址。我的做法是给三份附录加一个统一的版本号放在每份附录的开头附录C 参数速查表 版本v2.3 对应模型版本model-2024-06 最后更新2024-06-15三份附录的版本号必须一致。每次更新时先确认哪些内容变了然后同步更新三份附录的版本号。如果只有一份变了其他两份也要更新版本号哪怕内容没变因为版本号代表的是这一组附录的整体状态。5.3 常见维护问题对照表问题表现处理方式参数默认值过期按表里的值调用报错每次模型升级后跑回归测试术语定义和正文不一致读者反馈看不懂术语表以正文为准定期对齐API地址变更调用返回404关注平台公告及时更新新增参数未入表用的人不知道有这个参数版本更新时对比接口文档废弃参数未标注老代码还在用废弃参数单独列已废弃区块标注替代方案这张表里的每一条我都实际遇到过。最麻烦的是术语定义和正文不一致因为这种问题不会报错只会让读者困惑。我的经验是术语表的定义必须比正文更简洁但不能和正文矛盾。如果正文说上下文长度是输入上限术语表就不能说上下文长度是输入输出上限哪怕后者更准确也要先改正文再改术语表。6. 我在实际使用中总结的几条经验先说一个反直觉的结论速查表的价值不在于快而在于准。很多人做速查表追求一页纸装下所有参数结果每个参数只有一行说明用的人看完还是不确定该怎么设。我宁愿速查表多几页也要把每个参数的调节方向和边界警告写清楚。快是次要的准是主要的。第二条经验是关于术语表的。术语表里最该写的不是这个词是什么意思而是这个词容易和什么混淆。比如temperature和top_p容易混frequency_penalty和presence_penalty容易混context length和max_tokens容易混。把这些容易混的术语放在一起对比比单独解释每个术语有用得多。第三条是关于API上手的。第一次接入时不要用生产环境的Key做测试。很多平台有测试专用的Key或者沙箱环境用测试Key跑通流程确认没问题再换生产Key。我见过有人直接用生产Key测试结果测试请求把配额用完了正式上线时反而没额度了。最后分享一个小的检查习惯每次更新完附录我会随机抽三个参数、三个术语、三个接口假装自己是第一次用的读者看能不能在不翻正文的情况下理解。如果有一个卡住了说明那份附录还需要补。这个习惯帮我发现了很多自己觉得写清楚了、但别人看不懂的地方。