如何将 RAG 管道部署为你的 AI 代理可以调用的 API 端点

每个 RAG 教程都遵循相同的路径：加载文档，分块，生成嵌入，写入向量存储。然后就结束了。读者手中只有一个已填充的向量数据库，却没有从那里到一个 AI 代理可以实际调用的生产系统的清晰路径。

"数据库中的向量"和"我的代理可以在运行时查询的检索端点"之间的差距是大多数 RAG 项目停滞的地方。本指南介绍如何将 RAG 部署为 API 端点——一个 AI 代理可以通过标准工具调用协议发现和调用的可调用检索服务。

为什么 RAG 教程偏离了重点

标准的 RAG 教程将检索视为嵌入式代码。你编写一个 Python 脚本来查询 Pinecone 或 Chroma，组装上下文，然后将其输入提示词。这在 notebook 中有效。但在以下情况下无效：

AI 代理（在 n8n、LangGraph 或你自己的编排器中运行）需要将检索作为工具调用
多个代理或应用程序需要共享同一个检索管道
非工程人员需要在不接触代码的情况下更新知识库
需要审计追踪来显示哪些文档被检索用于哪些查询

核心问题：作为嵌入式代码构建的 RAG 不可寻址。它没有 URL，没有模式，没有工具调用规范。AI 代理无法调用埋藏在另一个服务代码库中的 Python 函数。

RAG 作为嵌入式代码 vs. RAG 作为基础设施

这一区别决定了你的检索系统能否扩展到单个应用程序之外。

嵌入式 RAG 意味着检索逻辑存在于你的应用程序代码中。向量搜索、上下文组装和提示词构建是你应用中的函数。如果第二个应用程序需要相同的知识库，你就需要复制代码。如果你想让 AI 代理使用它，你需要手动编写一个包装端点。

RAG 作为基础设施 意味着检索管道是一个独立的服务，拥有自己的端点、自己的模式和自己的生命周期。你将 RAG 作为 API 端点部署一次，任何需要检索的代理或应用程序都可以调用它。这就是在本地运行 RAG 即服务的含义——检索成为一种共享能力，而不是重复的胶水代码。

将 RAG 部署为 API 的最佳方式是将索引和检索视为两个独立的管道，它们共享一个向量存储但独立运行。

架构：两个管道，一个画布

生产环境的 RAG 系统有两种不同的运行模式，它们在不同的时间表上运行，有不同的要求。

索引管道（批处理）

该管道处理你的源文档并填充向量存储。它按计划运行或在新文档到达时按需运行。

文件导入 → 解析器 → 清洗 → RAG 分块器 → 嵌入 → 向量存储写入器

每个步骤都是一个离散操作：从源目录或对象存储导入文件，将其解析为文本（处理 PDF、DOCX、HTML），通过删除样板内容清洗文本，使用重叠进行分块以保证检索质量，生成嵌入，并将向量写入你的存储。

当代理正在查询时，此管道不需要运行。它在数据更改时运行。

检索管道（实时）

该管道处理传入的查询并返回相关上下文。它持续运行，监听请求。

API 端点 → 查询嵌入器 → 向量搜索 → 上下文组装器 → API 响应

API 端点节点接收传入的查询，查询嵌入器使用索引期间使用的相同嵌入模型将其转换为向量，向量搜索在存储中找到最近邻，上下文组装器对结果进行排序和格式化，API 响应节点将结构化输出返回给调用者。

在 Ertas Data Suite 中，两个管道都在一个可视化画布上。你可以在一个视图中看到完整的数据流——从原始文档到向量存储到查询响应。检索管道可以独立于索引管道的运行而部署（切换到监听状态）。这意味着你的 RAG 检索 API 端点在后台重新索引文档时保持活跃和响应。

检索管道详解

检索管道中的每个节点处理一个关注点。

API 端点。 这是入口点。它定义 HTTP 接口：接受的参数（查询字符串、top-k 计数、可选过滤器）、身份验证和速率限制。关键的是，该节点自动生成一个工具调用规范，以 AI 代理可以消费的格式描述端点的输入和输出。

查询嵌入器。 获取原始查询字符串并使用与索引管道嵌入步骤相同的模型和参数生成向量。这里的一致性是不可协商的——如果你在索引期间使用了 512 维的 text-embedding-3-small，查询嵌入器必须完全匹配。

向量搜索。 对向量存储执行最近邻搜索。可配置的参数包括 top-k（检索多少个分块）、相似度阈值（最低相关性分数）和元数据过滤器（将搜索限制在特定文档类别或日期范围内）。

