附录：附录：LLM 应用开发速查手册

zjc 于 2026-02-01 发布

这是《LLM 应用开发零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。

核心链路

基础调用：API -> Prompt -> 结构化输出 -> 校验
RAG：解析 -> 切块 -> Embedding -> 混合检索 -> Rerank -> 引用
Agent：目标 -> 状态 -> 工具 -> 预算 -> 审计 -> 停止
治理：数据集 -> 评测 -> 护栏 -> 权限 -> 观测 -> 灰度

API 检查项

项目	要点
认证	密钥来自环境或密钥系统
超时	外层大于内层
重试	只重试可重试错误
限流	指数退避加抖动
流式	处理取消和分片重组
停止原因	检查 `length`、`tool_calls`
成本	记录 input/output tokens
观测	trace、模型版本、Prompt 版本

Prompt 模板

角色：...
任务：...
输入：...
规则：
1. ...
2. ...
输出格式：...
不确定时：...

发布前检查：

输出 schema 明确；
示例覆盖边界；
不放秘密；
资料与指令隔离；
允许信息不足；
版本化；
有回归评测。

结构化输出校验

模型输出
  -> JSON 提取
     -> schema 校验
        -> 枚举 / 范围 / 关系校验
           -> 业务权限校验
              -> 确认 / 写入 / 审计

关键点：

confidence 不等于真实概率；
关键字段用数据库验证；
JSON 修复最多一次；
模型输出不能直接拼接 SQL；
关键动作要审批。

RAG 检查表

环节	检查
解析	标题、表格、OCR、页码
切块	语义完整、父子块、overlap
向量	模型版本、维度、索引版本
检索	向量 + BM25 + 元数据过滤
重排	候选数、延迟、端到端收益
上下文	token 预算、去重、引用
生成	忠实上下文、资料不足拒答
校验	chunk、quote、权限、时间

Agent 检查表

目标是否明确
工具是否最小权限
参数是否校验
预算是否有限
停止条件是否清楚
状态是否可恢复
重复调用是否检测
高危动作是否审批
trace 是否完整
失败是否可降级

安全清单

身份、租户、角色服务端确认；
检索和工具权限硬过滤；
高危工具独立审批；
敏感字段脱敏；
外部文档视为数据而非指令；
输出过滤和引用校验；
注入、越权、泄露用例进入 CI；
审计日志可回放；
护栏配置版本化；
安全事件可快速回滚。

评测指标

类别	指标
检索	Recall@K、MRR、NDCG
生成	Correctness、Faithfulness、Relevance
引用	Citation Accuracy
结构化	Parse Rate、Schema Pass Rate
Agent	Task Success、Tool Accuracy、Loop Rate
安全	Injection Block、Leakage Zero
工程	TTFT、p95、错误率、成本
业务	解决率、转人工率、采纳率

发布清单

单元测试通过
离线评测通过
安全用例通过
权限测试通过
回放样本通过
成本预算确认
SLO 确认
灰度计划确认
回滚方案确认
负责人和告警确认

常见故障速查

现象	优先排查
JSON 解析失败	finish_reason、Prompt、schema
编号查不到	BM25 或数据库精确查询
答案引用错	chunk 映射、quote 校验
新旧政策冲突	effective_time、索引版本
跨用户数据	权限过滤、缓存键
首字慢	输入长度、模型负载
总耗时高	输出长度、工具串行
成本突增	重试、Agent 循环、上下文
语义缓存错答	相似度阈值、时间敏感
工具不调用	工具描述、schema、模型能力

附录：附录：LLM 应用开发速查手册

核心链路

API 检查项

Prompt 模板

结构化输出校验

RAG 检查表

Agent 检查表

安全清单

评测指标

发布清单

常见故障速查

推荐工程习惯