From 03d4e9bad182b1a983c65066b06fb1af6de6d424 Mon Sep 17 00:00:00 2001 From: Wenjie Zhang Date: Sat, 8 Nov 2025 11:01:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=A0=E9=99=A4=E8=BF=87=E6=97=B6?= =?UTF-8?q?=E7=9A=84=E6=96=87=E6=A1=A3=E6=96=87=E4=BB=B6=EF=BC=8C=E5=8C=85?= =?UTF-8?q?=E6=8B=AC=E6=9B=B4=E6=96=B0=E8=AF=B4=E6=98=8E=E3=80=81=E8=B4=A1?= =?UTF-8?q?=E7=8C=AE=E6=8C=87=E5=8D=97=E3=80=81=E5=B8=B8=E8=A7=81=E9=97=AE?= =?UTF-8?q?=E9=A2=98=E5=92=8C=E5=BC=80=E5=8F=91=E8=B7=AF=E7=BA=BF=E5=9B=BE?= =?UTF-8?q?=EF=BC=8C=E4=BB=A5=E7=AE=80=E5=8C=96=E6=96=87=E6=A1=A3=E7=BB=93?= =?UTF-8?q?=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/changelog/0.3-release-notes.md | 106 ---------------------- docs/changelog/contributing.md | 125 -------------------------- docs/changelog/faq.md | 41 --------- docs/changelog/roadmap.md | 50 ----------- docs/latest/intro/project-overview.md | 4 +- docs/v0.3.0/intro/project-overview.md | 4 +- 6 files changed, 4 insertions(+), 326 deletions(-) delete mode 100644 docs/changelog/0.3-release-notes.md delete mode 100644 docs/changelog/contributing.md delete mode 100644 docs/changelog/faq.md delete mode 100644 docs/changelog/roadmap.md diff --git a/docs/changelog/0.3-release-notes.md b/docs/changelog/0.3-release-notes.md deleted file mode 100644 index 7d8d5fbd..00000000 --- a/docs/changelog/0.3-release-notes.md +++ /dev/null @@ -1,106 +0,0 @@ -# Yuxi-Know v0.3 更新说明 - -## 概览 - -Yuxi-Know v0.3 是一个重要的里程碑版本，包含了多项架构重构、功能增强和用户体验改进。本版本重点关注了系统架构的优化、数据存储的统一管理以及用户界面的现代化改进。 - -## 🔄 重大变更 (Breaking Changes) - -### 环境配置文件位置调整 -- **变更内容**: 将 `.env` 文件从 `src/.env` 移动到项目根目录 `.env` -- **影响**: 需要更新配置文件的复制命令和所有相关的文档引用 -- **迁移指南**: - ```bash - # 旧版本 - cp src/.env.template src/.env - - # 新版本 - cp .env.template .env - ``` - -### 配置文件管理调整 - -配置系统从 YAML 格式迁移到了基于 Pydantic BaseModel + TOML 的现代化配置系统。 - -| 项目 | v0.2.x | v0.3.x | -|------|--------|--------| -| 默认模型配置 | `src/config/static/models.yaml` | `src/config/static/models.py` | -| 用户配置 | `saves/config/base.yaml` | `saves/config/base.toml` | -| 配置格式 | YAML | Python 代码 + TOML | -| 类型安全 | ❌ 无 | ✅ Pydantic 验证 | -| IDE 支持 | ❌ 基础 | ✅ 完整智能提示 | -| 持久化策略 | 全量保存 | 选择性保存 | - - -示例：迁移自定义模型提供商 - -假设你的旧 `models.yaml` 中有： - -```yaml -# 旧的 models.yaml -MODEL_NAMES: - custom-provider: - name: "My Custom Provider" - base_url: "https://api.custom.com/v1" - default: "custom-model" - env: "CUSTOM_API_KEY" - models: - - "custom-model" - - "another-model" -``` - -需要在新的 `src/config/static/models.py` 中添加： - -```python -# 新的 models.py -DEFAULT_CHAT_MODEL_PROVIDERS: dict[str, ChatModelProvider] = { - # ... 现有配置 ... - - "custom-provider": ChatModelProvider( - name="My Custom Provider", - url="https://custom.com/docs", - base_url="https://api.custom.com/v1", - default="custom-model", - env="CUSTOM_API_KEY", - models=["custom-model", "another-model"], - ), -} -``` - - -### 数据库存储架构重构 -- **变更内容**: 重新实现了对话管理的存储与管理，不再依赖于 MemorySaver -- **影响**: 使用新的存储结构，之前存储的历史记录无法直接迁移 -- **改进**: 所有对话记录统一保存到 `server.db` 中，提供更好的数据一致性和查询性能 - -### 自定义模型支持移除 -- **变更内容**: 完全移除自定义模型支持功能 -- **替代方案**: 使用自定义 provider - -## ✨ 新增功能 - -### 1. Dashboard 统计面板 -- **用户活跃度统计**: 提供用户使用情况的详细分析 -- **工具调用统计**: 实时监控各种工具的使用频率和效果 -- **知识库分析**: 展示知识库的使用情况和性能指标 -- **智能体分析**: 统计智能体的调用次数和成功率 -- **时间序列数据**: 支持历史趋势分析和可视化展示 - -### 2. 消息反馈系统 -- **点赞点踩功能**: 用户可以对 AI 回复进行质量评价 -- **反馈数据收集**: 为模型优化提供有价值的数据支持 -- **管理员视图**: 管理员可以查看整体的反馈统计情况 - -### 3. 用户资料增强 -- **用户名更新**: 支持用户修改显示名称 -- **头像管理**: 完善用户头像上传和管理功能 -- **账户安全**: 增强账户登录失败次数限制和锁定机制 - -### 4. 文档系统 -- **VitePress 集成**: 添加完整的官方文档站点 -- **快速开始指南**: 优化新用户的上手体验 -- **配置文档**: 详细的环境配置和功能说明 -- **GitHub Actions**: 实现文档的自动部署 - - -**注意**: v0.3 版本包含多项重大变更，建议在升级前仔细阅读本文档并做好数据备份。如有问题，请通过 GitHub Issues 反馈。 \ No newline at end of file diff --git a/docs/changelog/contributing.md b/docs/changelog/contributing.md deleted file mode 100644 index 9f77ead9..00000000 --- a/docs/changelog/contributing.md +++ /dev/null @@ -1,125 +0,0 @@ -# 参与贡献 - -感谢所有贡献者的支持！ - - - 贡献者名单 - - -## 如何贡献 - -### 1. Fork 项目 - -在 GitHub 上 Fork 本项目到你的账户。 - -### 2. 创建分支 - -```bash -git checkout -b feature/amazing-feature -``` - -### 3. 提交更改 - -```bash -git commit -m 'feat: Add some amazing feature' -``` - -### 4. 推送分支 - -```bash -git push origin feature/amazing-feature -``` - -### 5. 创建 PR - -在 GitHub 上创建 Pull Request，详细描述你的更改内容。 - -## 开发指南 - -### 代码规范 - -- 遵循项目代码规范 -- Python 代码使用 `make format` 格式化 -- 使用 `make lint` 检查代码质量 -- 添加必要的测试用例 -- 更新相关文档 - -### 提交规范 - -使用清晰的提交信息： - -``` -feat: 添加新功能 -fix: 修复 bug -docs: 更新文档 -style: 代码格式调整 -refactor: 代码重构 -test: 添加测试 -chore: 构建过程或辅助工具的变动 -``` - - -## 🐞 Bug 修复发布流程 - -如果在发布 `v0.3.0` 后发现 bug： - -### ✅ 情况 1：main 上没有未完成的新功能 - -直接在 main 修复并发布： - -```bash -git commit -m "fix: resolve config parser crash" -git tag -a v0.3.1 -m "Hotfix v0.3.1" -git push origin main --tags -``` - -### ⚙️ 情况 2：main 上已有新功能未完成 - -从上一个 tag 建立 hotfix 分支： - -```bash -git checkout -b hotfix/0.3.1 v0.3.0 -# 修复问题 -git commit -m "fix: resolve config parser crash" -git push origin hotfix/0.3.1 - -# 测试后合并回 main 并打 tag -git checkout main -git merge --no-ff hotfix/0.3.1 -git tag -a v0.3.1 -m "Hotfix v0.3.1" -git push origin main --tags - -# 删除临时分支 -git branch -d hotfix/0.3.1 -git push origin --delete hotfix/0.3.1 -``` - - -### 测试要求 - -::: tip 测试 -- `make lint` / `make format` 保持代码整洁 -- `cp test/.env.test.example test/.env.test` 配置测试凭据 -- `make router-tests` 运行集成路由测试，支持 `PYTEST_ARGS="-k chat_router"` -- `uv run --group test pytest test/api` 可直接运行 pytest（容器内） -::: - -
-常用命令 - -```bash -# 全量路由测试 -make router-tests - -# 仅运行知识库相关用例 -make router-tests PYTEST_ARGS="-k knowledge_router" - -# 不经过 Makefile，直接调用 pytest -uv run --group test pytest test/api -vv -``` - -
- -## 许可证 - -本项目基于 MIT License 开源，贡献的代码将遵循相同的许可证。 diff --git a/docs/changelog/faq.md b/docs/changelog/faq.md deleted file mode 100644 index 5e0fad90..00000000 --- a/docs/changelog/faq.md +++ /dev/null @@ -1,41 +0,0 @@ -# 常见问题 - -以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。 - -- 首次运行如何创建管理员？ - - Web 首次启动会引导初始化；也可调用 API： - - `GET /api/auth/check-first-run` → `first_run=true` 时 - - `POST /api/auth/initialize` 提交 `user_id` 与 `password` - - 无默认账号，初始化后使用创建的超级管理员登录 - -- 镜像拉取/构建失败？ - - 可使用 `docker/pull_image.sh` 辅助拉取，或配置代理环境变量 `HTTP_PROXY/HTTPS_PROXY` - - 若已配置代理仍失败，可临时取消代理后重试 - - 参考：介绍 → 快速开始 → 故障排除 - -- 服务端口与访问地址？ - - Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs` - - 端口一览与说明见：高级配置 → 其他配置 → 服务端口 - -- Milvus/Neo4j 启动或连接失败？ - - 重启：`docker compose up milvus -d && docker restart api-dev` - - Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474` - -- OCR 模型或服务不可用？ - - RapidOCR 本地模型：确保 `MODEL_DIR/SWHL/RapidOCR` 下存在 `PP-OCRv4` 模型 - - MinerU/PaddleX：检查健康检查接口与 GPU/CUDA 版本 - - 参考：高级配置 → 文档解析 - -- 支持的文件类型与常见入库失败？ - - 查询：`GET /api/knowledge/files/supported-types` - - 常见失败：不支持的扩展名、内容哈希重复（去重）、OCR 服务未就绪 - -- 批量上传与转换示例？ - - 上传入库：`uv run scripts/batch_upload.py upload --db-id --directory --username --password

