docs: 删除过时的文档文件，包括更新说明、贡献指南、常见问题和开发路线图，以简化文档结构
This commit is contained in:
Wenjie Zhang
parent
62cdd8648f
commit
03d4e9bad1
@ -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 反馈。
|
||||
@ -1,125 +0,0 @@
|
||||
# 参与贡献
|
||||
|
||||
感谢所有贡献者的支持！
|
||||
|
||||
<a href="https://github.com/xerrors/Yuxi-Know/contributors">
|
||||
<img src="https://contributors.nn.ci/api?repo=xerrors/Yuxi-Know" alt="贡献者名单">
|
||||
</a>
|
||||
|
||||
## 如何贡献
|
||||
|
||||
### 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（容器内）
|
||||
:::
|
||||
|
||||
<details>
|
||||
<summary>常用命令</summary>
|
||||
|
||||
```bash
|
||||
# 全量路由测试
|
||||
make router-tests
|
||||
|
||||
# 仅运行知识库相关用例
|
||||
make router-tests PYTEST_ARGS="-k knowledge_router"
|
||||
|
||||
# 不经过 Makefile，直接调用 pytest
|
||||
uv run --group test pytest test/api -vv
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目基于 MIT License 开源，贡献的代码将遵循相同的许可证。
|
||||
@ -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 <id> --directory <dir> --username <u> --password <p> --base-url http://127.0.0.1:5050/api`
|
||||
- 参考：高级配置 → 文档解析
|
||||
|
||||
- 登录失败被锁定？
|
||||
- 多次失败会临时锁定账户，请根据提示等待后重试
|
||||
|
||||
- 如何查看日志和状态？
|
||||
- `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志
|
||||
@ -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) <Badge type="info" text="0.4" />
|
||||
- 集成智能体评估，首先使用命令行来实现，然后考虑放在 UI 里面展示
|
||||
- 开发与生产环境隔离，构建生产镜像 <Badge type="info" text="0.4" />
|
||||
- 集成 LangFuse (观望) 添加用户日志与用户反馈模块，可以在 AgentView 中查看信息
|
||||
|
||||
### Bugs
|
||||
- 部分异常状态下，智能体的模型名称出现重叠[#279](https://github.com/xerrors/Yuxi-Know/issues/279)
|
||||
- 消息中断没有达到预期效果，看不到截断的消息
|
||||
|
||||
### 新增
|
||||
- 优化知识库详情页面，更加简洁清晰
|
||||
|
||||
### 修复
|
||||
- 修复重排序模型实际未生效的问题
|
||||
|
||||
|
||||
## v0.3
|
||||
### Added
|
||||
- 添加测试脚本，覆盖最常见的功能（已覆盖API）
|
||||
- 新建 tasker 模块，用来管理所有的后台任务，UI 上使用侧边栏管理。Tasker 中获取历史任务的时候，仅获取 top100 个 task。
|
||||
- 优化对文档信息的检索展示（检索结果页、详情页）
|
||||
- 优化全局配置的管理模型，优化配置管理
|
||||
- 支持 MinerU 2.5 的解析方法 <Badge type="info" text="0.3.5" />
|
||||
- 修改现有的智能体Demo，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中
|
||||
- 基于 create_agent 创建 SQL Viewer 智能体 <Badge type="info" text="0.3.5" />
|
||||
- 优化 MCP 逻辑，支持 common + special 创建方式 <Badge type="info" text="0.3.5" />
|
||||
- LightRAG 知识库应该可以支持修改 LLM
|
||||
|
||||
### Fixed
|
||||
- 修复本地知识库的 metadata 和 向量数据库中不一致的情况。
|
||||
- v1 版本的 LangGraph 的工具渲染有问题
|
||||
- upload 接口会阻塞主进程
|
||||
- LightRAG 知识库查看不了解析后的文本，偶然出现，未复现
|
||||
- 智能体的加载状态有问题：（1）智能体加载没有动画；（2）切换对话和加载中，使用同一个loading状态。
|
||||
- 前端工具调用渲染出现问题
|
||||
- 当前 ReAct 智能体有消息顺序错乱的 bug，且不会默认调用工具
|
||||
- 修复文件管理：（1）文件选择的时候会跨数据库；（2）文件校验会算上失败的文件；
|
||||
@ -26,11 +26,11 @@ Yuxi-Know（语析）是一个基于知识图谱和向量数据库的智能知
|
||||
## 演示视频
|
||||
|
||||
<div align="center">
|
||||
<a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank">
|
||||
<a href="https://www.bilibili.com/video/BV1DF14BTETq" target="_blank">
|
||||
<img width="3651" height="1933" alt="视频演示缩略图" src="https://github.com/user-attachments/assets/eac4fa89-2176-46ae-a649-45a125cb6ed1" />
|
||||
</a>
|
||||
<p style="margin-top: 12px;">
|
||||
<a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank" style="text-decoration: none; color: #23ade5; font-weight: 500;">
|
||||
<a href="https://www.bilibili.com/video/BV1DF14BTETq" target="_blank" style="text-decoration: none; color: #23ade5; font-weight: 500;">
|
||||
📽️ 点击查看视频演示 <i class="fa fa-external-link" style="margin-left: 4px;"></i>
|
||||
</a>
|
||||
</p>
|
||||
|
||||
@ -26,11 +26,11 @@ Yuxi-Know（语析）是一个基于知识图谱和向量数据库的智能知
|
||||
## 演示视频
|
||||
|
||||
<div align="center">
|
||||
<a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank">
|
||||
<a href="https://www.bilibili.com/video/BV1DF14BTETq" target="_blank">
|
||||
<img width="3651" height="1933" alt="视频演示缩略图" src="https://github.com/user-attachments/assets/eac4fa89-2176-46ae-a649-45a125cb6ed1" />
|
||||
</a>
|
||||
<p style="margin-top: 12px;">
|
||||
<a href="https://www.bilibili.com/video/BV1ETedzREgY/?share_source=copy_web&vd_source=37b0bdbf95b72ea38b2dc959cfadc4d8" target="_blank" style="text-decoration: none; color: #23ade5; font-weight: 500;">
|
||||
<a href="https://www.bilibili.com/video/BV1DF14BTETq" target="_blank" style="text-decoration: none; color: #23ade5; font-weight: 500;">
|
||||
📽️ 点击查看视频演示 <i class="fa fa-external-link" style="margin-left: 4px;"></i>
|
||||
</a>
|
||||
</p>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user