一个技术助手说出了正确命令，却指向一页根本不存在的文档。更麻烦的是，它还会把这个不存在的链接包装成"官方依据"。对普通聊天，这也许只是一次尴尬的幻觉；对正在修改线上配置的编程助手，错误出处会让人误以为那条建议已经被正式验证。
十月九日，Redis 工程团队公开了 Redis Docs MCP 的构建过程。值得看的不是又多了一个聊天接口，而是一份具体的工程答卷：为什么只暴露三个工具，为什么同一套知识库要走两条读取路径，为什么引用地址不能由大模型自己书写，以及怎样用可重复的评估拒绝看起来漂亮、实际变差的优化。
这套服务面向公开技术文档，并不控制使用者自己的 Redis 数据库。它的公开地址是 redis.io/mcp ，无需 API 密钥。下面把这篇工程复盘拆成一套可以迁移到内部知识库、开发者文档和企业研发助手的实施方法，同时明确哪些数字属于 Redis 团队的实测，哪些只是我们据此提出的设计建议。
一、真正的问题不是模型答不上来，而是答案没有可核验来源
设想一位工程师问助手，某个 Redis 版本的内存淘汰行为该如何配置。模型可能从训练知识中回忆一条旧指令，也可能搜索到一个包含不同版本信息的网页，然后流畅地拼成答复。表面上答案很完整，但工程师还需要知道：这条结论适用哪个版本？对应原文哪一节？网页更新后还能找到吗？
传统的网页搜索容易返回页面标题与摘要，却缺少适合程序复用的稳定文档标识。把网页全部抓到本地做向量化也不是免费的午餐：分段策略、版本更新、重新嵌入、删除过期内容、搜索排序都要自己维护。多个助手各自建索引，最后会出现不同团队从同一份官方文档得出互不兼容的结论。
Redis 的选择是把官方文档直接变成面向 Agent 的检索服务：调用者不需要复制语料，文档所有者统一维护索引，返回可再次查询的标识。这个边界比把一个通用问答模型套在网页上重要得多。它让"我查到了什么"成为独立于"我怎么解释它"的事实，而不仅是一段看似可信的话。
应用到自己的系统时，第一步应该先列出可能误导用户的查询：版本差异、命令参数、默认配置、迁移限制、废弃接口、故障恢复。然后确认每种问题都有可查证的文档路径，而不是先采购一个更大的模型。模型升级可以改善措辞，却不能自动补齐缺失的证据链。
二、三个工具够用：让模型少做决定，让开发者多看事实
Redis Docs MCP 只提供 search、fetch 和 ask。它们看起来朴素，恰好组成一个可检查的链条。search 根据查询返回最多八个候选页面，附带标题、摘要、地址与稳定标识；fetch 根据标识返回更完整的正文及主题、版本、章节信息；ask 才进入多步检索与语言模型综合回答。
| 工具 | 主要职责 | 适合的请求 | 需要核实的事实 |
|---|---|---|---|
| search | 找候选证据 | 单一命令或配置查询 | 是否返回正确页面与稳定标识 |
| fetch | 取得原始内容 | 核对参数、引用原句 | 标识是否可以再次解析 |
| ask | 跨章节综合 | 多个概念有关联的问题 | 输出是否附带真实获取的来源 |
为什么不多提供十个高级工具？因为每个工具的描述都可能进入调用者的上下文，工具数量膨胀并不只是服务端多写几个函数，还会持续占用模型注意力。更糟的是，如果每个具体命令都有一个专用工具，模型要先在大量相近名字里选择，选错的机会也一起增长。
实际操作应优先 search。拿到候选后，先比较标题与版本，必要时调用 fetch 取得原文。只有一个页面无法回答的问题，或者多处证据必须结合的问题，再交给 ask。这个顺序把较昂贵的推理留给确实需要推理的场景，普通事实查询仍能保持简单可靠。
需要强调，公开文档接口和操作业务数据库的接口不能混为一谈。前者通常只暴露公开知识；后者可能读取敏感数据甚至执行写操作，必须设计身份验证和权限边界。Redis 团队公开的是只读文档服务，不等于推荐所有 MCP 服务都取消认证。
三、一份索引，两条读取路径：不要让大模型成为搜索的单点故障
这次架构最值得借鉴的一点，是把高频的 search、fetch 与模型驱动的 ask 分离。前两者直接查询 Redis 索引，团队可以控制检索字段、候选数量、融合算法和排序；ask 经过 Context Retriever 的工具网关和模型，由模型决定怎样追加检索并综合结果。
这不是简单地在同一个函数里写一个条件分支。两条路径的依赖、延迟、失败方式和可观测指标都不同。即使模型供应商临时不可用，直接检索工具仍然可以返回文档；即使复杂问题的综合质量有波动，用户仍能退回可验证的原始页面。
索引本身遵循"一位写入者、两位读取者"。导入流水线从 Redis 文档仓库读取 Markdown，处理文档元数据与特殊标记，按照章节切分长文，生成嵌入并写入索引。服务与网页演示读取同一份资料，但不各自生成另一套近似相同的知识库。这减少了内容版本分叉，也让错误更容易定位到写入、查询或者答案生成中的某一层。
对企业知识库，建议把系统划为三个独立责任：内容摄取负责版本和更新时间；检索服务负责命中、标识和原文；回答层负责解释与引用。三个责任可以部署在一个项目里，却不应糊成一个无法定位故障的黑盒。
特别要小心索引结构的隐性成本。Redis 团队发现，某些字段一旦被声明成可过滤属性，就会让网关自动生成更多过滤工具；原本只是希望让文档标识可读，结果模型额外看见了不需要调用的工具。解决方法不是继续给模型写长提示词，而是在适配层从原始记录提取字段，避免污染工具界面。这是非常典型的"少暴露就是好设计"。
四、引用绝对不能交给模型自由编写
Redis 的工程复盘里有一个很直观的失败案例：模型给出一个看似正确、实际上会返回找不到页面的文档路径。路径里只有一段目录名错了，肉眼几乎看不出来。这样的链接如果出现在带有配置指令的答案后面，读者通常会高估整段答案的可靠程度。
后来团队改变了责任分配。模型仍可以根据检索内容组织语言，但引用列表不再由它生成字符串；系统直接读取当轮检索实际拿到的文档标识，构造 sources 数组，并要求每个标识都能经过 fetch 解析。这等于为引用建立了一条不能仅凭想象完成的路径。
最小验收可以写成这样，代码没有依赖外部模型，主要用于说明验证边界。真实系统应使用自己的检索客户端替换 resolve 函数，并在请求超时或解析失败时拒绝给出"全部已核验"的结论。
python
from dataclasses import dataclass
@dataclass(frozen=True)
class Source:
id: str
title: str
def verify_sources(sources, resolve):
if not sources:
return {"verified": False, "reason": "no sources"}
checked = []
for source in sources:
page = resolve(source.id)
if not page or page.get("id") != source.id:
return {"verified": False, "reason": "unresolvable id"}
checked.append(source.id)
return {"verified": True, "ids": checked}
documents = {"docs:search": {"id": "docs:search", "body": "reference"}}
result = verify_sources(
[Source("docs:search", "Search reference")],
documents.get,
)
assert result["verified"] is True校验一个链接能打开，也不等于证明回答的每个断言都正确。前者验证来源存在，后者还要检查命令、数值、适用版本是否真出现在来源中。一个可靠答案至少要区分"原文明确写了什么""从多个来源推断出什么""尚缺少哪项证据"。
还有一个容易忽略的细节：来源排序与来源删除不是一回事。Redis 通过答案中出现的特征事实给来源加权，重复来自同一页面的章节可能被适度降权，却不直接删除已经检索到的来源。对于审查和追溯而言，保留完整证据比把列表修剪得漂亮更有价值。
五、检索不要凭感觉调参：七十三条问题给出不直觉的结果
不少工程师一提到技术文档搜索，就条件反射地说要改用混合检索。原因听起来很合理：命令名、参数名与英文缩写需要关键词匹配，纯语义向量可能把相似但不同的命令混在一起。这个判断值得测试，但不能直接当作发布结论。
Redis 团队在七十三条查询上对比向量检索与混合检索。官方报告中，向量方案的 MRR 为零点八一六，混合方案为零点八三六；前三条结果命中率从零点八八升至零点九六；前八条召回率从零点九三升至零点九九。看起来全面占优，但第一条命中率反而从零点七五降为零点七一。
| 官方评估指标 | 向量检索 | 混合检索 |
|---|---|---|
| MRR | 0.816 | 0.836 |
| Hit@1 | 0.75 | 0.71 |
| Hit@3 | 0.88 | 0.96 |
| Recall@8 | 0.93 | 0.99 |
这意味着什么？如果产品只展示第一条结果，混合搜索未必更好；如果产品会交给助手八条候选，再决定 fetch 哪篇文档，覆盖范围变广更有价值。不能脱离调用链路谈"搜索质量提升"。同一组数字针对不同产品可能导向相反的设计结论。
团队还报告，标题字段的关键词匹配通常比正文更有效，倒数排名融合在他们的测试中优于线性权重组合；相关检索延迟数据是在他们当地环境测得，不能直接当成所有云环境的性能保证。最有意思的是，他们后来意识到部分问题源于语料分段与结构，而不是模型本身。
因此，评估看板不要只放一个总分。最少记录首条命中、前三条命中、固定窗口召回、可解析标识比例和查询延迟。如果改动提升了召回却损害首条命中，就按照实际产品怎么消费候选结果作选择，而不是挑一项最漂亮的数据写战报。
六、落地到自己的 Agent：从十条真实问题开始做可失败验收
不必第一天就建设一套复杂的知识图谱。先选十条团队里真正有人问过的问题，覆盖命令精确匹配、跨版本配置、教程与 API 文档区别、跨章节解释、已弃用接口。为每条问题记录一个或多个权威来源标识和能否找到它们的标准。
接下来可以用一个极小的评估循环：固定问题集，运行检索，保存返回的候选标识，和事先标注的相关集合比较。这个示例可直接运行，特意不调用任何在线大模型，保证纯检索质量评估能被重复执行。
python
def recall_at_k(results, expected_ids, k=5):
expected = set(expected_ids)
if not expected:
raise ValueError("expected_ids must not be empty")
returned = set(results[:k])
return len(returned & expected) / len(expected)
case = {
"question": "Which source explains the search contract?",
"expected": ["docs:search", "docs:fetch"],
}
retrieved = ["docs:search", "docs:unrelated", "docs:fetch"]
score = recall_at_k(retrieved, case["expected"], k=3)
assert score == 1.0
print({"question": case["question"], "recall_at_3": score})纯检索评估只问"证据有没有被找回来"；加入模型的完整链路评估再问"代理如何改写问题、调用多少次工具、怎样组合证据"。Redis 官方数据里，代理改写对简单查询的前五条召回有帮助，但在多跳查询上也可能增加噪声、降低前五片段的精度。把两层成绩混成一个总分，会掩盖到底是搜索器还是代理在失误。
上线前建议设置三条可以自动失败的门：所有返回给用户的来源标识都必须能解析；需要版本限定的问题必须在来源里找到对应版本；检索失败时只能说明没有取得充分证据，不允许模型靠记忆伪造官方引文。每条门禁都应该留下可复核日志，但公开服务要避免记录敏感的提问正文。
运行期还要区分真实容量瓶颈与限流造成的拒绝。Redis 团队提到一次并发压测几乎全是 HTTP 429，后来发现测到的是速率限制而不是服务承载能力。遇到类似数字，第一问应当是"请求有没有到达要测的组件"，而不是急着增加服务器实例。
七、最值得复制的做法：先固定证据合同，再让 Agent 写实现
这个项目有相当一部分代码由编程代理参与编写。Redis 披露的三百七十四次提交里，一百三十五次把代理列为作者。但他们的经验不是把任务一句话扔给 Agent，而是先在人类之间评审接口、非目标、验收条件和设计取舍，再把约束明确的实现工作交出去。
这样做的价值在于避免反复走同一条死路。若团队已经验证某个字段不能直接暴露为过滤工具，写进设计文档比让下一个模型重新猜测更可靠。若引用必须取自真实查询结果，验收测试应该先于生成代码存在；否则模型很容易写出一个看起来有来源、实则只是拼接字符串的接口。
复盘时应把问题按层分类：内容导入错误，就修内容和更新流程；搜索结果缺失，就修切分与排名；来源标识不可解析，就修索引到 fetch 的合同；语言模型讲错，就修证据选择和回答校验。不要因为最终答案出了错，就本能地给模型堆更多提示词和抽象的"必须准确"。
对开发者而言，这篇 Redis 工程记录最有用的结论不是"为产品加一个 MCP"。真正应该带走的是三个习惯：先返回可以查证的事实，再组织解释；把高频检索和模型生成的故障域拆开；用能失败的测量结果，而不是演示视频，来批准架构变更。
来源：Redis 工程博客《How we built the Redis Docs MCP for agents》，发布于 2026 年 10 月 9 日，redis.io/blog/how-we... 。文中的服务接口、三工具、测试数据和工程案例来自该原文；上文自建知识库实施顺序、验收建议和两段示例程序为本文原创整理。