尧图网站建设 
Yuxi 实战多租户知识智能体平台的私有部署、Docker Compose 快速启动与功能全景解析【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi本文基于开源仓库 Yuxi 的英文主 READMEREADME.en.md及其配套源码撰写完整覆盖 Yuxi 的核心能力定位、技术栈组成、从拉取代码到初始化.env、启动开发环境并验证服务就绪的完整操作流程以及六大功能模块的实现细节。读完本文你可以独立完成一套 Yuxi 的私有化部署与首次登录并理解其知识库 RAG、知识图谱、多智能体编排、沙盒工作区与团队治理各能力在仓库中的落点。一、Yuxi 是什么能力定位Yuxi 是一个可私有部署self-hosted、多租户的知识智能体平台它将知识库检索、知识图谱、基于 LangGraph 的多智能体编排、MCP/Skills 扩展、沙盒工具与访问控制整合到同一个工作区中。项目面向需要掌控自身数据、模型与权限的团队README 明确列出了五类核心场景构建知识问答Knowledge-based QA上传文档经过解析、分块、构建向量索引让智能体基于检索到的内容回答问题。执行多步任务组合工具、MCP、Skills、SubAgents 与沙盒产出可预览、可下载的文件。连接知识图谱从 Milvus 知识库的文档块中抽取实体与关系存入 Neo4j并参与检索。管理团队访问按用户、部门与共享范围控制知识库、智能体、Skills 和模型的访问权限。对比执行质量评估知识库检索结果或使用 Langfuse Datasets 评估完整智能体任务。从仓库结构看ARCHITECTURE.md这些能力分别落在清晰的后端模块中backend/package/yuxi/knowledge承载知识库、文档解析、评估与图谱领域backend/package/yuxi/agents定义 LangGraph 智能体体系基类、中间件、工具包、沙盒对接、Skills 与 MCP 运行时backend/package/yuxi/services是用例层覆盖请求排队、Run 生命周期、SubAgent 调用与观测。二、技术栈与运行拓扑README 给出的技术栈分层如下所有服务由 docker-compose.yml 统一编排层技术前端Vue 3 · Vite · Ant Design · G6后端FastAPI · LangGraph · ARQ worker存储PostgreSQL · Redis · MinIO · Milvus · Neo4j文档处理MinerU · PaddleX · RapidOCR部署Docker Compose前端声明与 web/package.json 一致ant-design-vue、antv/g6知识图谱渲染、markmap-lib/markmap-view思维导图、pdfjs-dist等版本为 0.7.3。docker-compose.yml 定义了开发环境的全部服务值得逐一理解服务职责关键配置apiFastAPI 服务挂载backend/server与backend/package热重载端口5050健康检查curl -f http://localhost:5050/api/system/readydocker-compose.yml#L86-L91workerARQ worker执行已派发的 AgentRun 与持久化 Durable TaskARQ_MAX_JOBS默认 140watchfiles监听热重载storage-migrator一次性 Schema 迁移进程成功后退出API 与 worker 必须等待它成功才启动sandbox-provisioner为智能体工具执行提供隔离沙盒只发布到127.0.0.1:8002默认 Docker 后端可切 KuberneteswebVue 3 开发服务器端口5173postgres/redis/minio业务数据 / 队列与事件 / 对象存储均带 healthcheck数据目录统一落在${YUXI_STATE_DIR:-./docker/volumes}milvusetcd向量检索Milvusv2.5.6standalonegraphNeo4j5.26.29知识图谱端口仅绑定127.0.0.1mineru-api/paddlex文档解析与 OCR属于allprofile可选启动需 GPUCompose 中有几个细节体现了安全边界API_KEY_DERIVATION_SECRET与SANDBOX_PROVISIONER_TOKEN使用:?语法强制要求缺失时 Compose 直接报错docker-compose.yml#L5、docker-compose.yml#L22PostgreSQL、Redis、MinIO、Milvus、Neo4j 的管理端口全部只绑定127.0.0.1不暴露公网。三、部署准备与初始化脚本前置条件安装 Docker Engine 与 Docker Compose准备一个可用的 LLM API仓库默认配置面向v0.7.3版本。1. 获取代码并初始化git clone --branch v0.7.3 --depth 1 https://gitcode.com/GitHub_Trending/yu/Yuxi cd Yuxi # Linux/macOS ./scripts/init.sh # Windows PowerShell .\scripts\init.ps1也可以手动完成复制 .env.template 为.env填入模型 API Key 与三个独立的安全密钥。2. 初始化脚本实际做了什么阅读 scripts/init.sh 可以看到它交互式收集并写入.env的内容比 README 一句话描述的要严谨得多SILICONFLOW_API_KEY必填默认以 SiliconFlow 为例的模型 API Key网页搜索供应商可选可选doubao豆包自定义搜索或tavily并写入对应密钥scripts/init.sh#L218-L239三个相互独立的安全密钥JWT_SECRET_KEY、API_KEY_DERIVATION_SECRET、SANDBOX_PROVISIONER_TOKEN。脚本的校验逻辑要求每个密钥至少 32 个非空白字符且不得与其他安全密钥相同security_secret_is_validscripts/init.sh#L56-L73直接回车则用openssl rand -hex 32自动生成YUXI_INSTANCE_ID标识这套部署的实例 ID可自动生成形如instance-hex。脚本还会预拉取开发环境所需的基础镜像python:3.13-slim、node:24-slim、milvusdb/milvus:v2.5.6、neo4j:5.26.29、postgres:16、redis:7.4.10-alpine、etcd、MinIO 以及沙盒镜像等scripts/init.sh#L294-L329并把.env权限设为600。已有.env时脚本只补齐缺失项并重新校验——升级时务必保留原有密钥尤其是JWT_SECRET_KEY和API_KEY_DERIVATION_SECRET否则会失效已有会话与 API Key 派生。YUXI_INSTANCE_ID与三个安全密钥的作用边界可以这样理解JWT 密钥签名登录态API Key 派生密钥用于服务端确定性派生并只保存 API Key 的 hash见 ARCHITECTURE.md 架构不变量中API Key 由独立服务端主密钥和客户端幂等 ID 确定性派生只保存 hash沙盒 token 则是 provisioner 与 API/worker 之间调用沙盒的鉴权凭据。四、启动开发环境并验证就绪启动与状态检查docker compose up --build -ddocker compose ps curl --fail http://localhost:5050/api/system/ready当ready接口返回 JSON 且status为ready时打开 http://localhost:5173按页面提示初始化超级管理员账号并登录。API 文档位于 http://localhost:5050/docs。服务依赖链与就绪探针的实现Compose 的依赖关系不是平铺的api与worker必须等postgres、redis、minio、sandbox-provisioner全部service_healthy且storage-migratorservice_completed_successfully之后才启动docker-compose.yml#L92-L102。storage-migrator是一次性服务成功后退出是正常状态它是 Compose 中唯一修改数据库 Schema 的进程在 PostgreSQL advisory lock 内修改并记录 business/knowledge 两个域的 Schema 版本。/api/system/ready背后的探针实现位于 backend/package/yuxi/services/readiness_service.py它依次验证PostgreSQL 能执行查询SELECT 1readiness_service.py#L33-L37Redis 能响应 ping存在一个完成启动且仍在续租的兼容 worker——检查 Redis 中 worker 健康租约键的值与短 TTL 是否都有效readiness_service.py#L51-L64。这与 ARCHITECTURE.md 中架构不变量的描述一致/api/system/health只表达 API 进程 liveness/api/system/ready才判断启动完成、PostgreSQL/Redis 可用且存在完成启动的兼容 worker。需要强调的边界是就绪接口只证明启动条件满足不代替一次真实登录或对话验证也不能单独证明知识库、模型或 Agent 业务链路正确参见 docs/advanced/ports.md 与 docs/intro/quick-start.md。开发环境的常用入口与端口来自 docs/advanced/ports.md与 Compose 一致端口服务用途5173Web开发 Web 界面5050APIAPI 与 Swagger 文档8002sandbox-provisioner本机排查仅绑定 127.0.0.17474 / 7687Neo4jHTTP 管理界面 / Bolt9000 / 9001MinIO对象 API / 管理控制台19530 / 9091MilvusgRPC / 健康检查5432PostgreSQL本机数据库维护6379Redis本机缓存和队列维护30001 / 8080mineru-api/paddlex仅allprofile 的 OCR 服务版本升级注意事项从 v0.7.1 或 v0.7.2 升级到当前版本时不要直接执行docker compose up应先行阅读 docs/advanced/deployment.md 中的生产部署与升级指南在维护窗口内完成备份和迁移。该文档同样覆盖了生产 Composedocker-compose.prod.yml的 TLS 反向代理要求、.env.prod配置与端口收敛策略。五、六大核心功能模块README 将 Yuxi 的能力组织为六个模块下面逐一展开并给出它们在仓库中的实现落点。模块解决的问题关键能力统一智能体工作区在单一界面中提问、执行任务、接收交付物多轮对话、知识检索、任务状态、人工审批知识库与 RAG为回答提供检索到的上下文多格式摄取、Embedding/Rerank、检索测试、RAG 评估知识图谱与思维导图发现实体关系、浏览知识库文件结构图谱构建、子图探索、节点详情、文件元数据图谱多智能体执行与扩展把复杂任务委托给专门角色与工具SubAgents、Skills、MCP、Tools、智能体配置沙盒工作区与文件产物把对话变成可复用的文件隔离文件系统、文件生成、在线预览、下载团队治理与运维在多用户环境中管理能力、权限与执行多租户、用户与部门权限、模型配置、API Key、Dashboard01 · 统一智能体工作区在同一个聊天界面中引用知识库文档、个人文件或扩展 Skills查看任务执行状态并直接在会话中收到回答或生成的文件用快速引用知识库、文件和特定 Skill查看任务分解、工具执行状态与上下文 token 用量预览并下载生成的产物。从源码结构看ARCHITECTURE.md 的智能体运行链路一节一次普通智能体请求的边界是前端调用POST /api/agent/runs→ 路由层 backend/server/routers/agent_router.py 校验后交给agent_request_queue_service→ 同一数据库事务中创建用户消息与 AgentRunRequest并按用户、智能体、线程检查活跃 Run 与 FIFO 队头 → 请求立即派发、进入等待队列或按reject策略拒绝只有数据库提交成功后才向 ARQ 投递 Run→ worker 取得 Run lease 后执行 LangGraph运行事件写入 Redis Stream → 前端排队阶段消费 Request SSE、派发后切换到 Run SSE断线可按数据库状态恢复。先提交 PostgreSQL 事实再投递 ARQ是 README 所称任务状态可见、排队可控背后的核心不变量。对于修改文件、调用高风险外部 API 等关键操作系统会弹出确认卡片等待人工审批对应backend/package/yuxi/agents/middlewares中的审批中间件与backend/package/yuxi/agents/tool_approval.py任务完成时以总结卡片交付结果并提供交互式产物入口。02 · 知识库与 RAG集中管理团队资料将其解析为结构化知识库智能体可检索相关文档块作为回答上下文集中管理文件与目录实时解析进度、块明细与 token 统计在管理界面中配置 Embedding 与 Rerank 算法直接测试并调优多条检索路径使用内置 RAG 评估工具与真实问答数据集度量检索与回答质量。仓库中的实现要点文档解析支持 PDF、Word、PowerPoint、Excel、Markdown 等常见格式。内置解析引擎 MinerU、PaddleX 与 RapidOCR 负责抽取文本、图片与表格再分块、建向量索引解析器统一封装在 backend/package/yuxi/knowledge/parser分块策略在 backend/package/yuxi/knowledge/chunkingmineru-api与paddlex服务通过allprofile 按需启动默认开发拓扑不要求 GPU知识库类型与外部源除内置本地向量库外还对接 Dify、Notion 等外部知识服务backend/package/yuxi/knowledge/implementations由统一检索层对智能体开放检索测试与重排交互式检索测试工作区可输入 query观察初始 embedding 相似度、混合检索结果以及重排后的分数变化RAG 评估构建基准问答数据集、批量评估检查检索召回与答案相关性等量化指标并可自动生成单跳与多跳问答对评估代码位于 backend/package/yuxi/knowledge/eval。03 · 知识图谱与思维导图把非结构化文档变成实体—关系网络在交互式图谱中探索关系或从文件层级与主题元数据生成知识图谱自动从知识库抽取实体与关系使用 Milvus/Neo4j 构建图索引按关键词检索实体点击节点查看属性并高亮相关子图从知识库文件元数据生成多级知识图谱一眼浏览业务域。对应实现backend/package/yuxi/knowledge/graphs 管理 Milvus 与 Neo4j 图谱能力Compose 中 Neo4j 服务开启了ENTITY_EMBEDDINGtruedocker-compose.yml#L315前端用antv/g6渲染图谱画布web/src/components/GraphCanvas.vue、web/src/components/GraphDetailPanel.vue用 markmap 渲染思维导图。文档解析阶段自动执行实体识别与关系抽取构建过程可查看实体数、关系数与进度。04 · 多智能体执行与扩展在单个智能体中组合模型、提示词、知识库、外部工具与专门化 SubAgents复杂任务由主智能体规划并派发多个 SubAgents 并行异步执行Skills 与 MCP 提供额外能力配置智能体的基础模型、连接的知识库、工具访问权限与系统提示词多个 SubAgents 并行异步运行适用于深度研究、数据分析、内容生成等场景例如分别研究不同领域的法规或撰写报告的不同章节结果汇总后统一收拢原生支持 Skills 扩展与 MCPModel Context Protocol。仓库落点backend/package/yuxi/agents/mcp 管理 MCP 运行时加载backend/package/yuxi/agents/skills 管理 Skills 及其投影共享与内置 Skill 才投影到只读/home/gem/skills个人 Skill 保存在用户工作区内置工具在 backend/package/yuxi/agents/toolkits。两个值得注意的机制其一是渐进式披露——Skill 的依赖工具只有在对应 Skill 被显式预加载或动态激活后才对模型开放基础工具与受 Skill 门控的工具保持边界其二是线上 Skill 安装支持 skills.sh 与 ModelScope 社区并可在界面中在线查看、编辑 Skills 及其权限与依赖。05 · 沙盒工作区与文件产物智能体通过沙盒工具读写文件。除了聊天回答还能把研究分析变成用户可在线查看与下载的 Markdown 文档、表格、HTML 页面或可执行代码通过沙盒限制工具可访问的文件范围生成带插图的报告、数据分析图表、网页等产物在浏览器中预览支持的文件格式并以归档方式下载文件。从 Compose 配置看docker-compose.yml#L201-L266sandbox-provisioner是一个独立的 FastAPI 服务默认 Docker 后端也可配置 Kubernetes 后端为每次沙盒操作拉起隔离容器支持空闲超时回收默认SANDBOX_IDLE_TIMEOUT_SECONDS120与并发删除。关键环境变量包括SANDBOX_PROVIDER默认provisioner、SANDBOX_VIRTUAL_PATH_PREFIX/home/gem/user-data、SANDBOX_EXEC_TIMEOUT_SECONDS180、SANDBOX_MAX_OUTPUT_BYTES262144。ARCHITECTURE.md 进一步明确了沙盒的三个不变量Sandbox 不在 Run 启动时预创建只在首次沙盒化的文件或命令操作时按同一 runtime scope 惰性创建沙盒虚拟路径由当前 Project Workdir、用户数据与共享 Skills 根共同约束Run 终态清理 runtime 进程但保留 Workdir。文件边界统一使用三种跨层路径数据库中的 Projectworkdir_path、Viewer 相对路径、runtime 绝对路径/home/gem/user-data/...宿主真实路径不泄露到普通服务层。06 · 团队治理与运维面向跨团队与企业协作管理员集中管理成员与部门、配置模型凭据与 API Key并通过 Dashboard 监控平台运行与使用指标按租户、用户、部门配置知识库、智能体与功能的读写权限集中配置多供应商模型与 API Key 凭据跟踪用量、请求趋势与资源负载支撑稳定运维。模型供应商支持 OpenAI、Anthropic、DeepSeek、Qwen 以及本地 Ollama/vLLM 部署API Key 集中管理、对普通成员隐藏.env.template 中列出了OPENAI_API_KEY、DEEPSEEK_API_KEY、DASHSCOPE_API_KEY、MINIMAX_API_KEY等可选配置。运营 Dashboard 实时展示请求量、token 用量、知识库检索频率与长任务队列状态。权限模型上前端路由守卫只负责页面体验FastAPI 认证依赖与 repository 可见性查询才是最终授权边界/extensions页面对所有登录用户开放但知识库、工具和 MCP 的管理能力仅管理员可见Dashboard 仅超级管理员可访问。六、文档索引与延伸阅读README 指向的文档体系在本仓库中均为可直接阅读的 Markdown 文件docs/intro/project-overview.md能力、概念与系统边界docs/intro/quick-start.md从零搭建本地环境含容器不健康、镜像拉取失败、代理构建、知识库依赖启动失败等常见问题排查docs/intro/model-config.md接入聊天、嵌入与重排模型docs/intro/knowledge-base.md创建知识库并验证检索docs/agents/agents-config.md智能体、工具与扩展配置docs/advanced/deployment.md生产部署、升级、备份与故障排查docs/develop-guides/changelog.md已发布变更docs/advanced/ports.md全部宿主机端口与安全边界CONTRIBUTING.md 与 docs/develop-guides/contributing.md开发工作流与贡献指南。七、许可与致谢Yuxi 本身采用 MIT 许可详见 LICENSE。需要特别注意通过 Docker Compose 引入的第三方组件保留各自许可在再分发或商业部署前应核对实际使用的镜像版本的上游许可与源码义务相关边界说明见 docs/advanced/deployment.md。README 同时致谢了若干对 Yuxi 实现与文档有借鉴作用的开源项目LightRAG早期图谱构建与检索思路、DeepAgents深度智能体框架、DeerFlow沙盒智能体架构思路、RAGFlow文档分块策略、LangGraph智能体编排基础、QwenPaw模型配置与个人文件区设计。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Yuxi 实战：多租户知识智能体平台的私有部署、Docker Compose 快速启动与功能全景解析
Yuxi 实战多租户知识智能体平台的私有部署、Docker Compose 快速启动与功能全景解析【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi本文基于开源仓库 Yuxi 的英文主 READMEREADME.en.md及其配套源码撰写完整覆盖 Yuxi 的核心能力定位、技术栈组成、从拉取代码到初始化.env、启动开发环境并验证服务就绪的完整操作流程以及六大功能模块的实现细节。读完本文你可以独立完成一套 Yuxi 的私有化部署与首次登录并理解其知识库 RAG、知识图谱、多智能体编排、沙盒工作区与团队治理各能力在仓库中的落点。一、Yuxi 是什么能力定位Yuxi 是一个可私有部署self-hosted、多租户的知识智能体平台它将知识库检索、知识图谱、基于 LangGraph 的多智能体编排、MCP/Skills 扩展、沙盒工具与访问控制整合到同一个工作区中。项目面向需要掌控自身数据、模型与权限的团队README 明确列出了五类核心场景构建知识问答Knowledge-based QA上传文档经过解析、分块、构建向量索引让智能体基于检索到的内容回答问题。执行多步任务组合工具、MCP、Skills、SubAgents 与沙盒产出可预览、可下载的文件。连接知识图谱从 Milvus 知识库的文档块中抽取实体与关系存入 Neo4j并参与检索。管理团队访问按用户、部门与共享范围控制知识库、智能体、Skills 和模型的访问权限。对比执行质量评估知识库检索结果或使用 Langfuse Datasets 评估完整智能体任务。从仓库结构看ARCHITECTURE.md这些能力分别落在清晰的后端模块中backend/package/yuxi/knowledge承载知识库、文档解析、评估与图谱领域backend/package/yuxi/agents定义 LangGraph 智能体体系基类、中间件、工具包、沙盒对接、Skills 与 MCP 运行时backend/package/yuxi/services是用例层覆盖请求排队、Run 生命周期、SubAgent 调用与观测。二、技术栈与运行拓扑README 给出的技术栈分层如下所有服务由 docker-compose.yml 统一编排层技术前端Vue 3 · Vite · Ant Design · G6后端FastAPI · LangGraph · ARQ worker存储PostgreSQL · Redis · MinIO · Milvus · Neo4j文档处理MinerU · PaddleX · RapidOCR部署Docker Compose前端声明与 web/package.json 一致ant-design-vue、antv/g6知识图谱渲染、markmap-lib/markmap-view思维导图、pdfjs-dist等版本为 0.7.3。docker-compose.yml 定义了开发环境的全部服务值得逐一理解服务职责关键配置apiFastAPI 服务挂载backend/server与backend/package热重载端口5050健康检查curl -f http://localhost:5050/api/system/readydocker-compose.yml#L86-L91workerARQ worker执行已派发的 AgentRun 与持久化 Durable TaskARQ_MAX_JOBS默认 140watchfiles监听热重载storage-migrator一次性 Schema 迁移进程成功后退出API 与 worker 必须等待它成功才启动sandbox-provisioner为智能体工具执行提供隔离沙盒只发布到127.0.0.1:8002默认 Docker 后端可切 KuberneteswebVue 3 开发服务器端口5173postgres/redis/minio业务数据 / 队列与事件 / 对象存储均带 healthcheck数据目录统一落在${YUXI_STATE_DIR:-./docker/volumes}milvusetcd向量检索Milvusv2.5.6standalonegraphNeo4j5.26.29知识图谱端口仅绑定127.0.0.1mineru-api/paddlex文档解析与 OCR属于allprofile可选启动需 GPUCompose 中有几个细节体现了安全边界API_KEY_DERIVATION_SECRET与SANDBOX_PROVISIONER_TOKEN使用:?语法强制要求缺失时 Compose 直接报错docker-compose.yml#L5、docker-compose.yml#L22PostgreSQL、Redis、MinIO、Milvus、Neo4j 的管理端口全部只绑定127.0.0.1不暴露公网。三、部署准备与初始化脚本前置条件安装 Docker Engine 与 Docker Compose准备一个可用的 LLM API仓库默认配置面向v0.7.3版本。1. 获取代码并初始化git clone --branch v0.7.3 --depth 1 https://gitcode.com/GitHub_Trending/yu/Yuxi cd Yuxi # Linux/macOS ./scripts/init.sh # Windows PowerShell .\scripts\init.ps1也可以手动完成复制 .env.template 为.env填入模型 API Key 与三个独立的安全密钥。2. 初始化脚本实际做了什么阅读 scripts/init.sh 可以看到它交互式收集并写入.env的内容比 README 一句话描述的要严谨得多SILICONFLOW_API_KEY必填默认以 SiliconFlow 为例的模型 API Key网页搜索供应商可选可选doubao豆包自定义搜索或tavily并写入对应密钥scripts/init.sh#L218-L239三个相互独立的安全密钥JWT_SECRET_KEY、API_KEY_DERIVATION_SECRET、SANDBOX_PROVISIONER_TOKEN。脚本的校验逻辑要求每个密钥至少 32 个非空白字符且不得与其他安全密钥相同security_secret_is_validscripts/init.sh#L56-L73直接回车则用openssl rand -hex 32自动生成YUXI_INSTANCE_ID标识这套部署的实例 ID可自动生成形如instance-hex。脚本还会预拉取开发环境所需的基础镜像python:3.13-slim、node:24-slim、milvusdb/milvus:v2.5.6、neo4j:5.26.29、postgres:16、redis:7.4.10-alpine、etcd、MinIO 以及沙盒镜像等scripts/init.sh#L294-L329并把.env权限设为600。已有.env时脚本只补齐缺失项并重新校验——升级时务必保留原有密钥尤其是JWT_SECRET_KEY和API_KEY_DERIVATION_SECRET否则会失效已有会话与 API Key 派生。YUXI_INSTANCE_ID与三个安全密钥的作用边界可以这样理解JWT 密钥签名登录态API Key 派生密钥用于服务端确定性派生并只保存 API Key 的 hash见 ARCHITECTURE.md 架构不变量中API Key 由独立服务端主密钥和客户端幂等 ID 确定性派生只保存 hash沙盒 token 则是 provisioner 与 API/worker 之间调用沙盒的鉴权凭据。四、启动开发环境并验证就绪启动与状态检查docker compose up --build -ddocker compose ps curl --fail http://localhost:5050/api/system/ready当ready接口返回 JSON 且status为ready时打开 http://localhost:5173按页面提示初始化超级管理员账号并登录。API 文档位于 http://localhost:5050/docs。服务依赖链与就绪探针的实现Compose 的依赖关系不是平铺的api与worker必须等postgres、redis、minio、sandbox-provisioner全部service_healthy且storage-migratorservice_completed_successfully之后才启动docker-compose.yml#L92-L102。storage-migrator是一次性服务成功后退出是正常状态它是 Compose 中唯一修改数据库 Schema 的进程在 PostgreSQL advisory lock 内修改并记录 business/knowledge 两个域的 Schema 版本。/api/system/ready背后的探针实现位于 backend/package/yuxi/services/readiness_service.py它依次验证PostgreSQL 能执行查询SELECT 1readiness_service.py#L33-L37Redis 能响应 ping存在一个完成启动且仍在续租的兼容 worker——检查 Redis 中 worker 健康租约键的值与短 TTL 是否都有效readiness_service.py#L51-L64。这与 ARCHITECTURE.md 中架构不变量的描述一致/api/system/health只表达 API 进程 liveness/api/system/ready才判断启动完成、PostgreSQL/Redis 可用且存在完成启动的兼容 worker。需要强调的边界是就绪接口只证明启动条件满足不代替一次真实登录或对话验证也不能单独证明知识库、模型或 Agent 业务链路正确参见 docs/advanced/ports.md 与 docs/intro/quick-start.md。开发环境的常用入口与端口来自 docs/advanced/ports.md与 Compose 一致端口服务用途5173Web开发 Web 界面5050APIAPI 与 Swagger 文档8002sandbox-provisioner本机排查仅绑定 127.0.0.17474 / 7687Neo4jHTTP 管理界面 / Bolt9000 / 9001MinIO对象 API / 管理控制台19530 / 9091MilvusgRPC / 健康检查5432PostgreSQL本机数据库维护6379Redis本机缓存和队列维护30001 / 8080mineru-api/paddlex仅allprofile 的 OCR 服务版本升级注意事项从 v0.7.1 或 v0.7.2 升级到当前版本时不要直接执行docker compose up应先行阅读 docs/advanced/deployment.md 中的生产部署与升级指南在维护窗口内完成备份和迁移。该文档同样覆盖了生产 Composedocker-compose.prod.yml的 TLS 反向代理要求、.env.prod配置与端口收敛策略。五、六大核心功能模块README 将 Yuxi 的能力组织为六个模块下面逐一展开并给出它们在仓库中的实现落点。模块解决的问题关键能力统一智能体工作区在单一界面中提问、执行任务、接收交付物多轮对话、知识检索、任务状态、人工审批知识库与 RAG为回答提供检索到的上下文多格式摄取、Embedding/Rerank、检索测试、RAG 评估知识图谱与思维导图发现实体关系、浏览知识库文件结构图谱构建、子图探索、节点详情、文件元数据图谱多智能体执行与扩展把复杂任务委托给专门角色与工具SubAgents、Skills、MCP、Tools、智能体配置沙盒工作区与文件产物把对话变成可复用的文件隔离文件系统、文件生成、在线预览、下载团队治理与运维在多用户环境中管理能力、权限与执行多租户、用户与部门权限、模型配置、API Key、Dashboard01 · 统一智能体工作区在同一个聊天界面中引用知识库文档、个人文件或扩展 Skills查看任务执行状态并直接在会话中收到回答或生成的文件用快速引用知识库、文件和特定 Skill查看任务分解、工具执行状态与上下文 token 用量预览并下载生成的产物。从源码结构看ARCHITECTURE.md 的智能体运行链路一节一次普通智能体请求的边界是前端调用POST /api/agent/runs→ 路由层 backend/server/routers/agent_router.py 校验后交给agent_request_queue_service→ 同一数据库事务中创建用户消息与 AgentRunRequest并按用户、智能体、线程检查活跃 Run 与 FIFO 队头 → 请求立即派发、进入等待队列或按reject策略拒绝只有数据库提交成功后才向 ARQ 投递 Run→ worker 取得 Run lease 后执行 LangGraph运行事件写入 Redis Stream → 前端排队阶段消费 Request SSE、派发后切换到 Run SSE断线可按数据库状态恢复。先提交 PostgreSQL 事实再投递 ARQ是 README 所称任务状态可见、排队可控背后的核心不变量。对于修改文件、调用高风险外部 API 等关键操作系统会弹出确认卡片等待人工审批对应backend/package/yuxi/agents/middlewares中的审批中间件与backend/package/yuxi/agents/tool_approval.py任务完成时以总结卡片交付结果并提供交互式产物入口。02 · 知识库与 RAG集中管理团队资料将其解析为结构化知识库智能体可检索相关文档块作为回答上下文集中管理文件与目录实时解析进度、块明细与 token 统计在管理界面中配置 Embedding 与 Rerank 算法直接测试并调优多条检索路径使用内置 RAG 评估工具与真实问答数据集度量检索与回答质量。仓库中的实现要点文档解析支持 PDF、Word、PowerPoint、Excel、Markdown 等常见格式。内置解析引擎 MinerU、PaddleX 与 RapidOCR 负责抽取文本、图片与表格再分块、建向量索引解析器统一封装在 backend/package/yuxi/knowledge/parser分块策略在 backend/package/yuxi/knowledge/chunkingmineru-api与paddlex服务通过allprofile 按需启动默认开发拓扑不要求 GPU知识库类型与外部源除内置本地向量库外还对接 Dify、Notion 等外部知识服务backend/package/yuxi/knowledge/implementations由统一检索层对智能体开放检索测试与重排交互式检索测试工作区可输入 query观察初始 embedding 相似度、混合检索结果以及重排后的分数变化RAG 评估构建基准问答数据集、批量评估检查检索召回与答案相关性等量化指标并可自动生成单跳与多跳问答对评估代码位于 backend/package/yuxi/knowledge/eval。03 · 知识图谱与思维导图把非结构化文档变成实体—关系网络在交互式图谱中探索关系或从文件层级与主题元数据生成知识图谱自动从知识库抽取实体与关系使用 Milvus/Neo4j 构建图索引按关键词检索实体点击节点查看属性并高亮相关子图从知识库文件元数据生成多级知识图谱一眼浏览业务域。对应实现backend/package/yuxi/knowledge/graphs 管理 Milvus 与 Neo4j 图谱能力Compose 中 Neo4j 服务开启了ENTITY_EMBEDDINGtruedocker-compose.yml#L315前端用antv/g6渲染图谱画布web/src/components/GraphCanvas.vue、web/src/components/GraphDetailPanel.vue用 markmap 渲染思维导图。文档解析阶段自动执行实体识别与关系抽取构建过程可查看实体数、关系数与进度。04 · 多智能体执行与扩展在单个智能体中组合模型、提示词、知识库、外部工具与专门化 SubAgents复杂任务由主智能体规划并派发多个 SubAgents 并行异步执行Skills 与 MCP 提供额外能力配置智能体的基础模型、连接的知识库、工具访问权限与系统提示词多个 SubAgents 并行异步运行适用于深度研究、数据分析、内容生成等场景例如分别研究不同领域的法规或撰写报告的不同章节结果汇总后统一收拢原生支持 Skills 扩展与 MCPModel Context Protocol。仓库落点backend/package/yuxi/agents/mcp 管理 MCP 运行时加载backend/package/yuxi/agents/skills 管理 Skills 及其投影共享与内置 Skill 才投影到只读/home/gem/skills个人 Skill 保存在用户工作区内置工具在 backend/package/yuxi/agents/toolkits。两个值得注意的机制其一是渐进式披露——Skill 的依赖工具只有在对应 Skill 被显式预加载或动态激活后才对模型开放基础工具与受 Skill 门控的工具保持边界其二是线上 Skill 安装支持 skills.sh 与 ModelScope 社区并可在界面中在线查看、编辑 Skills 及其权限与依赖。05 · 沙盒工作区与文件产物智能体通过沙盒工具读写文件。除了聊天回答还能把研究分析变成用户可在线查看与下载的 Markdown 文档、表格、HTML 页面或可执行代码通过沙盒限制工具可访问的文件范围生成带插图的报告、数据分析图表、网页等产物在浏览器中预览支持的文件格式并以归档方式下载文件。从 Compose 配置看docker-compose.yml#L201-L266sandbox-provisioner是一个独立的 FastAPI 服务默认 Docker 后端也可配置 Kubernetes 后端为每次沙盒操作拉起隔离容器支持空闲超时回收默认SANDBOX_IDLE_TIMEOUT_SECONDS120与并发删除。关键环境变量包括SANDBOX_PROVIDER默认provisioner、SANDBOX_VIRTUAL_PATH_PREFIX/home/gem/user-data、SANDBOX_EXEC_TIMEOUT_SECONDS180、SANDBOX_MAX_OUTPUT_BYTES262144。ARCHITECTURE.md 进一步明确了沙盒的三个不变量Sandbox 不在 Run 启动时预创建只在首次沙盒化的文件或命令操作时按同一 runtime scope 惰性创建沙盒虚拟路径由当前 Project Workdir、用户数据与共享 Skills 根共同约束Run 终态清理 runtime 进程但保留 Workdir。文件边界统一使用三种跨层路径数据库中的 Projectworkdir_path、Viewer 相对路径、runtime 绝对路径/home/gem/user-data/...宿主真实路径不泄露到普通服务层。06 · 团队治理与运维面向跨团队与企业协作管理员集中管理成员与部门、配置模型凭据与 API Key并通过 Dashboard 监控平台运行与使用指标按租户、用户、部门配置知识库、智能体与功能的读写权限集中配置多供应商模型与 API Key 凭据跟踪用量、请求趋势与资源负载支撑稳定运维。模型供应商支持 OpenAI、Anthropic、DeepSeek、Qwen 以及本地 Ollama/vLLM 部署API Key 集中管理、对普通成员隐藏.env.template 中列出了OPENAI_API_KEY、DEEPSEEK_API_KEY、DASHSCOPE_API_KEY、MINIMAX_API_KEY等可选配置。运营 Dashboard 实时展示请求量、token 用量、知识库检索频率与长任务队列状态。权限模型上前端路由守卫只负责页面体验FastAPI 认证依赖与 repository 可见性查询才是最终授权边界/extensions页面对所有登录用户开放但知识库、工具和 MCP 的管理能力仅管理员可见Dashboard 仅超级管理员可访问。六、文档索引与延伸阅读README 指向的文档体系在本仓库中均为可直接阅读的 Markdown 文件docs/intro/project-overview.md能力、概念与系统边界docs/intro/quick-start.md从零搭建本地环境含容器不健康、镜像拉取失败、代理构建、知识库依赖启动失败等常见问题排查docs/intro/model-config.md接入聊天、嵌入与重排模型docs/intro/knowledge-base.md创建知识库并验证检索docs/agents/agents-config.md智能体、工具与扩展配置docs/advanced/deployment.md生产部署、升级、备份与故障排查docs/develop-guides/changelog.md已发布变更docs/advanced/ports.md全部宿主机端口与安全边界CONTRIBUTING.md 与 docs/develop-guides/contributing.md开发工作流与贡献指南。七、许可与致谢Yuxi 本身采用 MIT 许可详见 LICENSE。需要特别注意通过 Docker Compose 引入的第三方组件保留各自许可在再分发或商业部署前应核对实际使用的镜像版本的上游许可与源码义务相关边界说明见 docs/advanced/deployment.md。README 同时致谢了若干对 Yuxi 实现与文档有借鉴作用的开源项目LightRAG早期图谱构建与检索思路、DeepAgents深度智能体框架、DeerFlow沙盒智能体架构思路、RAGFlow文档分块策略、LangGraph智能体编排基础、QwenPaw模型配置与个人文件区设计。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考