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”或联系客服确认开通情况。开通后你需要准备两样东西知识库文档这是你 Agent 的“大脑”。我们提前把运维相关的文档做了整理。格式支持很友好包括.txt,.md,.pdf,.docx,.ppt,.xlsx甚至可以直接输入一个网页 URL 让它去抓取。建议在开始前就把你的文档收集好放在一个统一的文件夹里。我们当时是建了一个专门的 Git 仓库来管理这些文档方便后续版本更新。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 文档上传与解析在应用管理界面找到“知识库管理”或类似的标签页。点击“上传文档”或“添加知识”把你准备好的运维文档批量上传上去。系统后台会自动进行一系列处理文本提取从各种格式的文档中提取出纯文本内容。文本清洗与分割去除无关的格式符号并将长文本按照语义切割成大小合适的“片段”Chunks。这个分割策略非常关键它直接影响后续检索的精度。分割得太碎可能丢失上下文分割得太大又会引入噪声。向量化使用嵌入模型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 文档。核心调用流程非常简单获取访问凭证使用你的腾讯云 SecretId 和 SecretKey通常通过签名算法生成一个临时的访问令牌。构造请求向指定的 API 端点发送一个 POST 请求。请求体主要包含query: 用户的问题。knowledge_id: 你的知识库 ID在管理界面可以找到。可选参数如stream是否流式输出、temperature控制回答的随机性对于知识库问答建议设低一点比如 0.1以保证答案的稳定性。解析响应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 常见问题与优化策略在初期我们遇到了几类典型问题检索不准用户问“Nginx 502 错误”但 Agent 引用的是关于“Apache 504 错误”的文档。这是因为“502”和“504”在向量空间可能被模型认为相似。优化我们在知识库中为这类关键错误码文档添加了更丰富的同义词和问题表述。例如在“Nginx 502 Bad Gateway”文档的开头我们手动添加了一段“常见问法502错误怎么办网站显示502如何排查Nginx返回502...” 这相当于给文档增加了更易被检索到的“标签”。答案冗长或包含无关信息有时 Agent 会连带着引用文档中的免责声明或示例代码的无关部分。优化调整 API 调用参数。Makers 的 API 通常有参数可以控制返回的“引用片段”数量和质量如top_k。我们通过测试将返回的片段数量从默认的 5 个调整为 3 个并要求模型“基于最相关的1-2个片段进行总结”有效提升了答案的简洁性。处理“不知道”当问题完全超出知识库范围时早期的 Agent 会试图“胡编乱造”大模型常见的幻觉问题。优化我们在自己的 Agent 服务层增加了判断逻辑。如果 API 返回的答案中引用的源文档置信度得分很低如果 API 提供此分数或者答案中包含大量“可能”、“一般来说”等模糊词汇我们的 Agent 会主动回复“这个问题超出了我当前知识库的范围建议您查阅 [某内部手册链接] 或联系某某团队。” 这比给出一个错误答案要好得多。5.3 知识库的持续运营我们设立了一个虚拟的“知识库维护员”角色由团队成员轮流担任每周花少量时间处理收集新的运维文档并上传。查看问答日志找出高频但回答不佳的问题针对性补充或修改知识库。清理过时文档。这个过程让我们的 DevOps 助手 Agent 真正活了起来成为了团队知识沉淀和流转的有效工具而不是一个上线即废弃的演示项目。从看到模板到第一个可用的 Slack Bot 响应我们确实在 5 个小时左右完成了核心流程。而后续的迭代优化则是一个伴随团队成长的长期过程。