附录 C+D+E 参数速查表 · 术语表 · 中文模型 API 上手

本篇是《AI Agent 实战：从设计模式到生产落地》的附录 C + D + E 合集：参数速查表 + 术语表 + 中文模型 API 快速上手，建议收藏当手册用。

---

附录 C：参数速查表

本附录是第 24 章《参数体系与调优》的三表合一速查版（模型参数 / Agent 引擎参数 / 企业级配置参数）。完整讲解见第 24 章正文与《参数调优速查表-第24章样章.md》。 使用提示：表中数值为经验基线，上线前以各模型最新文档为准，并在自有评测集上验证。

C.1 模型调用常用参数

参数	作用	范围	默认	调大 →	调小 →	注意
temperature	输出随机性	0~2	1.0	更发散/易幻觉	更确定/可复现	与 top_p 二选一
top_p	核采样截断	0~1	1.0	词汇池更大	更聚焦	与 temperature 互斥
top_k	前 K 候选	1~数百	视模型	更多候选	更保守	OpenAI 系不支持
max_tokens	最大输出长度	1~上限	视模型	更长	更省/更快	企业级必须设置
stop	停止序列	数组	空	---	---	结构化输出收尾
frequency_penalty	频率惩罚	-2~2	0	抑制重复	更易重复	代码/JSON 用 0
presence_penalty	话题惩罚	-2~2	0	新话题	守话题	客服可 +0.3~0.6
seed	随机种子	整数	无	---	---	不保证完全复现
stream	流式	bool	false	---	---	交互开/后台关
response_format	输出格式	text/json	text	---	---	首选 json_schema

C.2 按任务类型的推荐基线

任务	典型场景	temperature	top_p	说明
抽取/结构化	实体抽取、JSON	0~0.2	0.1~0.3	配 json_schema
问答/知识库	RAG、客服	0.3~0.5	0.5~0.9	平衡忠实与自然
决策/规划	计划、路由	0~0.3	0.3~0.7	可加 self-consistency
代码生成	补全、工具参数	0.1~0.3	0.5~0.9	工具调用 ≈0
创意写作	文案、故事	0.7~1.0	0.9~1.0	需要多样性
翻译/改写	互译、润色	0.3~0.5	0.7~0.9	忠实度优先
总结/摘要	长文总结	0.2~0.4	0.7~0.9	防漏关键信息
多步推理	数学、逻辑	0~0.2	0.3~0.7	配合 CoT/ReAct

C.3 中文模型参数差异对照

能力	DeepSeek-V3	DeepSeek-R1	Qwen	豆包	混元	GPT/o 系
temperature	✅	⚠️ 建议不调	✅	✅	✅	✅
top_p	✅	⚠️	✅	✅	✅	✅
top_k	✅	✅	✅	✅	⚠️	❌
seed	⚠️	⚠️	✅	✅	⚠️	✅ beta
response_format	✅ json	⚠️	✅	✅ json	✅	✅ schema
推理输出	思维链	reasoning_content	可配思考	可配思考	⚠️	o 系 reasoning
上下文（约）	128K	128K	32K~1M	128K~256K	256K~1M	128K~1M

跨模型迁移 3 铁律 ：① 推理模型不调温度/penalty；② top_k 迁到 OpenAI 系前必须去掉；③ json 输出优先 json_schema。

C.4 Agent 引擎参数

参数	含义	推荐基线	调优方向
max_iterations	最大循环轮数	简单 35 / 多步 810 / 复杂 15~20	卡死调小；未完成查根因
max_tool_calls	单轮工具调用	3~8	频繁失败检查工具质量
tool_choice	工具选择	auto/required/none	流水线 required；问答 none
parallel_tool_calls	工具并行	true	有依赖 false；独立 true
工具重试	失败重试	2~3 次 + 1s/2s/4s 退避	过多加熔断
单工具超时	单次调用超时	5~30s 按类型	外部 API 10s+，本地 5s
端到端超时	任务整体	30120s / 复杂 510min	超出降级返回部分
上下文分配	系统/历史/工具/输出	系统≤10%、工具≤20%、输出留 30%	溢出压缩或转 RAG
记忆保留	短期记忆轮数	8~12 轮	频繁遗忘提炼摘要
子 Agent 数	多智能体并发	3~5（单任务）	过多通信开销大
聚合等待	Fan-in 等待	2~5s 或最长子任务 80%	尾部敏感缩短

C.5 企业级配置清单（A-G 七类速查）

