1. 从零到一：为什么选择 EdgeOne Makers 作为 Agent 的起点？

最近在团队内部搞了个小实验，想看看能不能快速把一个 DevOps 知识库的“智能助手”给跑起来。需求很明确：我们内部有大量的运维手册、故障处理 SOP、部署脚本和配置说明，散落在 Confluence、GitLab Wiki 和各种 Markdown 文件里。每次新人入职或者遇到不常见的问题，老员工就得花时间翻找，或者重复解释。我们想，能不能有个“活”的助手，能理解自然语言提问，然后从这些文档里精准地找到答案，甚至能根据上下文给出操作建议？

一开始，我们自然想到了去搭建一套完整的 RAG（检索增强生成）系统。但一评估，从向量数据库选型（Milvus, Pinecone, Weaviate）、Embedding 模型部署（BGE, text2vec），到 LLM 的 API 集成和前端界面开发，没个小一周时间根本下不来，这还不算后续的调优和运维。就在我们纠结于技术选型和资源投入时，偶然看到了腾讯云 EdgeOne 的 Makers 模板。它的宣传点是“快速构建 AI 应用”，特别是里面有一个“知识库问答”的模板。这让我们眼前一亮：如果这个模板能帮我们省掉底层基础设施的搭建，让我们直接聚焦在“灌数据”和“调效果”上，那“5小时上线”这个目标，或许真的不是天方夜谭。

EdgeOne 本身是一个边缘网络加速与安全平台，而 Makers 是它上面一个面向开发者的 AI 应用构建平台。选择它，核心是看中了它的“开箱即用”和“集成度”。我们不需要自己操心服务器、GPU、向量数据库的部署和扩缩容。Makers 模板已经封装了从文档解析、向量化到问答推理的完整流水线。对于我们这种验证性项目，最大的成本不是金钱，而是时间和工程师的注意力。能够将精力从“搭建轮子”转移到“训练司机”（即优化知识库内容和问答逻辑）上，是做出这个决策的关键。

当然，这并不意味着它适合所有场景。如果你的知识库数据量极其庞大（例如 TB 级），或者有极强的定制化需求（例如需要特定的检索算法、复杂的多跳推理），那么从零开始搭建可能是更优解。但对于我们这种数据量在 GB 级别、追求快速验证和迭代的中小型团队需求，Makers 模板提供了一个近乎完美的“起跑线”。

2. 实战第一步：环境准备与 Makers 模板初始化

理论说得再多，不如动手跑一遍。我们的目标是“5小时”，所以每一步都必须高效、明确。

2.1 核心资源准备

首先，你需要一个腾讯云账号。如果还没有，去官网注册一个，这个过程大概10分钟。注册完成后，进入控制台，找到“边缘安全加速平台 EdgeOne”。这里有个关键点：Makers 功能可能需要申请开通，或者处于特定区域的灰度测试中。我们当时是在“华南地区（广州）”找到的，如果你在控制台没直接看到，可以尝试搜索“Makers”或联系客服确认开通情况。

开通后，你需要准备两样东西：

1. 知识库文档：这是你 Agent 的“大脑”。我们提前把运维相关的文档做了整理。格式支持很友好，包括.txt,.md,.pdf,.docx,.ppt,.xlsx，甚至可以直接输入一个网页 URL 让它去抓取。建议在开始前，就把你的文档收集好，放在一个统一的文件夹里。我们当时是建了一个专门的 Git 仓库来管理这些文档，方便后续版本更新。
2. API 密钥：Makers 的核心能力，比如调用大模型进行问答，需要用到腾讯云自家的混元大模型API。你需要在“腾讯云 API 密钥管理”页面创建一组 SecretId 和 SecretKey。这个过程很简单，但务必妥善保管你的 Key，不要泄露。

2.2 创建你的第一个 AI 应用

在 EdgeOne 控制台找到 Makers 入口，点击“创建应用”。你会看到一系列模板，我们直接选择“知识库问答”。这个模板已经预设好了文档处理、索引构建和问答交互的整个流程。

给应用起个名字，比如DevOps-Helper-Agent。描述可以写清楚它的用途，比如“内部运维知识库智能问答助手”。接下来是关键一步：选择模型。Makers 提供了混元大模型的不同版本供选择。对于知识库问答场景，我们选择了hy-llm-text-32k这个版本。理由如下：知识库的上下文（Context）可能很长，特别是当需要引用多篇文档的片段来综合回答时，32K 的上下文长度能提供更大的缓冲空间，避免重要信息被截断。相比更短的版本，它在处理复杂问题时表现更稳定。

注意：模型选择会影响费用和响应速度。hy-llm-text-32k能力更强，但单次调用的 Token 消耗也可能更多。在项目初期，建议先使用它来保证效果，后续如果发现大部分问答都很简单，可以再尝试切换到更轻量的版本进行成本优化。

