diff --git a/README.en.md b/README.en.md index 96847319..4e2abe19 100644 --- a/README.en.md +++ b/README.en.md @@ -1,5 +1,7 @@
-

Yuxi - A Multi-tenant Harness Platform Combining Knowledge Bases and Knowledge Graphs

+

Yuxi

+ +

A multi-tenant agent platform combining RAG and knowledge graphs
Make enterprise knowledge retrievable, reasoned over, and deliverable by agents

[![](https://img.shields.io/badge/Docker-2496ED?style=flat&logo=docker&logoColor=ffffff)](https://github.com/xerrors/Yuxi/blob/main/docker-compose.yml) [![](https://img.shields.io/github/issues/xerrors/Yuxi?color=F48D73)](https://github.com/xerrors/Yuxi/issues) @@ -18,19 +20,36 @@ **Image generated by GPT-Image-2.* +## Introduction + +Yuxi is an LLM-powered platform for building knowledge-base and knowledge-graph agents. It unifies **RAG retrieval**, **LightRAG knowledge graphs**, and **LangGraph multi-agent orchestration** into a single multi-tenant workspace: administrators configure knowledge bases, models, and permissions, while users chat — in a ChatGPT-like interface — with agents that can mount Skills, MCPs, sub-agents, and sandbox tools, and receive answers with cited sources, graph-based reasoning, and deliverable artifacts. + ## Core Features -- **Agent development**: Built on LangGraph, with support for sub-agents, Skills, MCPs, Tools, and middleware. -- **Knowledge base (RAG)**: Multi-format document parsing, Embedding / Rerank configuration, and knowledge base evaluation. -- **Knowledge graph**: Graph construction and visualization based on LightRAG, with property graph support for agent reasoning. -- **Platform and engineering**: Vue + FastAPI architecture with dark mode, Docker-based development, and production-oriented deployment. +- 🤖 **Agent development** — Built on LangGraph, with sub-agents (SubAgents), Skills, MCPs, Tools, and middleware; long-running tasks run asynchronously on a background worker, backed by a sandbox file system for persisting, previewing, and downloading tool artifacts. +- 📚 **Knowledge base (RAG)** — Multi-format document parsing (MinerU / PaddleX / OCR), configurable Embedding and Rerank models, knowledge base evaluation, in-app PDF / image preview, and retrieval sources backfilled as chat citations. +- 🕸️ **Knowledge graph** — Graph construction and visualization based on LightRAG, with property graph support that feeds directly into agent reasoning. +- 🏢 **Multi-tenancy & permissions** — User / department-level access control, unified model provider configuration, and API Key authentication for external system integration. +- ⚙️ **Platform & engineering** — Vue + FastAPI architecture, ready-to-run Docker Compose deployment, dark mode, a lightweight LITE startup mode, and production-grade orchestration. + +## Tech Stack + +| Layer | Technologies | +| --- | --- | +| Frontend | Vue 3 · Vite · Pinia | +| Backend | FastAPI · LangGraph · ARQ (async worker) | +| Storage | PostgreSQL · Redis · MinIO · Milvus · Neo4j | +| Doc parsing | MinerU · PaddleX · RapidOCR | +| Deployment | Docker Compose | ## Quick Start -Clone the repository and initialize the project: +**Prerequisites**: [Docker](https://docs.docker.com/get-docker/) and Docker Compose installed, plus at least one OpenAI-compatible LLM API. + +**1. Clone and initialize** ```bash -git clone --branch v0.6.2 --depth 1 https://github.com/xerrors/Yuxi.git +git clone --branch v0.7.0.dev0 --depth 1 https://github.com/xerrors/Yuxi.git cd Yuxi # Linux/macOS @@ -40,13 +59,17 @@ cd Yuxi .\scripts\init.ps1 ``` -Start the project with Docker: +**2. Start with Docker** ```bash docker compose up --build ``` -After the services are ready, open `http://localhost:5173`. +**3. Open the platform** + +Once the services are ready, open `http://localhost:5173` in your browser and sign in with the admin account generated during initialization. + +> 💡 If you don't need heavy dependencies like knowledge bases / graphs, run `make up-lite` for a lightweight LITE mode with faster cold starts. See the [docs](https://xerrors.github.io/Yuxi) for more deployment details. ## Examples and Demo diff --git a/README.md b/README.md index d7139bab..f1fb902f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@
-

语析 - 结合知识库与知识图谱的多租户 Harness 平台

+

语析 Yuxi

+ +

融合 RAG 与知识图谱的多租户智能体平台
让企业知识可被智能体检索、推理与交付

[![](https://img.shields.io/badge/Docker-2496ED?style=flat&logo=docker&logoColor=ffffff)](https://github.com/xerrors/Yuxi/blob/main/docker-compose.yml) [![](https://img.shields.io/github/issues/xerrors/Yuxi?color=F48D73)](https://github.com/xerrors/Yuxi/issues) @@ -20,16 +22,46 @@ **图由 GPT-Image-2 生成* +## 简介 + +语析(Yuxi)是一个基于大模型的智能知识库与知识图谱智能体开发平台。它把 **RAG 检索**、**LightRAG 知识图谱** 与 **LangGraph 多智能体编排** 整合进统一的多租户工作台:管理员配置知识库、模型与权限,用户在类 ChatGPT 的界面中与可挂载 Skills、MCP、子智能体和沙盒工具的智能体对话,并获得带引用来源、知识图谱推理与可交付产物的回答。 + ## 核心特性 -- **智能体开发**:基于 LangGraph,支持子智能体、Skills、MCPs、Tools 与中间件机制 -- **知识库(RAG)**:多格式文档解析,支持 Embedding / Rerank 配置及知识库评估 -- **知识图谱**:基于 LightRAG 的图谱构建与可视化,支持属性图谱并参与智能体推理 -- **平台与工程化**:Vue + FastAPI 架构,支持暗黑模式、Docker 与生产级部署 +- 🤖 **智能体开发** —— 基于 LangGraph 构建,支持子智能体(SubAgents)、Skills、MCP、Tools 与中间件机制;长耗时任务由后台 worker 异步执行,配套沙盒文件系统支持工具产物落盘、预览与下载。 +- 📚 **知识库(RAG)** —— 多格式文档解析(MinerU / PaddleX / OCR),可配置 Embedding 与 Rerank 模型,支持知识库评估与 PDF / 图片在线预览,检索来源回填到对话引用。 +- 🕸️ **知识图谱** —— 基于 LightRAG 的图谱构建与可视化,支持属性图谱,并作为检索增强直接参与智能体推理。 +- 🏢 **多租户与权限** —— 用户 / 部门级权限管理,模型供应商统一配置,支持 API Key 认证供外部系统集成调用。 +- ⚙️ **平台与工程化** —— Vue + FastAPI 架构,开箱即用的 Docker Compose 部署,支持暗黑模式、LITE 轻量启动与生产级编排。 + +## 技术栈 + +| 层 | 技术 | +| --- | --- | +| 前端 | Vue 3 · Vite · Pinia | +| 后端 | FastAPI · LangGraph · ARQ (异步 worker) | +| 存储 | PostgreSQL · Redis · MinIO · Milvus · Neo4j | +| 文档解析 | MinerU · PaddleX · RapidOCR | +| 部署 | Docker Compose | ## 最新动态 +
+[2026/06] v0.7.0 开发中(重要不兼容变更) + +### 重大变更 + +- **模型配置收敛**:移除旧版 v1 模型配置与 Ollama 支持,运行时统一使用 `provider_id:model_id` 与独立 provider 模块,自定义 provider 迁移到数据库 +- **智能体运行时收敛**:用户可见的 `AgentConfig` 收敛为数据库持久化的一级 `Agent`,新增 `/api/agent` 管理与运行接口,前端只提交 `agent_id` +- **知识库能力收敛**:移除 Upload 与 LightRAG 知识库/图谱能力,知识库类型收敛为 **Milvus** 与只读连接器(**Dify**、**Notion**);知识图谱仅保留 Milvus 知识库内的构建/展示/检索 +- **Skill 安装与权限收敛**:以 `source_type / share_config / enabled` 表达来源、生效范围与启用状态;内置 Skill 启动自动入库并默认全局启用,上传/远程统一改为「解析草稿 → 确认安装」 +- **用户身份命名收敛**:业务登录标识统一为字符串 `uid` + +详见 [开发路线图](docs/develop-guides/roadmap.md)。 + +
+
[2026/04/01] v0.6.0 版本发布 @@ -87,10 +119,12 @@ ## 快速开始 -克隆代码,并初始化 +**前置要求**:已安装 [Docker](https://docs.docker.com/get-docker/) 与 Docker Compose,并准备至少一个兼容 OpenAI 接口的大模型 API。 -``` -git clone --branch v0.6.2 --depth 1 https://github.com/xerrors/Yuxi.git +**1. 克隆代码并初始化** + +```bash +git clone --branch v0.7.0.dev0 --depth 1 https://github.com/xerrors/Yuxi.git cd Yuxi # Linux/macOS @@ -100,13 +134,17 @@ cd Yuxi .\scripts\init.ps1 ``` -然后需要使用 docker 启动项目 +**2. 使用 Docker 启动** -``` +```bash docker compose up --build ``` -等待启动完成后,访问 `http://localhost:5173` +**3. 访问平台** + +等待启动完成后,浏览器打开 `http://localhost:5173`,使用初始化时生成的管理员账户登录即可。 + +> 💡 不需要知识库 / 知识图谱等重依赖时,可使用 `make up-lite` 以 LITE 轻量模式启动,加快冷启动速度。更多部署说明见 [项目文档](https://xerrors.github.io/Yuxi)。 ## 示例与演示 diff --git a/docs/advanced/document-processing.md b/docs/advanced/document-processing.md index 0f019432..3464b867 100644 --- a/docs/advanced/document-processing.md +++ b/docs/advanced/document-processing.md @@ -119,3 +119,4 @@ HOST_IP=your_server_ip 2. **GPU 要求**:MinerU 和 PP-Structure-V3 需要 GPU 支持 3. **API 密钥**:部分服务需要额外的 API 密钥配置 4. **超时处理**:复杂文档解析可能耗时较长,可通过 `MINERU_TIMEOUT` 环境变量调整超时时间 +5. **文件大小限制**:单个上传文件大小不超过 100 MB diff --git a/docs/agents/middleware.md b/docs/agents/middleware.md index 4325dbf0..6ec41273 100644 --- a/docs/agents/middleware.md +++ b/docs/agents/middleware.md @@ -41,4 +41,4 @@ async def get_graph(self): ## 自定义中间件 -新增中间件时,将其放入 `backend/package/yuxi/agents/common/middlewares` 目录,然后在智能体的 `middleware` 列表中引用即可。 +新增中间件时,将其放入 `backend/package/yuxi/agents/middlewares` 目录,然后在智能体的 `middleware` 列表中引用即可。该目录下已内置知识库挂载(`knowledge_base`)、Skills 注入(`skills`)、附件上下文(`attachment`)、子智能体任务(`subagent_task`)、上下文压缩(`summary`)、动态工具(`dynamic_tool`)等中间件。 diff --git a/docs/agents/sandbox-architecture.md b/docs/agents/sandbox-architecture.md index 966fb1d1..edbde25d 100644 --- a/docs/agents/sandbox-architecture.md +++ b/docs/agents/sandbox-architecture.md @@ -293,7 +293,7 @@ CHECK_YUXI_SANDBOX_ENV_EXISTS=True ## 十四、和旧版文档相比,今天最重要的理解方式 -当前项目不应再按“应用直接管理一个长期存在的本地 sandbox 服务”去理解。更准确的认识应该是:Yuxi 只管理线程和上下文;provisioner 负责创建线程对应的沙盒实例;文件系统不是简单地暴露一个容器根目录,而是把可写工作区、只读 skills 和只读知识库组合成一个受控命名空间。 +当前项目不应再按“应用直接管理一个长期存在的本地 sandbox 服务”去理解。更准确的认识应该是:Yuxi 只管理线程和上下文;provisioner 负责创建线程对应的沙盒实例;文件系统不是简单地暴露一个容器根目录,而是把可写工作区、只读 skills 等组合成一个受控命名空间(知识库不再映射为沙盒目录,改由 `query_kb`/`open_kb_document` 等工具访问)。 因此,当你在界面上“启用沙盒”或者在文档里“选择 K8s”时,本质上做的不是切换一段业务逻辑,而是在切换 provisioner 的底层实例承载方式。选择 `docker` 时,沙盒由当前部署机上的 Docker daemon 动态创建;选择 `kubernetes` 时,沙盒由目标 K8s 集群动态创建。Yuxi 自己始终只面对一个 provisioner 服务地址。 diff --git a/docs/agents/skills-management.md b/docs/agents/skills-management.md index 5ebb29c0..07789825 100644 --- a/docs/agents/skills-management.md +++ b/docs/agents/skills-management.md @@ -164,11 +164,11 @@ Skills 之间可以建立依赖关系,形成一个松耦合的技能网络。 2. 递归展开 `skill_dependencies`,派生 `_prompt_skills` 和 `_readable_skills` 3. 将 `_prompt_skills` 对应的技能说明注入到系统提示词中 -这意味着:只要配置了某个 Skill,它的依赖 Skill 就会立即进入提示词和 `/home/gem/skills` 只读范围。 +这意味着:只要配置了某个 Skill,它的依赖 Skill 就会立即进入提示词和沙盒 `/home/gem/skills` 只读范围。 **阶段二:技能激活** -当 Agent 通过 `read_file` 工具读取 `/skills//SKILL.md` 时,视为"激活"该技能。系统会: +当 Agent 通过 `read_file` 工具读取 `/home/gem/skills//SKILL.md` 时,视为"激活"该技能。系统会: 1. 验证该技能在可见列表中 2. 将其添加到 `activated_skills` 列表 3. 后续的模型调用会使用激活列表来加载依赖 @@ -211,13 +211,13 @@ Skills 管理采用基于角色的权限控制: ### Agent 如何使用 Skills -1. **提示词注入**:系统会在 Agent 的系统提示词开头自动插入可用 Skills 的描述 -2. **文件访问**:Skills 目录以只读方式挂载到 `/skills//...` +1. **提示词注入**:系统在每次模型请求时动态注入可用 Skills 的描述(请求级注入,避免污染 runtime context) +2. **文件访问**:Skills 目录以只读方式挂载到 `/home/gem/skills//...` 3. **工具调用**:当 Agent 需要使用某个 Skill 时,会先读取对应的 SKILL.md 了解使用方法 ### 文件操作限制 -运行时 `/skills` 路径有以下限制: +运行时 `/home/gem/skills` 路径有以下限制: - **只读**:Agent 只能读取文件内容 - **禁止写入**:不能创建、修改或删除文件 - **路径安全**:所有路径都经过安全校验,防止目录穿越攻击 diff --git a/docs/agents/tools-system.md b/docs/agents/tools-system.md index db3c03b6..b68f4b4e 100644 --- a/docs/agents/tools-system.md +++ b/docs/agents/tools-system.md @@ -62,14 +62,16 @@ Qwen-Image 生成能力已迁移为内置 Skill `image-gen`。模型调用与图 from yuxi.agents.toolkits.kbs import get_common_kb_tools kb_tools = get_common_kb_tools() -# 返回: [list_kbs, get_mindmap, query_kb] +# 返回: [list_kbs, get_mindmap, query_kb, find_kb_document, open_kb_document] ``` | 工具 | 说明 | |------|------| | `list_kbs` | 列出用户可访问的知识库 | | `get_mindmap` | 获取知识库的思维导图结构 | -| `query_kb` | 在指定知识库中检索内容 | +| `query_kb` | 在指定知识库中检索内容,返回结构化的 `resource_id`(即 `kb_id`)/`file_id`/`chunk` | +| `find_kb_document` | 在已知文件内按关键词或正则定位内容 | +| `open_kb_document` | 按 `file_id` 分段打开知识库文档(默认窗口 1800 行) | ## 工具组装 @@ -99,6 +101,6 @@ async def get_tools_from_context(self, context) -> list: ## Skills 集成 -Skills 与工具是两种不同的扩展机制。工具是具体的功能实现,而 Skills 是包含提示词、工具依赖和元数据的完整技能包。通过 `context.skills` 配置 Skills 时,对应的技能文件会被挂载到 `/skills//...`,智能体可以通过读取 SKILL.md 来了解如何使用这些技能。 +Skills 与工具是两种不同的扩展机制。工具是具体的功能实现,而 Skills 是包含提示词、工具依赖和元数据的完整技能包。通过 `context.skills` 配置 Skills 时,对应的技能文件会被挂载到沙盒的 `/home/gem/skills//...`,智能体可以通过读取 SKILL.md 来了解如何使用这些技能。 关于 Skills 的详细机制,请参阅 [Skills 管理](./skills-management.md)。 diff --git a/docs/intro/evaluation.md b/docs/intro/evaluation.md index de79c1a8..adfa2cb9 100644 --- a/docs/intro/evaluation.md +++ b/docs/intro/evaluation.md @@ -56,7 +56,7 @@ JSONL 只是导入和导出的交换格式。导入后,系统会把评估数 ## 运行评估 -在知识库详情页点击「评估」标签,选择评估基准后配置: +在知识库详情页左侧边栏,「评估基准」Tab 用于管理评估数据集,「RAG 评估」Tab 用于运行评估并查看结果。在「RAG 评估」中选择评估数据集后配置: 1. **答案生成模型**(可选):基于检索到的文档块生成答案 2. **评判模型**(可选):评估生成答案与标准答案的一致性 diff --git a/docs/intro/knowledge-base.md b/docs/intro/knowledge-base.md index 41860338..2b9db944 100644 --- a/docs/intro/knowledge-base.md +++ b/docs/intro/knowledge-base.md @@ -1,6 +1,6 @@ # 知识库与知识图谱 -Yuxi 提供文档知识库、向量检索和知识图谱构建能力。当前支持 Milvus 知识库、Milvus 知识库内的图谱构建/展示/检索,以及 Dify Dataset 只读检索。 +Yuxi 提供文档知识库、向量检索和知识图谱构建能力。当前支持 Milvus 知识库、Milvus 知识库内的图谱构建/展示/检索,以及 Dify Dataset、Notion Data Source 只读检索。 ## 为什么需要知识库 @@ -15,17 +15,18 @@ Yuxi 提供文档知识库、向量检索和知识图谱构建能力。当前支 | 类型 | 特点 | 适用场景 | |------|------|----------| | **Milvus** | 高性能向量检索,支持文档入库、检索测试、评估和知识图谱构建 | 自建文档知识库与生产检索 | -| **Dify** | 连接 Dify Dataset 检索 API,只读使用 | 复用已有 Dify 数据集 | +| **Dify** | 连接 Dify Dataset 检索 API,只读连接器 | 复用已有 Dify 数据集 | +| **Notion** | 连接 Notion Data Source 检索 API,只读连接器 | 复用已有 Notion 页面内容 | -历史 LightRAG 类型不再作为受支持类型展示或创建。 +只读连接器(Dify、Notion)仅用于检索,不支持上传与入库;历史 LightRAG 类型不再作为受支持类型展示或创建。 ## 创建知识库 访问 Web 界面的「知识库」页面,点击「新建知识库」: 1. 填写知识库名称和描述 -2. 选择 Milvus 或 Dify -3. Milvus 配置嵌入模型和分块策略;Dify 配置 API URL、Token 和 Dataset ID +2. 选择知识库类型(Milvus、Dify 或 Notion) +3. Milvus 配置嵌入模型和分块策略;只读连接器(Dify、Notion)按类型动态渲染连接参数(如 API URL、Token、Dataset ID 等) 4. 配置访问权限 5. 保存 @@ -51,7 +52,7 @@ Milvus 文件从上传到可检索,经历三个阶段: ### 3. 入库阶段 -系统对 Markdown 内容进行分块,将 chunk 元数据保存到 PostgreSQL,并将向量写入 Milvus。 +系统对 Markdown 内容进行分块,将 chunk 内容与元数据双写到 PostgreSQL 的 `knowledge_chunks` 表,并将向量写入 Milvus。 在前端界面中,默认会自动完成前两个阶段。如果需要自动入库,勾选「上传后自动入库」选项;否则需要手动点击入库按钮。 @@ -60,8 +61,8 @@ Milvus 文件从上传到可检索,经历三个阶段: 每个知识库可以配置独立的访问权限: - **全局共享**:所有用户可访问 -- **部门授权**:仅指定部门可访问 -- **私有**:仅创建者和管理员可访问 +- **部门共享**:指定部门可访问,且必须包含当前用户所在部门 +- **指定人可访问**:仅创建者、管理员及被明确授权的人员可访问 权限规则: @@ -71,7 +72,7 @@ Milvus 文件从上传到可检索,经历三个阶段: ## 知识图谱 -Milvus 知识库详情页提供「知识图谱」Tab。图谱构建流程会从已入库 chunks 中抽取实体和关系,并写入 Neo4j 作为图存储。 +Milvus 知识库详情页提供「知识图谱」Tab。图谱构建流程会从已入库 chunks 中抽取实体和关系,将 entity/triple 本体与 chunk 引用写入 Neo4j 和 PostgreSQL,并为唯一实体/三元组建立 Milvus 语义索引;检索时可召回图谱实体与三元组,并与 chunk 命中结果融合(RRF)。 主要能力: diff --git a/docs/intro/project-overview.md b/docs/intro/project-overview.md index b91611e8..c6be39dc 100644 --- a/docs/intro/project-overview.md +++ b/docs/intro/project-overview.md @@ -18,8 +18,8 @@ Yuxi (语析) 是一个智能知识库和知识图谱 Agent 开发平台,能 | 状态管理 | Pinia | 前端集中式状态管理 | | 后端 API | FastAPI, Uvicorn | 高性能异步 Python Web 框架 | | Agent 框架 | LangGraph v1 | 声明式 Agent 编排与状态管理 | -| 知识库 | Milvus, Dify | 基于向量存储与外部 Dataset 的 RAG 实现 | -| 图数据库 | Neo4j | 知识图谱存储与查询 | +| 知识库 | Milvus(可建库入库)、Dify / Notion(只读连接器) | 向量知识库 RAG 与外部只读数据源检索 | +| 图数据库 | Neo4j | Milvus 知识库内知识图谱存储与查询 | | 文档处理 | MinerU, PaddleX, RapidOCR | 多格式文档解析与 OCR | | 任务队列 | Redis, PostgreSQL Workers | 异步任务处理 | | 对象存储 | MinIO | 文件与文档存储 | @@ -47,11 +47,11 @@ Yuxi 提供完整的知识入库链路,而不是只做检索接口封装。文 ### 3. 知识图谱参与推理,而不只是展示 -Yuxi 的知识图谱能力不是孤立的可视化模块,而是和 Milvus 知识库入库链路联动的。系统可以从已入库 chunks 中抽取实体和关系,写入 Neo4j,并在知识库详情页展示和检索子图。 +Yuxi 的知识图谱能力不是孤立的可视化模块,而是和 Milvus 知识库入库链路联动的。系统可以从已入库 chunks 中抽取实体和关系,写入 Neo4j 与 PostgreSQL 并为唯一实体/三元组建立 Milvus 语义索引;检索时可召回图谱实体与三元组,并与 chunk 命中结果融合(RRF),在知识库详情页展示和检索子图。 ### 4. 面向生产落地的文档理解与平台能力 -为了让知识真正可用,Yuxi 集成了 MinerU、PP-Structure-V3、Docling 等解析能力,覆盖 PDF、Office、Markdown、图片等常见格式,解决原始资料进入系统前的结构化处理问题。 +为了让知识真正可用,Yuxi 集成了 MinerU、PP-Structure-V3、RapidOCR、DeepSeek OCR 等解析能力,覆盖 PDF、Office、Markdown、图片等常见格式,解决原始资料进入系统前的结构化处理问题。 在此基础上,平台还补齐了业务落地常用的工程能力,例如: diff --git a/docs/intro/quick-start.md b/docs/intro/quick-start.md index afe7117b..2b699b2b 100644 --- a/docs/intro/quick-start.md +++ b/docs/intro/quick-start.md @@ -20,7 +20,7 @@ ```bash # 克隆最新版本 -git clone --branch v0.6.2 --depth 1 https://github.com/xerrors/Yuxi.git +git clone --branch v0.7.0.dev0 --depth 1 https://github.com/xerrors/Yuxi.git cd Yuxi ``` @@ -28,7 +28,7 @@ cd Yuxi | 版本 | 适用场景 | |------|----------| -| v0.6.x | 当前开发版本,包含最新特性 | +| v0.7.x | 当前开发版本,包含最新特性 | | main | 开发版本,包含最新特性(可能不稳定) | ### 步骤二:配置环境变量