上下文组装器。 获取原始搜索结果并准备供消费。这包括去重（来自同一文档的重叠分块）、相关性重排、来源归属（每个分块来自哪个文档和页面）以及将输出格式化为结构化数据而非原始文本块。

API 响应。 将组装的上下文序列化为响应格式。返回检索到的分块、其源元数据、相关性分数以及调用者请求的任何诊断信息。

工具调用集成：如何使 RAG 可被 AI 代理调用

Ertas 中的 API 端点节点自动生成工具调用规范。这是使最佳 AI 代理 RAG 部署工具区别于基本 REST 包装器的关键能力。

当你部署检索管道时，API 端点节点生成与 OpenAI 函数调用、Anthropic 工具使用和其他代理框架兼容的工具规范。该规范描述：

端点 URL 和身份验证方法
带有类型和描述的输入参数（查询为字符串，top_k 为整数，过滤器为可选对象）
描述响应结构的输出模式
工具功能的自然语言描述，以便代理可以决定何时使用它

配置了此规范的 AI 代理可以在需要特定领域信息时自主决定调用你的 RAG 检索 API 端点。这就是 AI 代理的 RAG 工具调用在实践中的运作方式——代理不需要硬编码的检索逻辑。它通过工具规范发现检索能力并在相关时调用它。

这将你的 RAG 管道转变为代理式 RAG 管道的一个组件，其中代理编排何时以及如何检索信息，而不是检索作为每个请求中的固定步骤。

为什么本地部署对已部署的检索端点很重要

当你将 RAG 部署为实时 API 端点时，三个因素推动向本地部署。

延迟。 检索端点位于每个需要上下文的代理交互的关键路径上。如果你的代理在你的基础设施上运行而检索端点在第三方云中，你就为每个查询增加了一次网络往返。与你的代理在同一网络上的本地检索端点将网络跳跃的查询延迟降低到个位数毫秒。

数据主权。 你向量存储中的文档是你的专有数据。对云托管检索服务的每次查询都会将你用户的问题发送给第三方，并接收你的专有文档分块作为响应。对于受监管行业——医疗保健、金融、法律——这通常是不可接受的。在本地运行 RAG 即服务将查询和检索到的内容都保留在你的网络边界内。

成本可预测性。 云 RAG 服务按查询收费。一个繁忙的 AI 代理每天进行 10,000 次检索调用会产生可变的月度账单。本地部署将其转化为固定的基础设施成本。最佳的本地 RAG 端点部署工具为你提供可预测的经济效益，不受查询量影响。

比较：部署 RAG 的三种方法

因素	自定义 Python 代码	托管 RAG 服务	可视化管道（Ertas）
部署时间	数天到数周	数小时	数小时
工具调用规范	手动编写	因供应商而异	自动生成
本地部署选项	是（你自己构建）	很少	是
审计追踪	你自己构建日志	取决于供应商	内置
非工程师访问	否	有限	完整的可视化画布
索引/检索分离	你自己设计架构	被抽象化	显式的双管道模型
每次查询成本	仅基础设施	按查询收费	仅基础设施

自定义 Python 检索代码给你最大的控制权，但需要你自己构建端点、工具调用规范、日志记录和运维工具。托管 RAG 服务减少了设置时间，但引入了按查询成本，并且通常缺乏本地部署选项。Ertas Data Suite 中的可视化管道方法为你提供关注点分离和自动生成的工具调用规范，无需编写检索基础设施代码。

完整图景

你的 AI 解决方案变成两个组件：一个推理 API（你的微调模型或托管 LLM）和一个在 Ertas 中构建的 RAG 检索端点。推理 API 处理推理。检索端点处理知识。AI 代理通过工具调用编排两者。

没有连接它们的胶水代码。没有嵌入在应用程序中的检索逻辑。没有对按查询收费并扣留你向量的托管 RAG 服务的供应商依赖。

索引管道在你的数据更改时运行。检索管道持续运行，服务查询。两者都在一个画布上可见，可审计，并且可由不编写 Python 的团队成员维护。

开始使用

Ertas Data Suite 的 Serve 类别——API 端点、查询嵌入器、向量搜索、上下文组装器和 API 响应——现已在设计合作伙伴计划中提供。如果你正在构建需要可调用检索层的 AI 代理，或者正在从嵌入式 RAG 代码迁移到代理式 RAG 管道架构，我们期待与你合作。

加入设计合作伙伴计划，在你自己的基础设施上部署你的第一个 RAG 检索 API 端点。