创建完成后，你会进入应用的管理界面。这里就是你的“作战指挥中心”了。

3. 构建 Agent 的“记忆体”：知识库上传与处理优化

应用创建好了，但它现在还是个“空壳”，没有知识。接下来就是最核心的一步：灌数据。

3.1 文档上传与解析

在应用管理界面，找到“知识库管理”或类似的标签页。点击“上传文档”或“添加知识”，把你准备好的运维文档批量上传上去。系统后台会自动进行一系列处理：

1. 文本提取：从各种格式的文档中提取出纯文本内容。
2. 文本清洗与分割：去除无关的格式符号，并将长文本按照语义切割成大小合适的“片段”（Chunks）。这个分割策略非常关键，它直接影响后续检索的精度。分割得太碎，可能丢失上下文；分割得太大，又会引入噪声。
3. 向量化：使用嵌入模型（Embedding Model）将每个文本片段转换为一个高维向量。这些向量就像文档片段的“数学指纹”，语义相近的片段，其向量在空间中的距离也更近。

这个过程是全自动的，你只需要等待进度条走完。我们上传了大约 200 个 Markdown 和 PDF 文档（总计约 50MB），处理时间在 15 分钟左右。

3.2 知识库优化的实战心得

上传完就万事大吉了吗？绝对不是。要让 Agent 回答得准，知识库的质量比数量更重要。这里分享几个我们踩过坑后总结的优化点：

• 文档结构预处理：在上传前，尽量保证文档本身结构清晰。比如 Markdown 文件，确保标题层级（#,##,###）正确。这能帮助分割算法更好地理解段落边界。对于从 Confluence 导出的 HTML 或 PDF，如果发现提取的文本杂乱，可以考虑先用pandoc等工具转成干净的 Markdown 再上传。
• 关键信息强化：对于运维文档中特别重要的部分，比如错误代码、命令参数、配置项，可以在源文档中适当加粗或使用代码块。虽然模型最终处理的是纯文本，但清晰的格式有助于分割和后续理解。例如，把ERROR_504: Gateway Timeout放在一个独立的段落或代码块中，比淹没在一大段描述里更容易被精准检索到。
• 处理“失效知识”：运维知识会过期。当有新的部署流程或配置变更时，务必更新知识库。Makers 支持重新上传同名文档（通常会触发更新）或直接删除旧文档。我们建立了一个简单的规则：任何线上配置变更文档被批准合并后，负责人需要在 24 小时内同步更新 Makers 中的知识库。不要依赖 Agent 去“理解”新旧文档的冲突，它只会基于检索到的片段来回答，如果旧文档没删，它就可能给出错误答案。
• 测试你的分割效果：上传后，可以尝试问一些非常具体、答案明确存在于某文档某一小段的问题。如果回答不上来或者引用错了地方，可能是分割策略导致相关文本被割裂了。这时，可能需要调整上传时的“分段长度”参数（如果提供），或者回头优化源文档的结构。

4. 从问答接口到智能体：配置与集成实战

知识库就绪后，你的 Agent 已经具备了“记忆”。下一步是让它能“开口说话”并融入你的工作流。

4.1 对话界面与 API 调用

Makers 模板自带一个 Web 对话界面。你可以在应用管理页找到预览或访问链接。在这个界面里，你可以直接像用 ChatGPT 一样向你的知识库提问。这是最快速的测试方式。比如输入：“Kubernetes Pod 一直处于 Pending 状态，可能的原因有哪些？” 它会从你上传的故障排查手册中检索相关信息并生成回答。

但我们的目标是一个能集成到内部工具（如 Slack, 钉钉，或内部运维平台）的 Agent。这就需要用到 API。Makers 提供了完善的 API 文档。核心调用流程非常简单：

1. 获取访问凭证：使用你的腾讯云 SecretId 和 SecretKey，通常通过签名算法生成一个临时的访问令牌。

2. 构造请求：向指定的 API 端点发送一个 POST 请求。请求体主要包含：

   • query: 用户的问题。
   • knowledge_id: 你的知识库 ID（在管理界面可以找到）。
   • 可选参数：如stream（是否流式输出）、temperature（控制回答的随机性，对于知识库问答，建议设低一点，比如 0.1，以保证答案的稳定性）。

3. 解析响应：API 会返回一个 JSON，里面包含模型生成的答案answer，以及非常重要的source或references字段，这个字段列出了回答所引用的原始文档片段及其出处。这个功能至关重要，它赋予了答案可解释性。当 Agent 给出一个操作建议时，工程师可以快速点击溯源，查看完整的原始上下文，确认建议的准确性，避免了“黑盒”带来的不信任感。

