feat: 添加Makefile并改进错误日志记录
docs: 更新项目文档结构并删除旧文档 refactor: 优化工具工厂的错误处理逻辑
This commit is contained in:
Wenjie Zhang
parent
e51d0dccdd
commit
85e13b6481
15
.github/ISSUE_TEMPLATE/提交一个bug.md
vendored
15
.github/ISSUE_TEMPLATE/提交一个bug.md
vendored
@ -18,9 +18,24 @@ assignees: ''
|
||||
请运行以下命令，并提供部分相关日志：
|
||||
|
||||
```sh
|
||||
# macOS / Linux
|
||||
make logs
|
||||
|
||||
# Windows
|
||||
docker logs --tail=100 api-dev
|
||||
git rev-parse HEAD
|
||||
```
|
||||
|
||||
<!-- 在下面粘贴日志的输出 -->
|
||||
|
||||
```
|
||||
make logs 的输出：
|
||||
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
||||
3️⃣ 相关截图
|
||||
|
||||
|
||||
|
||||
43
AGENTS.md
Normal file
43
AGENTS.md
Normal file
@ -0,0 +1,43 @@
|
||||
|
||||
# 项目目录结构 (Project Overview)
|
||||
|
||||
Yuxi-Know 是一个基于知识图谱和向量数据库的智能知识库系统。它通过 FastAPI 提供后端 API，使用 Vue.js 构建前端界面，并利用 Docker Compose 进行整体服务的编排和管理。
|
||||
|
||||
|
||||
```
|
||||
Yuxi-Know/
|
||||
├── docker/ # Docker 配置文件
|
||||
├── scripts/ # 脚本文件，如批量上传等
|
||||
├── server/ # 服务端代码（部分）
|
||||
├── src/ # 主要源代码目录
|
||||
│ ├── agents/ # 智能体应用
|
||||
│ ├── config/ # 配置文件
|
||||
│ ├── knowledge/ # 知识库相关
|
||||
│ ├── models/ # 数据模型
|
||||
│ ├── plugins/ # 插件（存放OCR）
|
||||
│ ├── static/ # 静态资源（配置文件）
|
||||
│ └── utils/ # 工具函数
|
||||
├── web/ # 前端代码
|
||||
└── docker-compose.yml # Docker Compose 配置
|
||||
```
|
||||
|
||||
# 核心服务与容器 (Core Services & Containers)
|
||||
|
||||
项目使用 Docker Compose 管理多个服务，主要容器名称如下：
|
||||
- `api-dev` - FastAPI 后端服务
|
||||
- `web-dev` - Vue.js 前端开发服务器
|
||||
- `graph` - Neo4j 图数据库
|
||||
- `milvus` - 向量数据库，包含 etcd 和 MinIO 依赖
|
||||
- `mineru` - 可选的 MinerU OCR 服务（需要 GPU）
|
||||
- `paddlex` - 可选的 PaddleX OCR 服务（需要 GPU）
|
||||
|
||||
## 开发与调试工作流 (Development & Debugging Workflow)
|
||||
|
||||
本项目完全通过 Docker Compose 进行管理。所有开发和调试都应在运行的容器环境中进行。使用 `docker compose up -d` 命令进行构建和启动。
|
||||
|
||||
核心原则: 由于 api-dev 和 web-dev 服务均配置了热重载 (hot-reloading)，本地修改代码后无需重启容器，服务会自动更新。应该先检查项目是否已经在后台启动（`docker ps`），具体的可以阅读 [docker-compose.yml](docker-compose.yml).
|
||||
|
||||
## 风格说明
|
||||
|
||||
- UI风格要简洁，同时要保持一致性，颜色要尽量参考 [base.css](web/src/assets/css/base.css) 中的颜色。不要悬停位移，不要过度使用阴影以及渐变色。
|
||||
- Python 代码要符合 Python 的规范，尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+），使用 uvx ruff check 检查 lint。
|
||||
13
Makefile
Normal file
13
Makefile
Normal file
@ -0,0 +1,13 @@
|
||||
|
||||
.PHONY: start logs
|
||||
|
||||
start:
|
||||
docker compose up -d
|
||||
|
||||
stop:
|
||||
docker compose down
|
||||
|
||||
logs:
|
||||
@docker logs --tail=50 api-dev
|
||||
@echo "Commit ID: $$(git rev-parse HEAD)"
|
||||
@echo "System: $$(uname -a)"
|
||||
@ -1,43 +0,0 @@
|
||||
|
||||
# 项目目录结构
|
||||
|
||||
```
|
||||
Yuxi-Know/
|
||||
├── docker/ # Docker 配置文件
|
||||
├── docs/ # 项目文档
|
||||
├── scripts/ # 脚本文件，如批量上传等
|
||||
├── server/ # 服务端代码（部分）
|
||||
├── src/ # 主要源代码目录
|
||||
│ ├── agents/ # 智能体应用
|
||||
│ ├── config/ # 配置文件
|
||||
│ ├── knowledge/ # 知识库相关
|
||||
│ ├── models/ # 数据模型
|
||||
│ ├── plugins/ # 插件
|
||||
│ ├── static/ # 静态资源
|
||||
│ └── utils/ # 工具函数
|
||||
├── web/ # 前端代码
|
||||
└── docker-compose.yml # Docker Compose 配置
|
||||
```
|
||||
|
||||
# 主要容器名称
|
||||
|
||||
项目使用 Docker Compose 管理多个服务，主要容器名称如下：
|
||||
- `api-dev` - FastAPI 后端服务
|
||||
- `web-dev` - Vue.js 前端开发服务器
|
||||
- `graph` - Neo4j 图数据库
|
||||
- `milvus` - 向量数据库，包含 etcd 和 MinIO 依赖
|
||||
- `mineru` - 可选的 MinerU OCR 服务（需要 GPU）
|
||||
- `paddlex` - 可选的 PaddleX OCR 服务（需要 GPU）
|
||||
|
||||
## 项目调试
|
||||
|
||||
此项目是使用 Docker 进行部署的，使用 `docker compose up -d` 命令进行构建和启动。因此当进行任何修改的时候，不要尝试启动这个项目，应该先检查项目是否已经在后台启动（`docker ps`），具体的可以阅读 [docker-compose.yml](docker-compose.yml).
|
||||
|
||||
前端和后端都是配置了自动启动的，因此当修改完成后，会自动更新，可以使用 docker logs 查看日志。对于部分场景可以创建一个 test_router.py 在 [server/routers](server/routers) 中，然后通过 API 测试功能场景。对于前端的 UI 修改，则不用测试。
|
||||
对于后端的修改，可以写个独立的脚本尝试调用 API，比如 [test_api.py](scripts/test_api.py)。注意使用 `uv run` 来执行脚本。
|
||||
|
||||
## 风格说明
|
||||
|
||||
UI风格要简洁，同时要保持一致性，颜色要尽量参考 [base.css](web/src/assets/css/base.css) 中的颜色。不要悬停位移，不要过度使用阴影以及渐变色。
|
||||
|
||||
Python 代码要符合 Python 的规范，尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+），使用 uvx ruff check 检查 lint。
|
||||
@ -1,6 +1,5 @@
|
||||
import asyncio
|
||||
import hashlib
|
||||
import os
|
||||
import traceback
|
||||
from typing import Annotated, Any
|
||||
|
||||
from pydantic import BaseModel, Field
|
||||
@ -90,10 +89,10 @@ def get_kb_based_tools() -> dict[str, Any]:
|
||||
)
|
||||
|
||||
kb_tools[tool_id] = tool
|
||||
logger.debug(f"Successfully created tool {tool_id} for database {db_id}")
|
||||
# logger.debug(f"Successfully created tool {tool_id} for database {db_id}")
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to create tool for database {db_id}: {e}")
|
||||
logger.error(f"Failed to create tool for database {db_id}: {e}, \n{traceback.format_exc()}")
|
||||
continue
|
||||
|
||||
return kb_tools
|
||||
@ -176,7 +175,7 @@ def query_knowledge_graph(query: Annotated[str, "The keyword to query knowledge
|
||||
logger.debug(f"Knowledge graph query returned {len(result.get('triples', [])) if isinstance(result, dict) else 'N/A'} triples")
|
||||
return result
|
||||
except Exception as e:
|
||||
logger.error(f"Knowledge graph query error: {e}")
|
||||
logger.error(f"Knowledge graph query error: {e}, {traceback.format_exc()}")
|
||||
return f"知识图谱查询失败: {str(e)}"
|
||||
|
||||
def get_static_tools() -> dict[str, Any]:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user