跳至主要内容
RAG demo 谁都会做,能上线才算数

RAG demo 谁都会做,能上线才算数

一个企业知识库项目,两周做出能回答问题的 demo 并不难:上传几份 PDF,切块、向量化、接上大模型,一个对话框就能对着规章制度作答。项目真正卡住的往往是下一步。安全部门问谁可以访问哪些语料,IT 问模型密钥放在哪里,合规问答案错了能不能追到原文,运维问配额和审计日志怎么看。这些问题和检索算法没关系,但每一个都足以让项目停在内网试点。

我越来越觉得,私有化 RAG 的分水岭不在检索质量,而在 demo 之后那一串没人愿意写的工程活。最近看到一个把这段活做完的开源项目 AgentDesk,正好可以拿它当清单,讲讲从能回答到能用之间到底隔着什么。

demo 能回答,和生产能用是两回事

把两种状态的差距摊开看,会更清楚钱和时间花在了哪里。

demo 里 上线时 真正的卡点
一个对话框,谁都能问 按部门和角色限制可见语料 企业身份系统(OIDC/JWKS)、基于角色的访问控制(RBAC)
模型密钥写在环境变量里 密钥轮换不重启、后台不回传明文 加密存储加缓存热生效
答案看着对就行 每句话都能追到原文出处 引用溯源加无依据拒答
日志打到终端 谁在什么时候问了什么可回放 审计日志加调用配额
敏感词靠提示词约束 输入输出两侧都要拦截脱敏 规则在后台配置且即时生效

这张表里的每一项单拎出来都不难,难的是它们必须同时成立,还要能在客户内网里交付。多数开源 RAG 项目停在第一列,把第二列留给使用者自己补。补的过程没有技术快感,却决定了项目能不能过验收。

AgentDesk 属于直接把第二列做完的那一类。它是一套可私有化部署的 RAG 知识库加 Agent 运行时参考实现,基于 Mastra Agent 框架,全链路是上传文档、分块向量化、流式问答、引用溯源、审计与配额。

它把一整套服务都摆齐了

这里要先说清一个容易误解的点:它不是软件开发工具包(SDK),而是一整套能跑起来的服务。业务后端、对话端、运营后台、Agent 运行时和部署编排都在仓库里。

应用 职责 技术
agentdesk-api 唯一业务后端,鉴权、会话、额度、编排、审计 Go + Gin + GORM
agentdesk-chat 对话端,流式回答、引用展示、移动端页面 React 19 + Vite
agentdesk-admin 运营后台,语料上传、模型配置、配额审计、安全策略 React 19 + shadcn/ui
agentdesk-agent RAG 检索、向量化、工具调用,仅内网开放 Mastra + pgvector
deploy/ 本地与生产部署模板 Docker Compose + Traefik

AgentDesk 运营后台与移动端对话界面

两套前端共用同一套蓝色语义色变量,改主题只动一处层叠样式表(CSS)。运营后台用的是 Tailwind v4 的 oklch 语义色,带深色模式,图表和指标卡通过兼容变量跟着主色走;对话端用 CSS 自定义属性,品牌渐变、用户气泡、发送按钮和输入框聚焦边框都是同一支蓝。实现细节不复杂,但对企业内部工具很实际:不用为每个项目重做一套视觉,深浅主题也都在变量层面解决。

一次问答在内部走了哪些地方

数据不出内网这句话,得落到具体的调用边界上才算数。AgentDesk 的做法是 Agent 运行时不暴露公网,只由 Go 后端通过内网地址调用;PostgreSQL 及其向量扩展 pgvector、Redis、对象存储都可以私有化部署;模型地址由使用者配置,可以是云厂商,也可以是自建的推理网关。

AgentDesk 部署架构

一次提问的完整链路更值得顺着看一遍。

RAG 问答请求链路泳道图

问题先过输入安全检测,再做向量检索;检索为空就直接返回自定义拒答话术,根本不调用对话模型;有依据才生成答案,输出在服务器推送事件(SSE)流式返回时做脱敏,并留下审计记录。这条链路把答案能不能信变成一串可检查的步骤,而不是指望模型自觉。低置信度兜底和无依据拒答是两道不同的闸门,前者处理检索到但不够好的情况,后者处理压根没检索到的情况,混在一起做就会漏掉一半场景。少了这两道闸门,模型在没有依据时会一本正经给出听起来很像出处的段落,这类错误在演示阶段很难被发现,到了员工照着执行的场景才会出事。

模型与密钥怎么兜底

自带模型密钥(BYOK)是这套系统里我认为最该被抄走的设计。对话、向量、视觉三类模型各自独立配置,只要接口兼容 OpenAI 规范就能接,云端服务和自建网关一视同仁。地址和密钥都不写进源码或镜像,而是加密后存进数据库。