4.2 打造你的“智能体”逻辑

有了 API，我们就可以封装自己的“DevOps 助手 Agent”了。这里的“Agent”不仅仅是一个问答接口，我们可以赋予它一些简单的逻辑。例如，我们用 Python 写了一个简单的 Flask 服务，做了以下几件事：

• 问题分类与路由：不是所有问题都需要查知识库。我们设置了一些关键词规则。比如用户提问“重启服务器”，Agent 会先回复一个标准警告：“重启操作会影响服务，请确认已通知相关方。你是想查询重启的标准操作流程（SOP）吗？” 这相当于一个安全护栏。
• 对话历史管理：为了支持多轮对话（比如用户追问“那具体怎么操作？”），我们在服务端维护了一个简单的会话缓存，将上一轮问答的上下文（精简后）作为历史信息传入下一次 API 调用，使得 Agent 能理解指代关系。
• 结果后处理：对于 API 返回的答案，我们有时会做一些格式化。比如，如果答案中包含命令行代码，我们自动用代码高亮包裹；如果引用了多个文档，我们把出处整理成更清晰的列表。

4.3 集成到内部平台

最后一步是暴露这个服务。我们把这个 Flask 服务部署在内部的 Kubernetes 集群上，并配置了一个内部域名devops-helper.internal.company.com。然后，在内部的运维门户网站和 Slack 机器人上，都集成了对这个端点的调用。Slack 集成的代码片段大致如下（伪代码）：

# Slack Bolt 应用中的消息监听事件 @app.event("app_mention") def handle_mention(event, say): user_question = event['text'] # 调用自己的 Agent 服务 answer = call_our_agent_service(user_question) # 将回答送回 Slack 频道 say(f"<@{event['user']}>, {answer}")

就这样，一个能响应@DevOps助手并回答问题的 Slack Bot 就上线了。

5. 效果评估与迭代：让 Agent 越用越聪明

上线不是终点，而是起点。一个有用的 Agent 需要持续喂养和调教。

5.1 如何评估回答质量？

我们建立了简单的评估机制：

• 相关性：答案是否直接针对问题？还是答非所问？
• 准确性：答案中的事实信息（命令、参数、步骤）是否与知识库源文档一致？
• 完整性：是否涵盖了问题所涉及的所有关键点？还是有所遗漏？
• 可操作性：给出的步骤是否清晰、可执行？

我们鼓励团队成员在使用后，通过一个简单的反馈按钮（“有帮助”/“没帮助”）来标注回答。对于“没帮助”的案例，我们会人工介入分析。

5.2 常见问题与优化策略

在初期，我们遇到了几类典型问题：

1. 检索不准：用户问“Nginx 502 错误”，但 Agent 引用的是关于“Apache 504 错误”的文档。这是因为“502”和“504”在向量空间可能被模型认为相似。优化：我们在知识库中，为这类关键错误码文档添加了更丰富的同义词和问题表述。例如，在“Nginx 502 Bad Gateway”文档的开头，我们手动添加了一段：“常见问法：502错误怎么办？网站显示502如何排查？Nginx返回502...” 这相当于给文档增加了更易被检索到的“标签”。
2. 答案冗长或包含无关信息：有时 Agent 会连带着引用文档中的免责声明或示例代码的无关部分。优化：调整 API 调用参数。Makers 的 API 通常有参数可以控制返回的“引用片段”数量和质量（如top_k）。我们通过测试，将返回的片段数量从默认的 5 个调整为 3 个，并要求模型“基于最相关的1-2个片段进行总结”，有效提升了答案的简洁性。
3. 处理“不知道”：当问题完全超出知识库范围时，早期的 Agent 会试图“胡编乱造”（大模型常见的幻觉问题）。优化：我们在自己的 Agent 服务层增加了判断逻辑。如果 API 返回的答案中，引用的源文档置信度得分很低（如果 API 提供此分数），或者答案中包含大量“可能”、“一般来说”等模糊词汇，我们的 Agent 会主动回复：“这个问题超出了我当前知识库的范围，建议您查阅 [某内部手册链接] 或联系某某团队。” 这比给出一个错误答案要好得多。

5.3 知识库的持续运营

我们设立了一个虚拟的“知识库维护员”角色，由团队成员轮流担任，每周花少量时间处理：

• 收集新的运维文档并上传。
• 查看问答日志，找出高频但回答不佳的问题，针对性补充或修改知识库。
• 清理过时文档。

这个过程让我们的 DevOps 助手 Agent 真正活了起来，成为了团队知识沉淀和流转的有效工具，而不是一个上线即废弃的演示项目。从看到模板到第一个可用的 Slack Bot 响应，我们确实在 5 个小时左右完成了核心流程。而后续的迭代优化，则是一个伴随团队成长的长期过程。