diff --git a/.gitignore b/.gitignore index c1fbc2ef..ba8806c8 100644 --- a/.gitignore +++ b/.gitignore @@ -35,10 +35,17 @@ cache .cursor .trae .pytest_cache -*.nogit* -*.private* -*.local* + +### (企业私有代码 - 仅忽略敏感配置，不忽略代码文件) +# 移除了 *.private* 和 *_private 规则，允许 Git 本地管理 +# 通过 .git/info/exclude 或本地分支管理私有代码 *.secret* +*.nogit* +# *.local* 保留用于本地配置文件 +*.local.py +*.local.js +*.local.yaml + *.pdf src/data diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..0afba646 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,295 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## 项目概述 + +**语析 (Yuxi-Know)** 是一个基于大模型的智能知识库与知识图谱问答系统，融合了 RAG（检索增强生成）与知识图谱技术。 + +- **技术栈**: FastAPI + Vue.js 3 + LangGraph + LightRAG + Neo4j + Milvus +- **Python版本**: ≥3.11 +- **当前版本**: v0.3.0-beta +- **许可证**: MIT + +## 开发命令 + +### Docker 环境管理 + +```bash +# 启动所有服务 +make start +# 或: docker compose up -d + +# 停止所有服务 +make stop +# 或: docker compose down + +# 查看后端日志 +make logs +# 或: docker logs --tail=50 api-dev +``` + +### 代码质量 + +```bash +# 代码检查 +make lint +# 或: uv run python -m ruff check . + +# 代码格式化 +make format +# 或: uv run ruff format . && uv run ruff check . --fix + +# 查看格式化差异 +make format_diff +# 或: uv run ruff format --diff . +``` + +### 测试 + +```bash +# 运行 API 单元测试 +make router-tests +# 或: docker compose exec -T api uv run --group test pytest test/api + +# 运行特定测试文件 +docker compose exec -T api uv run --group test pytest test/api/test_xxx.py + +# 带覆盖率报告 +docker compose exec -T api uv run --group test pytest test/ --cov=src --cov-report=html +``` + +## 架构设计 + +### 分层架构 + +``` +前端层 (Vue.js 3) + ↓ HTTP/REST API +API层 (FastAPI) + ↓ +业务逻辑层 (Service) + ├─ 智能体系统 (Agent - LangGraph) + ├─ 知识库管理 (KnowledgeBase) + ├─ 任务管理 (Tasker) + └─ 认证服务 (Auth) + ↓ +数据访问层 + ├─ SQLite (对话、用户、统计) + ├─ Neo4j (知识图谱) + ├─ Milvus/Chroma (向量数据库) + └─ MinIO (文件存储) +``` + +### 核心目录结构 + +``` +src/ # 核心Python源代码 +├── agents/ # 智能体框架 (LangGraph) +│ ├── chatbot/ # 聊天机器人智能体 +│ ├── react/ # ReAct智能体 +│ └── common/ # 通用组件 (工具、模型、上下文) +├── knowledge/ # 知识库核心模块 +│ ├── implementations/ # 具体实现 (Milvus, Chroma, LightRAG) +│ └── manager.py # 知识库管理器 +├── models/ # LLM模型加载 (chat, embed, rerank) +├── storage/ # 数据存储层 +│ ├── db/ # SQLite ORM模型 +│ ├── minio/ # MinIO对象存储 +│ └── conversation/ # 对话历史管理 +├── config/ # 配置管理 +│ └── static/ # 静态配置 (models.yaml, agents_meta.yaml) +├── plugins/ # 文档处理插件 (MinerU, PaddleOCR) +└── utils/ # 工具函数 + +server/ # FastAPI应用层 +├── main.py # FastAPI应用入口 +├── routers/ # API路由 (7个主要路由) +│ ├── auth_router.py # /api/auth/* +│ ├── chat_router.py # /api/chat/* +│ ├── knowledge_router.py # /api/knowledge/* +│ ├── graph_router.py # /api/graph/* +│ ├── dashboard_router.py # /api/dashboard/* +│ ├── system_router.py # /api/system/* +│ └── task_router.py # /api/tasks/* +├── services/ # 业务逻辑服务 +│ └── tasker.py # 后台异步任务管理器 +└── utils/ # 服务层工具 (认证、用户管理) + +web/ # Vue.js前端应用 +├── src/ +│ ├── views/ # 页面视图 +│ ├── components/ # 可复用组件 +│ ├── layouts/ # 布局模板 (AppLayout, BlankLayout) +│ ├── router/ # Vue Router配置 +│ ├── stores/ # Pinia状态管理 +│ ├── apis/ # API调用层 +│ └── utils/ # 前端工具函数 +└── vite.config.js # Vite构建配置 +``` + +## 关键架构决策 + +### 1. 智能体系统 (LangGraph) + +所有智能体基于 **LangGraph** 的状态机模型构建： + +- **状态定义**: `messages[]`, `context` (包含 system_prompt, model, tools, mcps) +- **节点**: `llm_call` (调用LLM), `dynamic_tools_node` (工具执行) +- **边**: 通过 `tools_condition` 判断是否需要工具调用 +- **持久化**: 使用 SQLite Checkpointer 支持中断恢复 + +**可用工具**: +- 知识库查询工具 +- 知识图谱查询工具 +- Web搜索工具 (Tavily) +- 计算器工具 +- MySQL查询工具 + +### 2. 知识库系统 + +支持三种知识库实现： + +- **Milvus**: 生产级向量数据库 +- **Chroma**: 轻量级向量数据库 +- **LightRAG**: 图增强检索系统，自动构建知识图谱 + +所有知识库通过 `KnowledgeBaseFactory` 工厂模式创建，由 `KnowledgeBaseManager` 统一管理。 + +### 3. 异步任务系统 (Tasker) + +所有耗时操作（文档处理、知识图谱构建）均通过 **Tasker** 异步队列处理： + +- **任务队列**: FIFO队列管理 +- **进度跟踪**: 实时更新任务状态 +- **结果存储**: 完成后存储到 SQLite +- **失败重试**: 支持失败回调处理 + +### 4. 文档处理 + +支持多种格式文档： + +- **文本**: `.txt`, `.md` +- **文档**: `.doc`, `.docx`, `.pdf` +- **网页**: `.html`, `.htm` +- **数据**: `.json`, `.csv`, `.xls`, `.xlsx` +- **图片**: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.tiff` (需要 OCR) + +处理流程： +1. 选择合适的解析器 (MinerU for PDF, PaddleOCR for images) +2. 文本提取与分块 +3. Embedding 向量化 +4. 存储到向量数据库 +5. 可选：知识图谱构建 (LightRAG) + +## 配置管理 + +### 环境变量配置 + +项目根目录 `.env` 文件（从 `.env.template` 复制）: + +```bash +# 模型提供商 API Key (推荐使用硅基流动) +SILICONFLOW_API_KEY=xxx +OPENAI_API_KEY=xxx +DEEPSEEK_API_KEY=xxx +ZHIPUAI_API_KEY=xxx + +# 数据库配置 +NEO4J_URI=bolt://graph:7687 +NEO4J_USERNAME=neo4j +NEO4J_PASSWORD=0123456789 +MILVUS_URI=http://milvus:19530 + +# 文档处理服务 (需要GPU) +MINERU_OCR_URI=http://mineru:30000 +PADDLEX_URI=http://paddlex:8080 + +# Web搜索 (可选) +TAVILY_API_KEY=xxx +``` + +### 模型配置 + +`src/config/static/models.yaml` 定义所有可用的 LLM 和 Embedding 模型： + +- **LLM模型**: 支持 OpenAI, DeepSeek, SiliconFlow, Together, ZhipuAI 等 +- **Embedding模型**: 支持 OpenAI, HuggingFace 本地模型 +- **重排序模型**: 支持 Jina Reranker + +## 数据库服务 + +### Docker Compose 服务 + +| 服务名 | 端口 | 用途 | +|--------|------|------| +| `api-dev` | 5050 | FastAPI后端服务 | +| `web-dev` | 5173 | Vue.js前端服务 | +| `graph` (Neo4j) | 7474/7687 | 知识图谱数据库 | +| `milvus` | 19530 | 向量数据库 | +| `minio` | 9000/9001 | 对象存储 | +| `etcd` | 2379 | Milvus元数据存储 | + +### 访问地址 + +- **Web界面**: http://localhost:5173 +- **API文档**: http://localhost:5050/docs +- **Neo4j浏览器**: http://localhost:7474 + +## 开发最佳实践 + +### 后端开发 + +1. **路由**: 新增 API 路由在 `server/routers/` 下，并在 `server/routers/__init__.py` 注册 +2. **业务逻辑**: 核心业务代码放在 `src/` 下，避免在路由中编写复杂逻辑 +3. **异步任务**: 耗时操作必须使用 Tasker 异步处理 +4. **代码规范**: 提交前运行 `make lint` 和 `make format` +5. **测试**: 为新增 API 编写单元测试 `test/api/test_xxx.py` + +### 前端开发 + +1. **API调用**: 统一在 `web/src/apis/` 下定义 API 函数 +2. **状态管理**: 使用 Pinia stores (`web/src/stores/`) +3. **组件**: 可复用组件放在 `web/src/components/` +4. **样式**: 使用 Less，参考 `web/src/assets/css/base.css` 配色系统 +5. **热更新**: Vite 支持热更新，无需重启容器 + +### 智能体开发 + +1. **工具定义**: 在 `src/agents/common/tools.py` 定义新工具 +2. **工具包**: 复杂工具可创建 toolkit，如 `src/agents/common/toolkits/mysql/` +3. **LangGraph状态**: 在智能体 graph 定义中添加自定义 State 字段 +4. **上下文管理**: 使用 `Context` 对象传递智能体配置 + +## 重要文件 + +| 文件 | 用途 | +|------|------| +| `src/config/app.py` | 全局配置管理 | +| `server/main.py` | FastAPI应用入口 | +| `src/knowledge/manager.py` | 知识库管理器 | +| `src/agents/chatbot/graph.py` | LangGraph智能体定义 | +| `server/services/tasker.py` | 异步任务管理器 | +| `src/storage/db/models.py` | SQLAlchemy ORM模型 | +| `docker-compose.yml` | 服务编排配置 | +| `pyproject.toml` | Python依赖与工具配置 | +| `web/src/router/index.js` | 前端路由配置 | + +## 常见问题 + +1. **Milvus启动失败**: `docker compose up milvus -d && docker restart api-dev` +2. **模型加载失败**: 检查 `.env` 中的 API Key 是否正确配置 +3. **任务卡住**: 查看 Tasker 日志，可能是工具执行超时 +4. **前端无法连接后端**: 检查 Vite 配置中的代理设置 + +## v0.3 重大变更 + +- **.env 文件位置**: 从 `src/.env` 移到项目根目录 +- **数据库重构**: 不再使用 MemorySaver，改用新的存储结构 +- **自定义模型移除**: 改用自定义 provider 方式 +- **新增功能**: Dashboard 统计、消息反馈、用户管理增强 + +## 文档资源 + +- **在线文档**: https://xerrors.github.io/Yuxi-Know/ +- **视频演示**: https://www.bilibili.com/video/BV1ETedzREgY/ diff --git a/docker-compose.yml b/docker-compose.yml index e7b3a10e..104efb88 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -15,7 +15,7 @@ services: - ./saves:/app/saves - ./test:/app/test - ./scripts:/app/scripts - - ./.env :/app/.env + - ./.env:/app/.env - ${MODEL_DIR:-./models}:/models # 使用默认值处理未定义的环境变量 ports: - "5050:5050" @@ -38,8 +38,8 @@ services: - MINIO_URI=${MINIO_URI:-http://milvus-minio:9000} - MODEL_DIR_IN_DOCKER=/models - RUNNING_IN_DOCKER=true - - NO_PROXY=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex - - no_proxy=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex + - NO_PROXY=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex,api.siliconflow.cn + - no_proxy=localhost,127.0.0.1,milvus,graph,milvus-minio,milvus-etcd-dev,etcd,minio,mineru,paddlex,api.siliconflow.cn # endregion api_envs command: uv run --no-dev uvicorn server.main:app --host 0.0.0.0 --port 5050 --reload restart: unless-stopped @@ -145,7 +145,7 @@ services: - ETCD_SNAPSHOT_COUNT=50000 volumes: - ./docker/volumes/milvus/etcd:/etcd - command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd + command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd healthcheck: test: ["CMD", "etcdctl", "endpoint", "health"] interval: 60s diff --git a/server/main.py b/server/main.py index 18d41b99..947a83b8 100644 --- a/server/main.py +++ b/server/main.py @@ -9,7 +9,7 @@ from fastapi.responses import JSONResponse from starlette.middleware.base import BaseHTTPMiddleware from server.routers import router -from server.services.tasker import tasker +from server.utils.lifespan import lifespan from server.utils.auth_middleware import is_public_path from server.utils.common_utils import setup_logging @@ -24,7 +24,7 @@ RATE_LIMIT_ENDPOINTS = {("/api/auth/token", "POST")} _login_attempts: defaultdict[str, deque[float]] = defaultdict(deque) _attempt_lock = asyncio.Lock() -app = FastAPI() +app = FastAPI(lifespan=lifespan) app.include_router(router, prefix="/api") # CORS 设置 @@ -119,16 +119,5 @@ class AuthMiddleware(BaseHTTPMiddleware): app.add_middleware(LoginRateLimitMiddleware) app.add_middleware(AuthMiddleware) - -@app.on_event("startup") -async def start_tasker() -> None: - await tasker.start() - - -@app.on_event("shutdown") -async def stop_tasker() -> None: - await tasker.shutdown() - - if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0", port=5050, threads=10, workers=10, reload=True) diff --git a/server/routers/chat_router.py b/server/routers/chat_router.py index 66c43a82..e86762fb 100644 --- a/server/routers/chat_router.py +++ b/server/routers/chat_router.py @@ -112,7 +112,7 @@ async def get_agent(current_user: User = Depends(get_required_user)): metadata = yaml.safe_load(f) return {"agents": agents, "metadata": metadata} - +#TODO:[未完成]这个thread_id在前端是直接生成的1234，最好传入thread_id时做校验只允许uuid4 @chat.post("/agent/{agent_id}") async def chat_agent( agent_id: str, @@ -254,6 +254,7 @@ async def chat_agent( logger.error(f"Error saving messages from LangGraph state: {e}") logger.error(traceback.format_exc()) + #TODO:[功能建议]针对需要人工审批后再执行的工具，可以使用langgraph的interrupt方法中断对话，等待用户输入后再使用command跳转回去 async def stream_messages(): # 代表服务端已经收到了请求 yield make_chunk(status="init", meta=meta, msg=HumanMessage(content=query).model_dump()) diff --git a/server/utils/lifespan.py b/server/utils/lifespan.py new file mode 100644 index 00000000..8215fd75 --- /dev/null +++ b/server/utils/lifespan.py @@ -0,0 +1,15 @@ +import asyncio +from contextlib import asynccontextmanager + +from fastapi import FastAPI + +from server.services import tasker + +#TODO:[已完成]使用lifespan进行统一生命周期管理 + +@asynccontextmanager +async def lifespan(app: FastAPI): + await tasker.start() + """FastAPI lifespan事件管理器""" + yield + await tasker.shutdown() diff --git a/server/utils/singleton.py b/server/utils/singleton.py new file mode 100644 index 00000000..568ed675 --- /dev/null +++ b/server/utils/singleton.py @@ -0,0 +1,15 @@ +from threading import Lock + +class SingletonMeta(type): + """ + This is a thread-safe implementation of Singleton. + """ + _instances = {} + _lock: Lock = Lock() + + def __call__(cls, *args, **kwargs): + with cls._lock: + if cls not in cls._instances: + instance = super().__call__(*args, **kwargs) + cls._instances[cls] = instance + return cls._instances[cls] \ No newline at end of file diff --git a/src/agents/__init__.py b/src/agents/__init__.py index 18be435a..5b91bbd4 100644 --- a/src/agents/__init__.py +++ b/src/agents/__init__.py @@ -1,7 +1,10 @@ import asyncio +import importlib +import inspect +from pathlib import Path -from .chatbot.graph import ChatbotAgent -from .react.graph import ReActAgent +from src.agents.common.base import BaseAgent +from src.utils import logger class AgentManager: @@ -35,10 +38,51 @@ class AgentManager: agents = self.get_agents() return await asyncio.gather(*[a.get_info() for a in agents]) + def auto_discover_agents(self): + """自动发现并注册 src/agents/ 下的所有智能体。 + + 遍历 src/agents/ 目录下的所有子文件夹，如果子文件夹包含 __init__.py， + 则尝试从中导入 BaseAgent 的子类并注册。(使用自动导入的方式，支持私有agent) + """ + # 获取 agents 目录的路径 + agents_dir = Path(__file__).parent + + # 遍历所有子目录 + for item in agents_dir.iterdir(): + logger.info(f"尝试导入模块：{item}") + # 跳过非目录、common 目录、__pycache__ 等 + if not item.is_dir() or item.name.startswith("_") or item.name == "common": + continue + + # 检查是否有 __init__.py 文件 + init_file = item / "__init__.py" + if not init_file.exists(): + logger.warning(f"{item} 不是一个有效的模块") + continue + + # 尝试导入模块 + try: + module_name = f"src.agents.{item.name}" + module = importlib.import_module(module_name) + + # 查找模块中所有 BaseAgent 的子类 + for name, obj in inspect.getmembers(module): + if ( + inspect.isclass(obj) + and issubclass(obj, BaseAgent) + and obj is not BaseAgent + and obj.__module__.startswith(module_name) + ): + logger.info(f"自动发现智能体: {obj.__name__} 来自 {item.name}") + self.register_agent(obj) + + except Exception as e: + logger.warning(f"无法从 {item.name} 加载智能体: {e}") + agent_manager = AgentManager() -agent_manager.register_agent(ChatbotAgent) -agent_manager.register_agent(ReActAgent) +# 自动发现并注册所有智能体 +agent_manager.auto_discover_agents() agent_manager.init_all_agents() __all__ = ["agent_manager"] diff --git a/src/agents/chatbot/tools.py b/src/agents/chatbot/tools.py index 22eb8da9..4d6a1593 100644 --- a/src/agents/chatbot/tools.py +++ b/src/agents/chatbot/tools.py @@ -9,10 +9,20 @@ from src.agents.common.tools import get_buildin_tools from src.storage.minio import upload_image_to_minio from src.utils import logger - -@tool +#TODO:[已完成]修改了tool定义的示例，使用更符合langgraph调用的方式 +@tool(name_or_callable="全能计算器",description="可以对给定的2个数字选择进行加减乘除四种计算") def calculator(a: float, b: float, operation: str) -> float: - """Calculate two numbers. operation: add, subtract, multiply, divide""" + """ + 可以对给定的2个数字选择进行加减乘除四种计算 + + Args: + a: 第一个数字 + b: 第二个数字 + operation: 计算操作符号，可以是add，subtract，multiply，divide + + Returns: + float: 最终的计算结果 + """ try: if operation == "add": return a + b diff --git a/src/agents/react/__init__.py b/src/agents/react/__init__.py index e69de29b..eefad6b3 100644 --- a/src/agents/react/__init__.py +++ b/src/agents/react/__init__.py @@ -0,0 +1,3 @@ +from .graph import ReActAgent + +__all__ = ["ReActAgent"] diff --git a/src/config/static/models.yaml b/src/config/static/models.yaml index 6f46d682..db9f2c89 100644 --- a/src/config/static/models.yaml +++ b/src/config/static/models.yaml @@ -43,9 +43,11 @@ MODEL_NAMES: name: SiliconFlow url: https://cloud.siliconflow.cn/models base_url: https://api.siliconflow.cn/v1 - default: deepseek-ai/DeepSeek-V3.2-Exp + default: Qwen/Qwen3-32B env: SILICONFLOW_API_KEY models: + - Qwen/Qwen3-Next-80B-A3B-Thinking + - Qwen/Qwen3-32B - deepseek-ai/DeepSeek-V3.2-Exp - Qwen/Qwen3-235B-A22B-Thinking-2507 - Qwen/Qwen3-235B-A22B-Instruct-2507 @@ -98,6 +100,12 @@ MODEL_NAMES: - anthropic/claude-sonnet-4 EMBED_MODEL_INFO: + siliconflow/Pro/BAAI/bge-m3: + name: Pro/BAAI/bge-m3 + dimension: 1024 + base_url: https://api.siliconflow.cn/v1/embeddings + api_key: SILICONFLOW_API_KEY + siliconflow/BAAI/bge-m3: name: BAAI/bge-m3 dimension: 1024 @@ -127,6 +135,10 @@ EMBED_MODEL_INFO: dimension: 1024 RERANKER_LIST: + siliconflow/Pro/BAAI/bge-reranker-v2-m3: + name: Pro/BAAI/bge-reranker-v2-m3 + base_url: https://api.siliconflow.cn/v1/rerank + api_key: SILICONFLOW_API_KEY siliconflow/BAAI/bge-reranker-v2-m3: name: BAAI/bge-reranker-v2-m3 diff --git a/src/storage/conversation/manager.py b/src/storage/conversation/manager.py index a9fd7a1d..890c390c 100644 --- a/src/storage/conversation/manager.py +++ b/src/storage/conversation/manager.py @@ -12,6 +12,7 @@ from src.storage.db.models import Conversation, ConversationStats, Message, Tool from src.utils import logger from src.utils.datetime_utils import utc_now +#TODO:[未完成]待修改为异步版本 class ConversationManager: """Manager for conversation storage operations""" diff --git a/src/storage/db/manager.py b/src/storage/db/manager.py index 34fd1676..0f06d4aa 100644 --- a/src/storage/db/manager.py +++ b/src/storage/db/manager.py @@ -5,6 +5,7 @@ from contextlib import contextmanager from sqlalchemy import create_engine from sqlalchemy.orm import sessionmaker +from server.utils.singleton import SingletonMeta from src import config from src.storage.db.models import Base, User from src.utils import logger @@ -18,8 +19,10 @@ except ImportError: def validate_database_schema(db_path): return True, [] +# TODO:[优化建议]需要将数据库修改为异步的aiosqlite或者异步mysql，缓存使用Redis存储 +# TODO:[已完成]为DBManager添加单例模式 -class DBManager: +class DBManager(metaclass=SingletonMeta): """数据库管理器 - 只提供基础的数据库连接和会话管理""" def __init__(self):