几个细节能看出是踩过坑的:密钥用 AES-256-GCM 加密,后台接口只返回是否设置的布尔标记,不回传明文;输入框留空表示不修改已有密钥;保存后由 Agent 侧缓存,约十五秒自动生效,换服务商或轮换密钥都不用重启;Go 后端和 Agent 运行时必须配同一个加密密钥,换这个值会让已存密钥全部失效,得重新录入。这套约束把轮换成本和泄露面都压得很低。还有个选型时容易忽略的量级:向量嵌入维度由环境变量控制,默认是 1536,而 pgvector 的层次导航小世界(HNSW)索引上限是 2000,超过就得换索引方案。

内容安全那边,敏感词分警告和禁止两级,输入侧可以选择提示但继续或直接拦截拒答。输出打码是在流式返回过程中做的,还会留一小段尾部缓冲来识别跨分块的词条,否则一个词被切成两段送到前端就拦不住了。规则在后台改完即时生效,还带一个测试面板,能先看命中结果再决定上线。页面里有个我认为很实在的设计:注册成的 HTTP 工具在服务端执行,只接受 http 或 https 地址,有超时和输出字符上限,文档里明确写着只对接可信的内网接口。把工具调用的权限边界写进文档,比在提示词里重复一百遍注意安全管用。

JSON13 行
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"method": "POST",
"url": "https://internal.example.com/api/order?q={{query}}",
"headers": { "Authorization": "Bearer {{token}}" },
"input_schema": {
"type": "object",
"properties": { "query": { "type": "string", "description": "用户问句" } },
"required": ["query"]
},
"response_path": "data.items",
"timeout_ms": 8000,
"max_output_chars": 4000
}

这段配置里,占位符会在调用时换成模型给出的参数,响应字段用点号路径提取,输出有字符上限避免撑爆上下文。内置的工具只有当前时间和知识库检索两个,随数据库迁移默认启用,可停用但不可删除。

上手成本到底有多高

部署编排在 deploy 目录,模板是 Docker Compose 加 Traefik。最短路径是复制几份环境变量样例,改掉数据库、Redis、对象存储、身份系统和加密密钥的配置,然后起容器。

BASH5 行
1
2
3
4
5
cd deploy
cp .env.example .env
cp agentdesk-api.env.example agentdesk-api.env
cp agentdesk-agent.env.example agentdesk-agent.env
docker compose up -d --build

再进业务后端目录做一次数据库迁移,起来之后有三个入口:对话端在 5173 端口,运营后台在 5174 端口,Go 接口的健康检查在 8080 端口。这里最容易踩的坑还是前面那个加密密钥:两个服务必须配成同一个值,否则 Agent 解不开后台存的密钥,知识库和问答功能会直接用不了。向量嵌入维度属于运维级配置,默认 1536,改了要重建向量索引,别等向量写满了才发现。

什么场景值得照着做,什么情况别碰

它明确不做单一行业绑定。仓库里出现的电商内容都是虚构示例,代码本身没有商品、订单或交易逻辑。按公开文档,比较对口的有五类:企业知识助手、客服与售前问答、渠道代理赋能、合规内容生成,以及文档预览站。文档预览站是另一个独立的静态站点示例,前四类吃的是同一套能力,但各自吃重的部件不一样。企业知识助手要多库检索和增量更新,客服问答靠流式对话、兜底话术和多轮记忆,渠道赋能要的是权限分级和问答审计,合规内容生成则用敏感词前置拦截加话术模板。把场景和部件对应起来,才好判断这套东西是不是真对症。

按我的判断,两种情况下没必要用它。一种是你只想知道向量检索怎么调更准,那这套东西太重,直接拿 Mastra 或 LangChain 搭个原型更快;另一种是纯对外的高并发对话产品,它的设计重心在内网可控和企业验收,不在那种规模的吞吐和弹性上。还有一种中间状态要留意:如果你没有私有化部署的条件,数据必须留在公有云托管服务里,那么数据不出内网这条最大的卖点就用不上了,剩下的能力要看是否还值这个部署成本。

如果你的问题停留在怎么让检索更准,这套参考实现的价值不大。但如果你要回答的是这套知识库怎么交给全公司用,而且安全、合规、可审计都说得清,那么从一个已经把清单第二列做完的项目开始,比从零补要省得多。代码在 https://github.com/bl8ds/AgentDesk-Private-Deployable-Knowledge-Base-Agent-Platform ,采用 MIT 许可。建议先看设计文档里的约束和部署指南里的清单,再决定要不要照着搭。

关于本文

由 Lu's Blog 撰写,采用 CC BY-NC 4.0 许可协议。

#Agent #RAG #开源 #私有化部署

评论