⚠️ = 强烈建议必须配置。完整版含每项的风险评估与适用场景，见第 24 章 24.4。

A. 容量与限流

#	配置项	推荐值
A1 ⚠️	QPS 上限	配额 60%~70%
A2 ⚠️	并发上限	连接池 + 信号量
A3	排队策略	令牌桶 + 队列 ≤1000
A4	请求优先级	关键任务插队
A5	按租户配额	QPS/日预算

B. 弹性与降级

#	配置项	推荐值
B1 ⚠️	熔断阈值	连续失败≥5 / 错误率≥30%（10s）
B2 ⚠️	降级响应	兜底话术/缓存/简化流程
B3 ⚠️	备用模型 failover	主失败切备选
B4	慢启动恢复	半开探测渐进放量

C. 缓存策略

#	配置项	推荐值
C1	结果缓存	相同输入 TTL 5~60min
C2	语义缓存	相似度≥0.95
C3 ⚠️	Prompt 缓存	固定系统提示开 KV Cache
C4	会话缓存	Redis 存会话状态
C5	缓存失效	数据变更主动失效

D. 稳定性与超时

#	配置项	推荐值
D1 ⚠️	连接超时	5~10s
D2 ⚠️	首 Token 超时	10~30s
D3 ⚠️	总时长超时	30s~5min 按任务
D4	重试策略	1s/2s/4s 退避+抖动 ≤3 次
D5	幂等键	idempotency-key
D6	任务队列	长任务异步化

E. 安全参数

#	配置项	推荐值
E1 ⚠️	内容审核	出入双向
E2 ⚠️	提示注入检测	工具输入/输出双侧
E3 ⚠️	PII 脱敏	正则+模型识别
E4	工具白名单	仅暴露必需
E5	输出过滤	敏感词/URL 拦截
E6	角色权限 RBAC	工具调用鉴权

F. 可观测性

#	配置项	推荐值
F1 ⚠️	全链路追踪	每步 trace
F2	采样率	默认 100%，高流量 10%
F3 ⚠️	Token 计量	输入/输出/缓存分计
F4	告警阈值	错误率>5% / P95>3s / 成本日增>50%
F5	质量指标	人工抽评 + LLM-as-Judge
F6	会话回放	关键会话存储

G. 配置管理

#	配置项	推荐值
G1 ⚠️	配置中心	Apollo/Nacos/自建
G2 ⚠️	环境隔离	dev/staging/prod 分离
G3	灰度参数	按比例/租户
G4	版本化	变更留痕可回滚
G5	预算封顶	日/月 Token 自动熔断

C.6 调优决策树（快速索引）

幻觉/编造     → temperature↓ + RAG 约束 + json_schema + Judge 抽评
重复/复读     → frequency_penalty↑ (0→0.5~1.0)
上下文溢出    → 压缩历史 + 记忆条数↓ + 超长转 RAG
Agent 卡死    → max_iterations↓ + trace + 完成判断步骤
工具参数乱填  → temperature→0 + 严格 Schema + 结果校验
成本爆炸      → max_tokens 上限 + Prompt 缓存 + 小模型路由
响应太慢      → stream + max_tokens↓ + 并行化 + 更快模型

C.7 调优五步法

[1 基线建立] 固定评测集（≥50 条）+ 指标基线
[2 单因素]   一次只改 1 个参数，跑全量评测集
[3 组合]     敏感参数 2~3 维扫描（网格/贝叶斯）
[4 回归]     独立验证集确认无退化
[5 灰度]     10% → 观察 → 全量（24~48h）

调参铁律：一次只改一个变量；所有变更记录进实验模板；上线前过评测集回归（第 20 章）。

---

附录 D：术语表

本书核心术语速查，按主题分组。括注内为首次详述章节。

D.1 基础概念

术语	全称/英文	一句话解释	章节
LLM	Large Language Model	大语言模型：理解/推理/生成的"大脑"	2
Token	---	模型处理文本的最小单位（约 1 汉字 ≈ 1~2 token）	3
上下文窗口	Context Window	模型单次能"同时看到"的最大 token 数	3
注意力机制	Attention	模型处理某词时"看向"上下文相关词的能力	2
预训练	Pre-training	大规模文本上预测下一个词，获得语言知识	2
SFT	Supervised Fine-Tuning	指令微调：让模型"会听话"	2
RLHF	RLHF	人类反馈强化学习：让模型"会做对"	2
KV 缓存	KV Cache	缓存已处理上下文，加速重复前缀推理	2
幻觉	Hallucination	模型编造不存在的知识/事实	13、17
提示注入	Prompt Injection	恶意指令混入输入，诱导模型非预期行为	22

