你信心满满地选了一个AI框架，然后现实给了你一巴掌
这是我见过的最常见的AI开发模式：第一周，框架太强了，Demo惊艳。第二周，遇到了第一个坑，花了两天解决。第三周，发现框架的抽象层在阻碍你而不是帮助你。第四周，开始考虑"要不要自己从头写"。
过去两年，我用了几乎所有主流AI框架，踩过的坑足够写一本书。以下是12个最致命的坑，以及如何避免它们。
坑一：LangChain的"抽象泄漏"
LangChain最大的卖点是"一切皆Chain"——你用LCEL（LangChain Expression Language）把各种组件串起来。但当你需要调试时，这个抽象变成了噩梦。
一个典型的RAG Chain：retriever | prompt | model | output_parser。看起来简洁优雅。但当检索结果为空时，你无法在这个链中插入fallback逻辑。当模型返回格式错误时，你无法优雅地重试。
解决方案：不要用Chain做复杂逻辑。用LangGraph的Graph来做——它让你在每一步都能插入条件分支和错误处理。
金句：LangChain的Chain是"Demo神器，生产地狱"。
坑二：LlamaIndex的索引膨胀
LlamaIndex的VectorStoreIndex默认会把所有文档的Embedding存在内存中。当你的文档量从1000增长到100万时，内存占用从2GB暴增到50GB，系统OOM。
解决方案：使用IngestionPipeline做增量索引，配置insert_batch_size控制内存占用，使用外部向量数据库（如Milvus）而不是默认的内存存储。
金句：LlamaIndex的默认配置是给Demo用的，不是给生产环境用的。
坑三：Dify的"代码节点地狱"
Dify的Workflow节点中有一个"代码节点"——在这里你可以写Python/Jinja2代码。问题在于，当你开始频繁使用代码节点时，Dify的"低代码"变成了"低级的代码"——你需要在Dify的Web界面里写代码，没有版本控制、没有IDE、没有测试。
一个真实的案例：某团队在Dify中写了87行代码节点，处理复杂的订单计算逻辑。一个月后，没人能维护这段代码——因为它既不在Git仓库里，也不在IDE里，而是藏在Dify的某个Workflow节点中。
解决方案：如果代码超过30行，把它抽成API服务，在Dify中用HTTP节点调用。保持在Dify中写代码的原则：只做数据转换，不做业务逻辑。
金句：Dify的代码节点是潘多拉魔盒，打开它你就告别了"低代码"的本意。
坑四：Agent的Token黑洞
多Agent框架（CrewAI、AutoGen）有一个共同的问题：Agent之间的对话会消耗大量Token。一次5个Agent的协作任务，可能烧掉200K-500K tokens，单次成本$1-$2.5。
更糟的是，Agent对话经常跑偏——Agent A问了一个问题，Agent B答非所问，Agent C追问，Agent A重新解释……循环往复。你烧掉的Token除了产生账单，什么都没产出。
解决方案：
- 设置
max_tokens和max_consecutive_auto_reply上限 - 为Agent对话设置"预算"（最多3轮/Agent）
- 使用小模型做内部对话（如GPT-4o-mini），大模型做最终输出
金句：Agent的Token消耗不是"可优化"的问题，是"必须限制"的问题。
坑五：框架版本升级的Breaking Change
AI框架的版本迭代速度极快。LangChain从0.1到0.3，API改变了几十次。LlamaIndex从0.9到0.11，索引格式不兼容。Dify从0.6到0.8，Workflow格式变了。
某团队在2025年Q1用一个版本的LangChain写了一个生产系统，Q3想升级到最新版本，发现50%的代码需要重写。
解决方案：
- 锁定框架版本，只在有明确需求时升级
- 升级前仔细阅读Migration Guide
- 核心业务逻辑不要深度耦合框架API——用适配器模式隔离
金句：AI框架的版本号不是"越大越好"，是"稳定就好"。
坑六：Prompt的"散落"问题
框架的便利性让你在不同的地方写Prompt：Chain里、Agent里、Tool里、代码节点里。一个月后，你的系统中有30个不同的Prompt散落在各个地方，没有一个统一的管理方式。
解决方案：
- 把所有Prompt集中在一个配置文件或数据库中
- 用DSPy做Prompt自动优化，而不是手动调Prompt
- 建立Prompt的版本管理和A/B测试机制
金句：散落的Prompt是技术债务，集中管理的Prompt是资产。
坑七：工具的"信任"问题
Agent框架中的一个Agent可以调用工具（Tool）——API调用、数据库查询、文件操作。但Agent可能"幻觉"出工具调用——调用一个不存在的API，用错误的参数格式，或者重复调用同一个工具。
解决方案：
- 为每个工具定义严格的Schema（输入/输出类型、参数范围）
- 设置Tool调用失败的重试和fallback机制
- 对危险操作（如删除、修改数据库）要求人工确认
金句：Agent调用的工具越多，出错的概率越大。工具数量不要超过10个。
坑八-十二（速览）
- 向量数据库选配：框架默认用内存向量库，生产环境必须换专业向量库
- 多租户隔离：框架默认不支持多租户，需要自己实现
- 日志和监控：框架的默认日志不够，必须接入LangSmith/LangFuse等可观测性工具
- 速率限制：框架不处理LLM API的速率限制（429错误），需要自己实现重试和退避
- 成本控制：框架让你"忘记"每次LLM调用都在花钱，必须建立成本监控和告警
金句：AI框架能帮你快速搭Demo，但能帮你稳定运行的，是框架之外的基础设施。