为技术现场服务构建AI智能体学到的13件事

我构建的语音机器人和聊天机器人，是技术人员在现场或办公室为工作做准备时使用的。它们基于制造商、工程实验室、暖通空调公司和现场服务团队的技术文档构建。这些智能体不是演示品。当机器出现故障时，技术人员会使用它们。我最初的许多想法是错误的。有些还代价高昂。以下是我一路走来学到的13件事。如果这对正在构建自己智能体的人有用，那就意义非凡了。 技术栈 这是我们使用的软件： 智能体和API：Python、FastAPI 编排：LangGraph用于图，LangChain用于组件/节点 可观测性：Langfuse 检索：OpenAI嵌入、Milvus（稠密和稀疏混合检索）、zerank-2用于重排序 结构化数据：Postgres 模型：不同的提供商，支持自动故障转移。如果某个提供商在运行期间出现API错误，我们会将请求发送到不同的提供商。 通信：通过Hail MCP实现智能体电话呼叫、短信和电子邮件。 基础设施：Hetzner上的服务器，AWS上的存储和部分管道组件 第1部分：数据摄取 第1条：构建自己的文档ETL管道 我们从一个名为“Unstructured”的商业文档处理平台开始。该平台很容易上手。我们在不到一天的时间里就让系统投入运行。商业平台在这方面很擅长。然后我们发现了问题。提取质量很低。平台给出了结构化输出，但结构是符合Unstructured的，而不是符合我们的。我们改变了自己的系统以适应他们的格式。这是错误的顺序。这是一种反模式。我们不得不扭曲我们的管道才能让它工作。后来我们开始与Zeppelin（一家主要的卡特彼勒经销商）合作，他们分享的第一份文档是8000页密集的技术文档。图纸、原理图、交叉引用其他页面的反向链接、复杂的标识符等等。Unstructured上的管道失败了20次。我们为每次失败都付了钱。那时，我们做出了一个决定。成本是一个问题，但更大的问题不同：我们的文档处理逻辑处在一个我们无法检查、修复或改进的系统中。我们对可用的平台和库进行了基准测试，并选定了一个名为Docling的开源库。我们用一个周末构建了一个原型。原型的效果比商业平台更好。我们继续改进管道。现在它已经完全自动化，效果很好。教训不是“不要使用商业工具”。从商业工具开始。发布你的产品MVP。了解你真正的需求。但应尽快将文档处理等关键架构组件迁移到自己的系统中。数据处理是所有其他功能的基础。你需要灵活性、成本控制，以及修复自己失败的能力。第2到第11条经验之所以成为可能，仅仅是因为我们掌控了ETL管道。 第2条：自主掌控管道让我们的成本降低了15到20倍 Unstructured起初对1000页收费20美元，随后价格涨到30美元。按页定价并不能反映真实成本。实际处理成本随文档不同而变化。一页简单文本和一页旋转的工程图纸并不等价。但提供商对这两页收取相同的费用。我们运营自己的管道数周，用真实客户文档测量了成本。我们的成本低了15到20倍。我们并不是用低质量模型来达到这个结果。我们使用了优秀的模型。我们在自己的GPU基础设施上，用我们自己的路由来运行这些模型。对于一家小公司来说，这不仅仅是改进——这是多出几个月的运营时间。 第3条：提取质量决定了系统的最高性能 你无法用更好的检索器、更智能的智能体或更大的模型来纠正糟糕的提取结果。规格表采用键值布局。如果提取将此布局变成了非结构化文本，数据就丢失了。如果提取忽略了旋转页面，数据就丢失了。如果表格失去了列对齐，数据就丢失了。后续任何过程都无法恢复这些数据。技术文档中经常出现这些情况：旋转页面、密集表格、键值布局的规格表、有30年历史的扫描手册，以及图像中包含重要文字的图表。我们在准确性上的所有改进都始于正确的提取。 第4条：分块是一种策略，而非默认设置 我们使用混合分块。这种方法按文档的结构和层级进行划分，然后根据token数量合并各部分。许多开发者使用512个token窗口的递归字符分割器，之后再也不会更改这个设置。然后他们问为什么检索质量低。你的分块边界决定了检索器可能的结果。如果一个过程被分成两个块，任何检索器都无法把完整过程提供给技术人员。 第5条：在ETL管道中提取分类法和标签 我们在摄取期间定义分类法：制造商、型号，以及每个组织的自定义标签。管道在预处理期间提取标签。我们将标签作为标量过滤器与向量一起保留。这看起来像一项小的管理任务。在第13条中，它变成了一个产品功能。这也是封闭商业平台不允许的功能的一个很好的例子。 第2部分：检索 第6条：简单的Top-K语义搜索是不够的 Opero的智能体第一个版本做了简单的Top-K语义检索。它通过语义相似度找到10到20个文档，把这些文档放入上下文中，然后生成答案。没有重排序，没有相关性过滤，也没有程序来判断这些文档是否是针对用户问题的最佳可用文档。我们曾希望余弦相似度能找到有用的数据，然后把结果作为答案提供给用户。这种方法在演示时效果尚可，但失败频率高到足以构成危险。这是该领域最危险的失败情况。 第7条：添加重排序步骤 我们添加了重排序步骤。系统找到许多候选文档，然后一个专门的模型会为每个候选文档针对该查询给出相关性分数。改进是立竿见影且巨大的。如果你只应用这份清单中的一条经验，那就应用这一条。我们还在用户界面中使用相关性分数。如果最佳结果分数较低，我们会告诉用户。我们不会基于低质量的上下文给出自信的答案。 第8条：重排序分数没有绝对尺度——选择一个能校准它们的模型 我们从Cohere Rerank开始。它运行正确，但其相关性分数不使用绝对尺度。因此，我们必须为每个组织和每个行业类型调整阈值。我们必须决定哪个分数是高、中或低。这些阈值是估计值，而且当文档集合变化时它们也会改变。我们换成了ZeroEntropy的zerank-2。这个模型提供标准化的相关性分数。这看起来是一个小改动，但其实不是。你可以一次性定义一个固定的相关性尺度，然后在这个尺度上构建产品逻辑。当你的数据变化时，这个尺度依然正确。你不必保持校准流程。 第9条：如果用户输入序列号，请使用混合检索 我们在语义搜索的基础上添加了BM25关键词匹配。工程师和技术人员不会写完整的问题。他们输入“E-047”，他们输入标签上的零件号，他们输入序列号。向量搜索在这些精确术语上准确率很低。这不是缺陷。嵌入寻找含义，而错误代码没有含义。语义搜索能找到“为什么压缩机短循环”的答案，BM25能找到“SCR-4471-B”的答案。用户需要这两种方法，而且经常在同一个问题中同时需要。 第10条：多语言是常态 我们的大部分文档是英文的。但我们也有德语、丹麦语、瑞典语和中文的文档。欧洲