D.2 Agent 核心

术语	英文	一句话解释	章节
Agent	AI Agent	LLM + 工具 + 自主循环的智能体	1、6
Agent Loop	---	思考→行动→观察的循环引擎	6
Tool Calling	Function Calling	模型输出结构化"函数调用意图"	5
工具	Tool	模型可调用的外部函数/API	14
Skill	---	提示词+工具+流程的可复用封装	19
MCP	Model Context Protocol	工具接入的标准化协议	7
RAG	Retrieval-Augmented Generation	检索增强生成：带资料回答问题	8
Harness	---	质量与安全保障框架	20
Guardrail	---	输入/输出侧的护栏	17
Sub-Agent	---	作为"工具"临时启用的子智能体	16
Supervisor	---	多智能体的主管（拆解/派活/汇总）	16

D.3 设计模式（第 IV 部分）

术语	英文	一句话解释	章节
提示链	Prompt Chaining	有序子任务流水线	10
路由	Routing	按输入分发到不同处理分支	11
并行化	Parallelization	独立子任务同时执行后聚合	12
反思	Reflection	生成后自我检查与修正	13
工具增强	Tool Augmentation	用外部工具扩展模型能力	14
规划	Planning	先出计划再执行（Plan-and-Execute）	15
ReAct	Reason + Act	思考行动交错的单循环范式	15
多智能体	Multi-Agent	多个角色 Agent 协作	16
自检	Self-check	输出交付前的分层校验	17
学习	Learning	从反馈中持续改进	18
Self-consistency	---	多次独立推理投票取多数	4、12

D.4 推理与提示技术

术语	英文	一句话解释	章节
CoT	Chain-of-Thought	思维链：引导模型写出推理过程	4
Few-shot	---	用少量示例校准模型输出	4
Zero-shot	---	无示例直接提问	4
JSON Schema	---	结构化输出的字段约束	4
temperature	---	输出随机性参数	24
top_p / top_k	---	采样截断参数	24

D.5 工程与运维

术语	英文	一句话解释	章节
评测集	Eval Set	标注好的测试问题集	20
基线	Baseline	改动前的评测分数基准	20
LLM-as-Judge	---	用模型当评测器	17、20
灰度发布	Canary Release	小流量验证后全量	20
可复现率	---	同一输入失败的可复现比例	21
Trace	---	一次任务的全链路调用记录	21
RBAC	Role-Based Access Control	基于角色的权限控制	22
沙箱	Sandbox	隔离代码执行环境	22
熔断	Circuit Breaker	连续失败后停止调用	24
指数退避	Exponential Backoff	重试间隔成倍增长	24
PII	Personally Identifiable Info	个人身份信息（需脱敏）	22
AAIF	---	AI 治理框架	22

D.6 检索与记忆

术语	英文	一句话解释	章节
分块	Chunking	长文本切块	8
Embedding	---	文本向量化（语义数字表示）	8
向量检索	Vector Search	按语义相似度检索	8
混合检索	Hybrid Search	向量 + 关键词融合检索	8
重排	Rerank	用 Cross-Encoder 精排检索结果	8
RRF	Reciprocal Rank Fusion	多路检索结果排名融合	8
命中率	Recall@K	检索到正确资料的比率	8
忠实度	Faithfulness	回答忠实于资料的程度	8
长期记忆	Long-term Memory	跨会话持久化记忆	9

D.7 快速查找索引

想找	术语
模型答错/编造	幻觉 / 反思 / 自检
模型不会调用工具	Tool Calling / 工具增强
工具太多接入乱	MCP
长文档处理	RAG / 分块 / 重排
Agent 记不住	上下文窗口 / 长期记忆
Agent 卡死	Agent Loop / 停止条件 / 可复现率
多 Agent 混乱	多智能体 / Supervisor / 上下文隔离
上线怕退化	评测集 / 基线 / 灰度发布
被攻击	提示注入 / Guardrail / 沙箱
太贵太慢	temperature / 熔断 / 缓存 / 量化

---

附录 E：中文模型 API 快速上手

本附录给出 DeepSeek / Qwen / 豆包三大中文模型的 API 快速接入示例（OpenAI 兼容接口）。完整参数与选型见第 2、24 章。

E.1 通用约定（OpenAI 兼容）

三家主流中文模型均提供 OpenAI 兼容接口 ------只需改 base_url 和 api_key，代码可复用：

