AI 工程的 100 个实战经验——老张精选
AI 工程的 100 个实战经验——老张精选
适读人群：AI应用开发者、想系统提升的工程师 | 阅读时长：约20分钟 | 核心价值：1400多篇文章和真实项目里提炼的100条，每条都有来历
写这篇文章之前，我翻了一下自己的项目笔记、踩坑记录和过去几年的文章。
这100条，每一条背后都有一个具体的场景：有些是我自己踩过的坑，有些是我帮客户排查问题时发现的规律，有些是反复在不同项目里被验证的判断。没有一条是从网上抄来再润色的。
简短精炼，不展开。要展开的，以前的文章里大多写过。
RAG 工程（1-25）
1. chunk大小不是越小越好，太小会破坏语义完整性，太大会引入噪音。没有通用最优值，只有针对你的文本类型的最优值——试出来，不要猜。
2. overlap的作用不是"多一点保险"，是保证跨chunk的语义连续性。如果你的文本本来就是独立段落，overlap可以设为0。
3. 召回数量（top-k）设太少，漏答案；设太多，上下文窗口被噪音塞满，反而降低答案质量。5-8是大多数场景的合理起点。
4. 查询改写（query rewriting）是提升召回质量投入产出比最高的优化，比换更好的embedding模型更有效，且成本低。
5. 混合检索（向量+BM25关键词）几乎在所有场景下都比纯向量召回效果好，但实现复杂度更高。如果项目对效果有较高要求，值得做。
6. 文档元数据是被严重低估的优化维度。给每个chunk附上来源文件名、章节信息、时间戳，在过滤和排序时用处极大。
7. 重排序（reranking）是召回后的重要一步，用更小但更精准的模型对top-k结果重排。Cohere reranker或BGE reranker都是常用选择。
8. 评估RAG系统效果，不能只看主观感受，要建立测试集：一批真实问题+对应的标准答案，定期跑评估。
9. RAG系统上线前，必须测试"这个问题的答案不在文档里"的情况。如果AI在没有相关上下文时还是编出了看起来合理的答案，这是高危行为。
10. embedding模型的选择，领域相关性比通用benchmark分数更重要。法律文本用通用embedding效果可能远不如专门微调的法律embedding。
11. 向量数据库的选型，99%的项目早期用Chroma或者FAISS就够了，不需要一上来就上Pinecone或者Milvus。等规模真正成为问题再迁移。
12. 增量更新文档时，要处理已删除文档的向量清理，否则召回到已删除内容会产生幻觉。
13. 长文档先做摘要，再对摘要做embedding，通常比直接对全文做chunking后embedding效果更好（对"找整体信息"类查询）。
14. 多路召回后的融合策略（Reciprocal Rank Fusion, RRF）比简单的分数合并更鲁棒。
15. 对于表格、代码、公式等结构化内容，纯文本chunk的效果很差，需要专门的处理逻辑。
16. RAG的幻觉问题，很多时候不是生成模型的问题，是召回的内容本身有噪音。先查召回，再查生成。
17. 多语言场景，embedding模型必须支持多语言，否则跨语言召回会失效。
18. 给用户展示信息来源，是RAG产品里被低估的功能。用户会更信任能溯源的答案。
19. 上下文窗口是宝贵资源。不要把召回的内容全部塞进去，要选择性地使用最相关的部分。
20. Prompt里的上下文注入顺序有影响：相关度最高的内容放在开头或结尾，不要放在中间（大模型对中间内容的注意力会衰减）。
21. 定期对你的向量库做清洗，删除低质量文档和重复内容，比持续添加内容更重要。
22. 如果你的文档有明确的结构（章节、条款），利用这个结构做层次化召回，比平铺所有chunk效果好。
23. RAG在需要综合多处信息给出答案的问题上效果差。这类问题的答案不在某一个chunk里，而是需要跨多个chunk推理，是当前RAG的天花板。
24. 用户的真实查询和你测试时用的查询往往差距很大。上线后要持续收集真实查询，用它们来优化。
25. 在prompt里明确告诉模型：如果上下文里没有足够信息，就说没有，不要编。这一句话能显著降低幻觉率。
Agent 工程（26-50）
26. Agent失败的最常见原因不是工具用错，而是任务理解错了。把任务拆解成明确的子步骤，比给更多工具更有效。
27. 工具的描述比工具本身更重要。模型是根据工具描述决定用哪个工具的，描述含糊或者有歧义，工具调用就会出问题。
28. 给Agent的工具不是越多越好。工具数量超过10个，模型选择工具的准确率会显著下降。保持工具精简。
29. 长链任务必须有中间状态保存机制。任何一步失败，不应该从头开始，而是从最近的checkpoint继续。
30. 对于有外部副作用的操作（发邮件、写文件、调API），在执行前加人工确认节点，特别是在产品早期。
31. Agent的错误处理要明确。工具调用失败时，告诉模型失败原因和可以尝试的替代方案，不要只返回错误码。
32. 多Agent协作的最大挑战不是通信，是任务边界的定义。哪个Agent负责什么，必须清晰，不然会出现重复工作或互相推诿。
33. ReAct（Reason + Act）框架的推理步骤是可以审计的，这对调试Agent行为非常有用。不要用黑盒的Agent框架，要看到每一步的思考。
34. Agent的计划阶段和执行阶段要分开。先让模型生成一个完整的执行计划，review计划没问题再执行，比边想边做更可控。
35. 递归或者循环依赖会让Agent陷入无限循环。必须有最大步数限制，到达上限就停止并报告。
36. 给Agent提供的上下文信息越精确，幻觉越少。与其给长段落，不如给结构化的键值对。
37. 工具的返回值要结构化，不要返回原始的自然语言文本。模型处理结构化数据更可靠。
38. Agent做的每一个决策都要有日志。生产环境里出了问题，这些日志是你唯一的调试依据。
39. 对于需要精确数字计算的步骤，不要让LLM做，调用代码执行工具。LLM的数学不可靠。
40. 多步骤任务里，每一步的输出质量都会影响下一步。早期步骤的小错误会被后续步骤放大。
41. 给Agent的system prompt要包含它的角色定义、能力边界、以及明确的不该做什么。
42. 在Agent任务开始前，先做一个"可行性检查"：这个任务在我的工具集和权限范围内可以完成吗？如果不行，提前报错。
43. Agent的重试逻辑要有上限，要有退避策略。无脑重试是在烧钱而不是在解决问题。
44. 把Agent的任务范围设窄一些，比设宽但边界模糊要好。宁可多建几个专用Agent，也不要一个什么都能做但都做不好的Agent。
45. 测试Agent时，要覆盖边界情况：信息不全时怎么处理、工具都不适用时怎么处理、任务有内在矛盾时怎么处理。
46. 生产Agent要监控token消耗，长链任务容易因为上下文累积导致单次调用费用暴涨。
47. 用户对Agent的信任是渐进建立的。不要一开始就让Agent有完全的自主权，先从低风险操作开始，建立信任再扩大权限。
48. Agent框架（LangChain, LlamaIndex, CrewAI等）选型要慎重，框架抽象层多了你反而不知道发生了什么。在充分理解底层逻辑之前，手写比用框架更可控。
49. 对于需要并发执行多个工具调用的场景，异步执行能显著提升效率，但要注意工具之间的依赖关系。
50. 把Agent的"为什么这样做"和"做了什么"分开记录。前者帮助你理解模型的推理，后者帮助你审计执行结果。
成本控制（51-65）
51. 提示词的token数是可以主动控制的成本。删掉废话，你的API费用就降了，而且输出质量通常也会提升。
52. 缓存相同的请求结果，对于有重复查询场景的应用，能减少30-60%的API调用。
53. 流式输出（streaming）是用户体验的优化，不是成本优化。用流式不会减少token消耗。
54. 在不需要高智能的步骤用小模型，在确实需要推理能力的步骤用大模型。混用模型是成本控制的核心策略。
55. 批量处理（batch API）能显著降低成本，适合不需要实时响应的任务。OpenAI、Anthropic都有batch API，通常有50%折扣。
56. 评估你的任务是否真的需要最强的模型。很多任务用GPT-4o-mini或者Claude Haiku就够了，用Opus级别是在浪费钱。
57. 对上下文长度设上限，不要无限累积对话历史。超过一定长度做摘要压缩，不要把整个对话全部送进去。
58. 定期分析你的API账单，找出哪些调用的token消耗异常高，这些地方通常有优化空间。
59. 本地运行小模型处理低敏感度、低复杂度的任务，减少云端API的调用量。
60. 向量数据库的查询成本通常被低估，高频率的相似性搜索会快速累积成本。
61. 用prompt缓存（如Anthropic的prompt caching）对高频使用的长system prompt，能降低重复token的成本。
62. 在开发阶段，用mock数据测试业务逻辑，不要每次调试都打真实API。
63. 设置API调用的费用告警，避免因为Bug导致无限循环调用产生意外账单。
64. 对于确定性高的任务（如格式转换、信息提取），微调小模型通常比每次用大模型成本更低、效果更稳定。
65. 成本优化要有基准线。没有测量就没有优化，先知道你现在的成本结构是什么，再针对性地优化。
安全与可靠性（66-80）
66. 永远不要把用户输入直接拼接进system prompt，这是prompt注入的标准入口。
67. 对模型的输出做格式验证，在发送给用户之前。模型不是100%按照你期望的格式输出的。
68. 不要在prompt里包含真实的API key、密码、内部URL。测试也一样。
69. 给AI应用做输出过滤，过滤有害内容、敏感信息泄露的情况。不能完全依赖模型的内置安全机制。
70. 速率限制不只是防滥用，也是防止意外的循环调用把账户掏空。
71. 在RAG系统里，上传文档的用户能不能访问其他用户上传的内容？这是数据隔离问题，容易被忽视。
72. 记录用户对AI输出的反馈（点赞/踩/投诉），这是发现安全问题和质量问题的早期信号。
73. 对于生成代码的场景，在沙箱环境里运行，不要直接在生产服务器上执行。
74. AI系统的故障模式要提前想清楚：API不可用时、模型输出格式不符时、上下文长度超出时，系统怎么降级？
75. 对模型输出做幂等性测试：同一个输入，多次输出是否一致？对于要求确定性的场景，这是重要的质量指标。
76. 用户数据在送给第三方API之前，要做脱敏处理，特别是个人身份信息。
77. 测试越界场景：用户试图让AI做不该做的事，系统的拒绝逻辑是否工作？
78. 对关键业务路径做AI输出的人工审计，特别是系统刚上线的前几周。不能因为是AI就不审。
79. 为AI系统建立回滚机制，当AI行为异常时，能快速切换到规则系统或者降级版本。
80. "AI说的，不是我说的"不是免责理由。你的产品对AI输出负责。
团队与协作（81-100）
81. AI工程师和传统后端工程师的协作断层通常在于：后端认为AI调用就是一个API调用，AI工程师知道prompt工程是真实的工程工作。提前对齐这个认知。
82. Prompt是代码，要用版本控制管理，要有Code Review，不能在生产环境随便改。
83. 对模型的评估结果要形成文档，记录哪个版本的prompt在哪个测试集上的效果是多少，避免"感觉"替代数据。
84. AI产品的产品需求文档要包含：AI负责什么、AI不负责什么、失败情况下的降级方案。
85. 对非技术的产品经理和业务方设定合理的AI能力预期，过度承诺是大坑。
86. 建立内部的AI测试用例库，每次迭代跑一遍，避免改了新问题引入了旧问题。
87. "AI做不到这个"不是结束，而是问题定义的开始。要搞清楚为什么做不到，是模型能力、数据质量、还是任务定义的问题。
88. 代码Review里应该包含对AI集成部分的Review，包括prompt设计的合理性。这需要团队有人有这方面的经验。
89. 记录每次AI系统出生产问题的复盘文档，时间久了你会发现有规律。
90. 对外的AI功能上线，做小流量灰度而不是全量发布，特别是第一次。
91. 确保团队里有人持续关注模型供应商的更新——API变化、模型能力变化、价格变化——这些都会影响你的系统。
92. AI技术更新快，但团队学习能力是最重要的资产，比任何具体的技术栈都持久。
93. 内部的AI应用要收集用户使用数据，不是为了监控，是为了理解用户真实行为和产品优化。
94. 向业务方解释AI的局限，要用业务语言而不是技术语言。"模型幻觉"对他们没意义，"AI会偶尔给出看起来合理但实际错误的信息，所以高风险决策需要人工复核"更有效。
95. 对AI工程的估时要留Buffer，因为调优迭代的时间几乎无法在项目初期准确估计。通常翻一倍是合理的。
96. 不同团队成员对AI能力的理解差距可能很大。定期分享内部学习，比引进一个"AI专家"更可持续。
97. 在项目结束后，整理一份"这个AI应用我们学到了什么"的文档。这是公司层面最有价值的知识积累。
98. 当AI的输出被直接用在对外沟通（客服回复、邮件、报告）时，必须有人工审核机制，不能完全自动化。
99. 对AI供应商不要单一依赖，至少了解备选方案，当主供应商出现故障或价格大幅上涨时，有切换的能力。
100. 最后一条，也是最重要的：AI是工具，你对工具的判断力才是真正的资产。一个新模型出来，你能快速判断它对你的场景有没有用，这个能力比跟上每一个新模型都重要。
100条写完了。
每一条背后都有一个故事，大多数是我或者我认识的人踩过的坑。希望你们能少踩一些。