从一次请求到五个存储组件：Yuxi（语析）多租户知识智能体平台部署与架构解读-育师

从一次请求到五个存储组件：Yuxi（语析）多租户知识智能体平台部署与架构解读

【免费下载链接】Yuxi可私有部署的多租户知识智能体平台：统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Yuxi = Cloud Agents + Knowledge RAG, Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi

想让企业文档进模型、让智能体检索、分析并产出文件、再按部门划分数据与权限，Yuxi（语析）就是为这类需求准备的。平台本身可私有部署、面向多租户，目标用户是需要自管数据、模型和权限的团队。一套 Docker Compose 文件就能拉起从知识库到沙盒的完整拓扑。

01 先弄懂三个概念：智能体、知识库、工作区

整个平台围着三个名词转，先读它们，后面看文档不卡壳。

智能体：自己拼装出来的运行单元

智能体是 Yuxi 的基本运行单元，由模型、提示词、工具、知识库、Skills、MCP 和子智能体拼成。代码骨架是backend/package/yuxi/agents/base.py里的BaseAgent：context_schema声明可配置字段，get_graph()返回编译后的 LangGraph 图。内置ChatbotAgent负责普通对话，SubAgentBackend承接主智能体委派的子任务。

知识库：让文档可检索、可溯源

知识库保存文档，承担解析、分块、向量检索和来源信息。backend/package/yuxi/knowledge/implementations/下有四个实现：Milvus 支持在 Yuxi 内完成上传、解析、索引全链路，还能构建知识图谱；Dify 与 Notion 是只读连接器，复用已有数据集，不能在 Yuxi 内上传或索引文档。

Workdir：所有入口看到同一份文件

Workdir 是一个 Project 在用户工作区里的持久目录。智能体文件操作、文件查看器、交付物接口，读到的都是同一份文件字节。路径映射和文件原语集中在backend/package/yuxi/workspace/：paths.py负责持久路径映射，filesystem.py提供 no-follow 文件原语，workdir.py给出以 Project 为根的持久化视图。

02 什么团队该考虑 Yuxi

团队只要沾上下面三条，Yuxi 就值得评估：文档不能交给外部 SaaS，数据要自己管；组织规模较大，权限要按部门切分；任务不止一问一答，而是多步执行。

数据自管：文档进自己的知识库，检索结果带命中文本和文件来源，可回溯。
权限分部门：知识库、智能体、扩展能力在用户、部门、管理员之间划分可见与管理范围。
多步任务：智能体调用搜索、MCP、Skills、子智能体和沙盒工具，完成调研、分析与文件产出。

边界同样清楚：如果只需要一个不带权限和文件操作的单文档聊天页面，Yuxi 的能力偏多。它是面向团队协作与数据治理的平台，不是聊天封装。

03 用户实际能做什么

能力按“界面上能干什么”来分，不按后端模块罗列。

问答与检索：文档入知识库后，检索返回命中文本加文件来源。RAG（检索增强生成，即先查文档库、再让模型基于结果作答）在这条链路上完整可用。Milvus 知识库还能从已索引的文档块抽取实体和关系，写入 Neo4j，查询时把图谱结果与文本块结果融合。

多步任务：管理员配置模型、系统提示词、工具、MCP、Skills、子智能体和上下文压缩策略，智能体由 LangGraph 驱动。执行中可以读写 Workdir 文件、执行沙盒命令、搜索网页、请求用户审批或委派子智能体；产出的文件支持界面内预览和下载。耗时任务交给独立 worker，进度用 SSE（Server-Sent Events，服务端向浏览器单向推送事件流）回传。

质量评估：知识库检索效果与智能体任务表现都能量化评估，版本改动前后可以拿数据对比。

团队治理：用户、部门、共享范围、模型供应商、API Key 各有管理入口。前端的隐藏入口只改善体验，最终授权以后端接口与数据查询处的检查为准，这条原则贯穿全系统。

04 一次请求的旅程：从浏览器到 worker 🧭

一次普通智能体请求走这条链路：

Web / CLI / 外部 API ↓ FastAPI 收下请求，Message 与 Request 落库 ↓ PostgreSQL 提交之后 Redis / ARQ 把 AgentRun 投出去 ↓ Worker 执行 LangGraph，写出运行事件与最终结果 ↓ 前端经 SSE 消费过程；状态与结果在 PostgreSQL 收口

这里有一条硬规矩：消息和请求在同一数据库事务里创建，提交成功后才向 ARQ 投递 Run。队列消息不能先于数据库状态可见。该不变量写在ARCHITECTURE.md，由submit_agent_request与agent_request_queue_service的 FIFO 派发共同保证。

各存储组件的分工一目了然：

组件	职责
PostgreSQL	业务状态、知识库元数据、请求队列、LangGraph checkpoint（智能体运行快照）
Redis	ARQ 任务投递、短期运行事件、取消信号、跨进程缓存
MinIO	附件、知识库原始文件等对象数据
Milvus	向量检索
Neo4j	可选的知识图谱存储

Redis 只放短期事件，不放历史：运行终态一律落 PostgreSQL，前端断线恢复也按数据库状态补偿。

05 三条命令跑起开发环境 🐳

Docker Compose 是开发环境的事实来源。docker-compose.yml的默认拓扑包含api、worker、storage-migrator、sandbox-provisioner、web、graph（Neo4j）、etcd、minio、milvus、postgres、redis；mineru-api与paddlex是文档解析/OCR 服务，走allprofile 按需启动，需要 GPU。

沙盒经sandbox-provisioner接入，为智能体提供隔离容器环境，让它安全地执行命令与文件操作；底层运行时可选 Docker 或 Kubernetes 后端。memory后端仅供测试，没有真实隔离，生产必须用真沙盒。

数据库 Schema 的修改权只给一个进程：storage-migrator，一次性跑完即退出。API 与 worker 等它成功、校验版本匹配后才启动，自身不建表、不执行 DDL。

启动命令（Linux/macOS；Windows 改用.\scripts\init.ps1）：

git clone --branch v0.7.3 --depth 1 https://gitcode.com/GitHub_Trending/yu/Yuxi cd Yuxi ./scripts/init.sh # 生成 .env：读取模型 API Key、生成独立安全密钥 docker compose up --build -d curl --fail http://localhost:5050/api/system/ready

最后一条返回status为ready后，打开http://localhost:5173初始化超级管理员并登录；API 文档在http://localhost:5050/docs。

06 技术栈怎么搭、取舍在哪

技术选型以成熟开源组件为主，真正的工程取舍体现在目录边界上。

层	技术	职责
前端	Vue 3、Vite、Pinia	工作区、配置界面、实时运行展示
API 与运行时	FastAPI、LangGraph、ARQ	请求接入、智能体编排、后台执行
持久化	PostgreSQL	业务状态、知识库元数据、checkpoint
缓存与事件	Redis	投递、短期事件、取消、缓存
对象与检索	MinIO、Milvus、Neo4j	文件对象、向量索引、知识图谱
文档处理	MinerU、PaddleX、RapidOCR 等	文档解析、版面分析、OCR
部署	Docker Compose	开发与单机部署拓扑