Yuxi(语析)完全教程:可私有部署的多租户知识智能体平台部署与实战
企业想把大模型用起来,绕不开三个问题:内部文档怎么安全地喂给模型、多个部门共用一套系统时权限怎么隔离、智能体执行任务时怎么保证可控。市面上的云端 Agent 产品大多解决不了数据出内网的顾虑,而自己从零拼 RAG、编排框架和权限体系又成本极高。Yuxi(语析)正是为这个场景做的开源答案:一个可以私有部署的多租户知识智能体平台,用官方的话说就是「Cloud Agents + Knowledge RAG」——把知识库检索、知识图谱、LangGraph 多智能体编排、MCP/Skills 扩展、沙盒工具和权限管理放进同一个工作区,目标是让每个用户都拥有一个云端版的编程/办公智能体。
Yuxi 采用 MIT 协议开源(GitHub 约 7.7k Star),二开和商用部署都比较友好。本文以官方当前的 v0.8.0 为准,讲清楚它的功能构成、技术栈、Docker Compose 部署步骤、模型与知识库的配置要点,以及上手使用时最值得先跑通的几条链路。
一、功能总览:六大模块
Yuxi 的能力可以拆成六个模块,彼此是打通的:知识进入系统、智能体执行任务、团队治理在同一条链路上完成。
- 统一智能体工作台:在同一个对话界面完成提问、执行与交付。支持多轮对话,用 @ 快速引入知识库文档、个人文件或某个 Skill;界面实时展示任务拆解步骤、工具调用状态和上下文 Token 消耗;长任务在后台异步执行时,思考链路、步骤计划、子任务状态与工具调用日志全程可见,不是黑盒等待。任务完成后通过「交付卡片」预览或下载生成的文件。
- 知识库与 RAG:这是 Yuxi 的核心卖点之一,官方称之为 Agentic RAG 套件。文档上传后自动解析、分块、向量化并建立索引;支持配置 Embedding 与 Rerank 模型,后台提供检索测试工作台,可以直观看到向量初筛得分、混合检索结果和重排后的分数变化;还内置 RAG 效果评估工具,能自动生成单条 QA 和多跳 QA 评估集,量化召回率与回答质量。
- 知识图谱与知识导图:从 Milvus 知识库的文档块中抽取实体与关系,写入 Neo4j 构建图谱并参与检索;支持按关键词搜索实体、点开节点看属性、高亮探索关联子图。另外还能结合文件目录结构与元数据自动生成多层级的知识导图(主题脑图),方便快速浏览一个大知识库的全貌。
- 多智能体与扩展生态:基于 LangGraph 做编排。一个 Agent 可以自由组合基座模型、系统提示词、挂载的知识库、自定义 Tools、MCP 服务与子智能体(SubAgents);复杂任务由主智能体规划拆解,多个子智能体异步并行执行(例如分头检索不同领域的法规、分别撰写报告的不同章节),最后汇总。Skills 插件机制原生兼容,支持从 skills.sh 以及魔搭社区在线安装 Skill,并可在线编辑、配置权限与依赖。
- 沙盒工作区与文件产物:智能体通过沙盒工具读写文件,产出 Markdown 文档、数据表格、HTML 页面、可执行代码等产物,工作区文件可视化管理,支持在线预览(HTML、PDF、图表、代码,Markdown 还能在线编辑保存)并打包下载,中间产物可以在会话之间复用。
- 团队治理与运行管理:多租户设计,管理员集中管理成员与部门组织架构,按用户、部门和共享范围控制知识库、智能体、Skills、模型的访问权限;统一配置各供应商的 API Key(对普通成员完全脱敏);Dashboard 看板统计会话量、模型与工具调用、Token 消耗和沙盒运行状态,支撑容量规划与成本核算。
二、技术栈与架构要点
从仓库结构与官方架构说明看,Yuxi 的主要技术选型如下:
- 后端:FastAPI(仓库 backend 目录),智能体编排基于 LangGraph,深度智能体能力参考了 DeepAgents 的设计。
- 前端:Vue 单页应用(仓库 frontend 目录),默认访问端口 5173;后端 API 端口 5050,自带 OpenAPI 文档页。
- 向量存储:Milvus,文档块的向量索引与图谱抽取的数据源都在这里。
- 图数据库:Neo4j,存放从文档中抽取的实体与关系。
- 文档解析:接入 MinerU、PaddleOCR 云服务,也可自托管 MinerU,另保留轻量 RapidOCR,负责提取 PDF、Word、PPT、Excel、Markdown 等格式中的文本、图片与表格。
- 沙盒:默认 Container 沙盒——每段智能体执行跑在独立临时容器里,工作目录文件持久保留,无需额外准备 KVM 节点;需要 VM 级隔离或持久用户环境时可切换为 Cube 沙盒(需要 Linux/KVM 执行节点)。
- 部署形态:Docker Compose 一键拉起,仓库同时提供生产(docker-compose.prod.yml)、精简(abridge)与无知识库(no-knowledge)等多种 Compose 变体。
三、环境要求与部署(v0.8.0)
先强调一个版本注意事项:官方明确说明 0.8 仅面向全新部署,旧数据库、索引和文件布局不提供自动升级路径。已经在跑旧版本的,先看官方 0.8.0 更新说明并使用独立数据目录,不要直接覆盖升级。
第 0 步:前置条件
- 安装 Git、Docker Engine 和 Docker Compose v2。
- 准备一个可用的大模型 API(初始化脚本默认引导填写 SiliconFlow API Key,其他供应商可登录后在平台里配置)。
- macOS / Windows 使用 Docker Desktop 的 Linux 容器模式,并允许项目目录共享。
第 1 步:获取代码并初始化
git clone --branch v0.8.0 --depth 1 https://github.com/xerrors/Yuxi.git
cd Yuxi
./scripts/init.sh
Windows 在 PowerShell 中运行 .\scripts\init.ps1。初始化脚本会提示填写 SiliconFlow API Key,并自动生成独立的应用安全密钥、runner 认证密钥和实例标识,同时准备沙盒基础镜像。若目录里已有 .env,脚本会保留原有密钥;如果要切换到 Container 沙盒,需要先设置 SANDBOX_BACKEND=container 再重新运行初始化。
第 2 步:启动服务
docker compose --profile container config --quiet
docker compose --profile container up --build -d
container profile 会构建沙盒镜像并启动 runner 以及前后端、Milvus、Neo4j 等配套服务。注意沙盒默认禁止联网,这是出于安全考虑的默认策略,需要放开时按官方 Container 沙盒文档调整,生产环境不建议随意放开。
第 3 步:验证部署
docker compose --profile container ps
curl --fail http://localhost:5050/api/system/ready
接口返回的 status 为 ready 后,浏览器打开 http://localhost:5173 ,按引导初始化超级管理员并登录。API 文档位于 http://localhost:5050/docs 。官方建议的冒烟测试是:在智能体里执行一个「创建 hello.txt」的任务,再到工作区核对文件内容——能走通这一条,说明对话、沙盒执行、工作区落盘整条链路都是好的。
四、模型配置要点
Yuxi 把模型接入收敛到平台统一管理,管理员在后台集中配置凭据、统一分配模型能力,普通成员看不到明文 Key。配置时注意区分三类模型,用途完全不同:
- 聊天模型:智能体对话与任务执行的主力。平台支持 OpenAI、Anthropic、DeepSeek、Qwen 等主流供应商,也支持 OpenAI 兼容的自建端点(如 vLLM 本地部署)。初始化时填的 SiliconFlow Key 只是起点,登录后可以继续添加其他供应商。
- Embedding 模型:知识库入库时把文档块向量化、提问时把问题向量化,用哪个模型建的索引,检索时就必须用同一个,中途更换需要重建索引。
- Rerank 模型:对多路召回的结果做重排序,直接影响最终喂给大模型的上下文质量。知识库问答效果不好时,先用检索测试工作台看召回与重排分数,往往比换聊天模型更对症。
此外,平台还支持直接连接 Dify、Notion 等外部知识库服务作为数据源,通过统一检索器供智能体调用,已有知识资产的团队可以平滑接入,不必重复搬运文档。
五、核心功能使用路线
1. 建第一个知识库并验证检索
在知识库模块新建库,上传一批 PDF / Word / Markdown 文档,观察解析进度、Chunk 切片和 Token 统计。索引完成后先不要急着挂到智能体上,先用检索测试工作台输入几个真实业务问题,检查召回片段是否相关、Rerank 分数是否合理;再用 RAG 评估功能生成评估集跑一批量化结果。这一步调好了,问答效果才有保障——RAG 系统的问题十有八九出在检索而不是生成。
2. 配置一个智能体
新建智能体时按需组合:选基座模型、写系统提示词、挂载刚建好的知识库、勾选需要的内置工具与 MCP 服务、设置在部门内的共享范围。先从「只挂一个知识库 + 基础工具」的最小配置开始,在工作台里用 @ 引用知识库提问,确认回答确实引用了库内文档,再逐步加工具和 Skill。
3. 跑一个带沙盒产物的任务
给智能体一个会产出文件的任务,例如「根据知识库里的销售数据生成一份带图表的分析报告」。执行过程中关注三件事:任务拆解步骤是否合理、工具调用是否成功、涉及命令执行和项目外文件写入时会触发人工审批——默认审批模式下,当前 Project 内的写入自动放行,命令执行和 Project 外写入需要人工确认;完全信任模式则不要求审批,只建议在个人可信环境使用。任务完成后通过交付卡片预览报告并下载。
4. 构建知识图谱(可选)
对已完成索引的 Milvus 知识库提交图谱构建任务,系统会做实体识别与关系抽取并写入 Neo4j。注意图谱构建不会随文档解析自动触发,需要管理员手动提交并查看后台任务进度。构建完成后,就可以在图谱界面按关键词搜实体、探索关联子图,图谱也会参与后续检索,适合法规、制度、产品参数这类实体关系密集的资料。
5. 多智能体与团队推广
单智能体跑顺后,再尝试给主智能体配置子智能体处理并行子任务(如深度调研、多章节报告)。团队推广阶段由管理员统一维护模型凭据与 API Key、按部门划分知识库和智能体的共享范围,并通过 Dashboard 观察 Token 消耗与调用趋势,做成本归属。
除了 Web 界面,Yuxi 还提供命令行工具(登录实例、对话、发送附件、查询知识库)和公开 Agent API(外部应用可创建会话、提交消息、读取结果),方便把智能体能力嵌入已有系统。
六、注意事项
- 版本升级:再次提醒,v0.8.0 不兼容旧版数据布局,只适合全新部署;生产升级前务必先读官方生产部署指南中的升级、备份与排障章节。
- 沙盒安全模型:Container 沙盒与宿主机共享内核,官方定位是本地试用和单租户可信代码场景;如果要让不可信用户跑代码,或者需要持久用户环境,应选择 Cube 沙盒并准备 Linux/KVM 执行节点。沙盒默认禁止联网也是有意设计,不要为了省事直接全放开。
- 审批模式别图省事:完全信任模式下智能体执行命令不再逐项确认,团队环境建议保持默认审批模式,把「Project 内自动放行」的边界利用好即可。
- 许可证边界:Yuxi 本体是 MIT 协议,但 Docker Compose 引入的第三方组件(数据库、解析服务等)遵循各自许可证,商业部署或再分发前要按实际镜像版本核对上游许可。
- 模型成本意识:图谱抽取、RAG 评估集自动生成、多智能体并行执行都会成倍消耗 Token,推广前先用 Dashboard 的统计摸清单任务成本,再决定开放范围。
七、适用人群与小结
Yuxi 适合这几类团队:一是有私有化硬要求的企业/机构,数据、模型、权限必须握在自己手里,又不想从零自研 Agent 平台;二是想给内部知识库加智能问答与图谱能力的团队,它的 RAG 链路(解析、分块、向量、重排、评估)是成套的,不用东拼西凑;三是需要多人共用智能体平台的部门,多租户、部门权限、凭据脱敏、用量看板这些「企业级琐事」它都做完了;四是打算二开的开发者,MIT 协议 + FastAPI/Vue/LangGraph 的主流技术栈,上手和改造门槛都不高。
总结一下:Yuxi 不是一个单点工具,而是一套「知识库 + 知识图谱 + 多智能体 + 沙盒 + 权限治理」的完整平台,部署就是一组 Docker Compose 命令,半小时可以拉起一套可体验的环境。建议的落地节奏是:先用 Container 沙盒全新部署 v0.8.0,跑通「建库 → 检索测试 → 智能体问答 → 沙盒出报告」这条主线,再根据安全要求决定是否上 Cube 沙盒和生产 Compose,最后才向团队开放。这样每一步都有可验证的结果,不容易在复杂功能里迷路。







