296 lines
9.2 KiB
Markdown
296 lines
9.2 KiB
Markdown
# 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/
|