from openai import OpenAI

client = OpenAI(
    base_url="<各家的 base_url>",
    api_key="<你的 key>",
)

建议：代码里统一用 OpenAI SDK，把 base_url/key 放环境变量，换模型只改配置不动代码（第 2 章"协议先行"原则）。

E.2 DeepSeek（深度求索）

基本信息

项	值
Base URL	https://api.deepseek.com
对话模型	deepseek-chat（V3）
推理模型	deepseek-reasoner（R1）
兼容性	OpenAI 兼容

基础调用

from openai import OpenAI

client = OpenAI(base_url="https://api.deepseek.com", api_key="<key>")

resp = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是客服助手"},
        {"role": "user", "content": "我的订单到哪了？"},
    ],
    temperature=0.3,
    max_tokens=1000,
)
print(resp.choices[0].message.content)

推理模型调用（R1）

resp = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user", "content": "鸡兔同笼，头35脚94？"}],
    # 注意：推理模型不调 temperature（第24章表三）
)
print(resp.choices[0].message.content)        # 最终答案
# 推理过程在 reasoning_content（部分版本）
# print(resp.choices[0].message.reasoning_content)

结构化输出

resp = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "抽取差评要点，输出 JSON"}],
    response_format={"type": "json_object"},
    temperature=0.1,
)

E.3 通义千问 Qwen（阿里）

基本信息

项	值
Base URL	https://dashscope.aliyuncs.com/compatible-mode/v1
对话模型	qwen-plus / qwen-turbo（小模型）
开源系列	Qwen2.5 / Qwen3（可私有化）
兼容性	OpenAI 兼容

基础调用

from openai import OpenAI

client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="<dashscope key>",
)

resp = client.chat.completions.create(
    model="qwen-plus",
    messages=[{"role": "user", "content": "介绍一下 RAG"}],
    temperature=0.3,
)
print(resp.choices[0].message.content)

小模型路由（第 11 章模型路由）

def route_model(complexity):
    # 简单任务走 qwen-turbo（便宜快），复杂走 qwen-plus
    return "qwen-turbo" if complexity == "simple" else "qwen-plus"

长窗口（Qwen 大窗口版本）

resp = client.chat.completions.create(
    model="qwen-long",          # 或 qwen-max（视版本）
    messages=[{"role": "user", "content": long_doc}],   # 支持超长输入
    max_tokens=2000,
)

E.4 豆包 Doubao（字节）

基本信息

项	值
平台	火山方舟（Volcano Ark）
Base URL	https://ark.cn-beijing.volces.com/api/v3
模型	通过"推理接入点 ID"（endpoint id）调用
兼容性	OpenAI 兼容

基础调用（通过接入点 ID）

from openai import OpenAI

client = OpenAI(
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    api_key="<火山方舟 key>",
)

resp = client.chat.completions.create(
    model="ep-20260807-xxxxx",      # 推理接入点 ID（控制台创建）
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

结构化输出

resp = client.chat.completions.create(
    model="ep-xxxxx",
    messages=[{"role": "user", "content": "输出 JSON"}],
    response_format={"type": "json_object"},
)

E.5 一键切换方案（配置驱动）

# config.py：模型配置统一管理
MODEL_CONFIG = {
    "deepseek": {"base_url": "https://api.deepseek.com", "model": "deepseek-chat"},
    "qwen":     {"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
                 "model": "qwen-plus"},
    "doubao":   {"base_url": "https://ark.cn-beijing.volces.com/api/v3",
                 "model": "ep-xxxxx"},
}

def get_client(provider="deepseek"):
    cfg = MODEL_CONFIG[provider]
    return OpenAI(base_url=cfg["base_url"], api_key=os.environ[f"{provider.upper()}_KEY"])

# 使用时
client = get_client("deepseek")    # 换模型 = 换一个字符串

迁移注意（第 24 章表三）：

• 推理模型（DeepSeek-R1）不调 temperature/penalty
• top_k 参数部分模型不支持，迁移时检查
• 各模型 JSON 输出支持度不同，用前验证 response_format

E.6 快速排错（API 接入常见问题）

现象	原因	解决
401 认证失败	key 错误/未生效	检查 key、确认环境变量加载
404 模型不存在	模型名/接入点 ID 错误	核对模型名（E.2-E.4 表格）
429 限流	配额超限	加退避重试（第 24 章 D4）
400 参数错误	参数不支持	检查 top_k 等（第 24 章表三）
超时	网络/长上下文	分层超时（第 24 章 D1-D3）