Add Phase 3 feature documentation
This commit is contained in:
OpenClaw Bot
198
docs/PHASE3_FEATURES.md
Normal file
198
docs/PHASE3_FEATURES.md
Normal file
@@ -0,0 +1,198 @@
|
|||||||
|
# InsightFlow Phase 3 功能说明
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
Phase 3 实现了 InsightFlow 的"记忆与生长"能力，支持多文件知识融合、文档导入和项目级知识库管理。
|
||||||
|
|
||||||
|
## 功能清单
|
||||||
|
|
||||||
|
### 1. 多文件图谱融合 ✅
|
||||||
|
|
||||||
|
#### 功能描述
|
||||||
|
- 支持向同一项目上传多个音频文件
|
||||||
|
- 系统自动对齐新文件中的实体与已有实体
|
||||||
|
- 合并知识图谱，保持实体一致性
|
||||||
|
- 跨文件追踪实体提及
|
||||||
|
|
||||||
|
#### 使用方式
|
||||||
|
1. 在工作台点击"+ 上传文件"
|
||||||
|
2. 选择音频文件（MP3/WAV/M4A）
|
||||||
|
3. 系统自动转录并提取实体
|
||||||
|
4. 新实体与已有实体自动对齐
|
||||||
|
5. 使用"📁 选择文件"切换不同转录内容
|
||||||
|
|
||||||
|
#### API
|
||||||
|
```
|
||||||
|
POST /api/v1/projects/{project_id}/upload
|
||||||
|
Content-Type: multipart/form-data
|
||||||
|
file: <音频文件>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 实体对齐算法优化 ✅
|
||||||
|
|
||||||
|
#### 功能描述
|
||||||
|
- 使用 Kimi API 的 embedding 服务计算语义相似度
|
||||||
|
- 余弦相似度匹配算法
|
||||||
|
- 支持阈值调整（默认 0.85）
|
||||||
|
- 自动别名建议
|
||||||
|
- 失败时回退到字符串匹配
|
||||||
|
|
||||||
|
#### 实现模块
|
||||||
|
- `backend/entity_aligner.py`
|
||||||
|
|
||||||
|
#### 核心算法
|
||||||
|
```python
|
||||||
|
# 余弦相似度计算
|
||||||
|
def compute_similarity(embedding1, embedding2):
|
||||||
|
vec1 = np.array(embedding1)
|
||||||
|
vec2 = np.array(embedding2)
|
||||||
|
dot_product = np.dot(vec1, vec2)
|
||||||
|
norm1 = np.linalg.norm(vec1)
|
||||||
|
norm2 = np.linalg.norm(vec2)
|
||||||
|
return dot_product / (norm1 * norm2)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### API
|
||||||
|
```
|
||||||
|
POST /api/v1/projects/{project_id}/align-entities?threshold=0.85
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. PDF/DOCX 文档导入 ✅
|
||||||
|
|
||||||
|
#### 功能描述
|
||||||
|
- 支持 PDF、DOCX、DOC、TXT、MD 格式
|
||||||
|
- 自动提取文档文本
|
||||||
|
- 文本参与实体提取和关系构建
|
||||||
|
- 文档类型标记和区分
|
||||||
|
|
||||||
|
#### 使用方式
|
||||||
|
1. 在工作台点击"+ 上传文件"
|
||||||
|
2. 切换到"📄 文档"标签
|
||||||
|
3. 选择文档文件
|
||||||
|
4. 系统自动解析并提取知识
|
||||||
|
|
||||||
|
#### 实现模块
|
||||||
|
- `backend/document_processor.py`
|
||||||
|
|
||||||
|
#### API
|
||||||
|
```
|
||||||
|
POST /api/v1/projects/{project_id}/upload-document
|
||||||
|
Content-Type: multipart/form-data
|
||||||
|
file: <文档文件>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 项目知识库面板 ✅
|
||||||
|
|
||||||
|
#### 功能描述
|
||||||
|
- 项目级全域知识库视图
|
||||||
|
- 统计面板（实体数、关系数、文件数、术语数）
|
||||||
|
- 实体网格展示（带提及统计）
|
||||||
|
- 关系列表展示
|
||||||
|
- 术语表管理
|
||||||
|
- 文件列表（区分音频/文档）
|
||||||
|
|
||||||
|
#### 使用方式
|
||||||
|
1. 在工作台点击左侧"📚"图标
|
||||||
|
2. 查看项目统计概览
|
||||||
|
3. 切换侧边栏标签浏览不同内容
|
||||||
|
4. 点击实体可跳转回工作台查看详情
|
||||||
|
|
||||||
|
#### API
|
||||||
|
```
|
||||||
|
GET /api/v1/projects/{project_id}/knowledge-base
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. 术语表管理 ✅
|
||||||
|
|
||||||
|
#### 功能描述
|
||||||
|
- 项目级术语表
|
||||||
|
- 支持添加术语和发音提示
|
||||||
|
- 频率统计
|
||||||
|
- 用于 ASR 热词优化
|
||||||
|
|
||||||
|
#### 使用方式
|
||||||
|
1. 在知识库面板切换到"📖 术语表"
|
||||||
|
2. 点击"+ 添加术语"
|
||||||
|
3. 输入术语和发音提示
|
||||||
|
4. 可删除不需要的术语
|
||||||
|
|
||||||
|
#### API
|
||||||
|
```
|
||||||
|
POST /api/v1/projects/{project_id}/glossary
|
||||||
|
GET /api/v1/projects/{project_id}/glossary
|
||||||
|
DELETE /api/v1/glossary/{term_id}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 数据库 Schema 更新
|
||||||
|
|
||||||
|
### transcripts 表
|
||||||
|
```sql
|
||||||
|
ALTER TABLE transcripts ADD COLUMN type TEXT DEFAULT 'audio';
|
||||||
|
-- 'audio' 或 'document'
|
||||||
|
```
|
||||||
|
|
||||||
|
### entities 表
|
||||||
|
```sql
|
||||||
|
ALTER TABLE entities ADD COLUMN embedding TEXT;
|
||||||
|
-- JSON 数组存储 embedding 向量
|
||||||
|
```
|
||||||
|
|
||||||
|
### glossary 表（新增）
|
||||||
|
```sql
|
||||||
|
CREATE TABLE glossary (
|
||||||
|
id TEXT PRIMARY KEY,
|
||||||
|
project_id TEXT NOT NULL,
|
||||||
|
term TEXT NOT NULL,
|
||||||
|
pronunciation TEXT,
|
||||||
|
frequency INTEGER DEFAULT 1
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
## 前端更新
|
||||||
|
|
||||||
|
### 新增组件
|
||||||
|
1. **侧边栏导航** - 切换工作台/知识库视图
|
||||||
|
2. **文件选择器** - 切换不同转录文件
|
||||||
|
3. **上传标签页** - 区分音频/文档上传
|
||||||
|
4. **知识库面板** - 统计卡片、实体网格、关系列表、术语表
|
||||||
|
|
||||||
|
### 更新文件
|
||||||
|
- `frontend/workbench.html` - 新增知识库 UI
|
||||||
|
- `frontend/app.js` - 新增知识库逻辑、多文件支持
|
||||||
|
|
||||||
|
## 部署说明
|
||||||
|
|
||||||
|
### 环境变量
|
||||||
|
```bash
|
||||||
|
KIMI_API_KEY=your_kimi_api_key
|
||||||
|
KIMI_BASE_URL=https://api.kimi.com/coding
|
||||||
|
ALIYUN_ACCESS_KEY_ID=your_aliyun_key
|
||||||
|
ALIYUN_ACCESS_KEY_SECRET=your_aliyun_secret
|
||||||
|
```
|
||||||
|
|
||||||
|
### 部署命令
|
||||||
|
```bash
|
||||||
|
# 使用部署脚本
|
||||||
|
./deploy.sh
|
||||||
|
|
||||||
|
# 或手动部署
|
||||||
|
docker build -t insightflow:phase3 .
|
||||||
|
docker run -d \
|
||||||
|
-p 18000:8000 \
|
||||||
|
-v /opt/data:/app/data \
|
||||||
|
-e KIMI_API_KEY=$KIMI_API_KEY \
|
||||||
|
insightflow:phase3
|
||||||
|
```
|
||||||
|
|
||||||
|
## 测试检查清单
|
||||||
|
|
||||||
|
- [ ] 上传多个音频文件到同一项目
|
||||||
|
- [ ] 检查实体是否正确对齐
|
||||||
|
- [ ] 上传 PDF 文档
|
||||||
|
- [ ] 上传 DOCX 文档
|
||||||
|
- [ ] 切换不同转录文件
|
||||||
|
- [ ] 查看知识库面板统计
|
||||||
|
- [ ] 添加术语到术语表
|
||||||
|
- [ ] 删除术语
|
||||||
|
- [ ] 实体合并功能
|
||||||
|
- [ ] 关系创建/删除
|
||||||
Reference in New Issue
Block a user