--base-url http://127.0.0.1:5050/api` - - 参考：高级配置 → 文档解析 - -- 登录失败被锁定？ - - 多次失败会临时锁定账户，请根据提示等待后重试 - -- 如何查看日志和状态？ - - `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志 diff --git a/docs/changelog/roadmap.md b/docs/changelog/roadmap.md deleted file mode 100644 index 7cad8d58..00000000 --- a/docs/changelog/roadmap.md +++ /dev/null @@ -1,50 +0,0 @@ -# 开发路线图 - -路线图可能会经常变更，如果有强烈的建议，可以在 [issue](https://github.com/xerrors/Yuxi-Know/issues) 中提。 - - -## v0.4 - - - -### 看板 - -- 新建 DeepAgents 智能体（暂时没有场景） -- 添加对于上传文件的支持 -- 统一图谱数据结构，优化可视化方式 [#298](https://github.com/xerrors/Yuxi-Know/issues/298) [#273](https://github.com/xerrors/Yuxi-Know/issues/273) -- 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示 -- 开发与生产环境隔离，构建生产镜像 -- 集成 LangFuse (观望) 添加用户日志与用户反馈模块，可以在 AgentView 中查看信息 - -### Bugs -- 部分异常状态下，智能体的模型名称出现重叠[#279](https://github.com/xerrors/Yuxi-Know/issues/279) -- 消息中断没有达到预期效果，看不到截断的消息 - -### 新增 -- 优化知识库详情页面，更加简洁清晰 - -### 修复 -- 修复重排序模型实际未生效的问题 - - -## v0.3 -### Added -- 添加测试脚本，覆盖最常见的功能（已覆盖API） -- 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。Tasker 中获取历史任务的时候，仅获取 top100 个 task。 -- 优化对文档信息的检索展示（检索结果页、详情页） -- 优化全局配置的管理模型，优化配置管理 -- 支持 MinerU 2.5 的解析方法 -- 修改现有的智能体Demo，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中 -- 基于 create_agent 创建 SQL Viewer 智能体 -- 优化 MCP 逻辑，支持 common + special 创建方式 -- LightRAG 知识库应该可以支持修改 LLM - -### Fixed -- 修复本地知识库的 metadata 和 向量数据库中不一致的情况。 -- v1 版本的 LangGraph 的工具渲染有问题 -- upload 接口会阻塞主进程 -- LightRAG 知识库查看不了解析后的文本，偶然出现，未复现 -- 智能体的加载状态有问题：（1）智能体加载没有动画；（2）切换对话和加载中，使用同一个loading状态。 -- 前端工具调用渲染出现问题 -- 当前 ReAct 智能体有消息顺序错乱的 bug，且不会默认调用工具 -- 修复文件管理：（1）文件选择的时候会跨数据库；（2）文件校验会算上失败的文件； \ No newline at end of file diff --git a/docs/latest/intro/project-overview.md b/docs/latest/intro/project-overview.md index c9adb0c1..7390fe1f 100644 --- a/docs/latest/intro/project-overview.md +++ b/docs/latest/intro/project-overview.md @@ -26,11 +26,11 @@ Yuxi-Know（语析）是一个基于知识图谱和向量数据库的智能知 ## 演示视频

- + 视频演示缩略图

- + 📽️ 点击查看视频演示

diff --git a/docs/v0.3.0/intro/project-overview.md b/docs/v0.3.0/intro/project-overview.md index c9adb0c1..7390fe1f 100644 --- a/docs/v0.3.0/intro/project-overview.md +++ b/docs/v0.3.0/intro/project-overview.md @@ -26,11 +26,11 @@ Yuxi-Know（语析）是一个基于知识图谱和向量数据库的智能知 ## 演示视频