docs: remove outdated and unused documentation files
A significant number of documentation files, including design documents, user guides, and old images, have been removed to clean up the repository and eliminate outdated information. This reduces clutter and ensures that the documentation accurately reflects the current state of the project. Key removals include: - `memory_system_design_v3.md` - `model_configuration_guide.md` - `PERMISSION_SYSTEM.md` - `CONTRIBUTE.md` - `vector_db_usage_guide.md
This commit is contained in:
minecraft1024a
331
docs/guides/model_configuration_guide.md
Normal file
331
docs/guides/model_configuration_guide.md
Normal file
@@ -0,0 +1,331 @@
|
||||
# 模型配置指南
|
||||
|
||||
本文档将指导您如何配置 `model_config.toml` 文件，该文件用于配置 MoFox_Bot 的各种AI模型和API服务提供商。
|
||||
|
||||
## 配置文件结构
|
||||
|
||||
配置文件主要包含以下几个部分：
|
||||
- 版本信息
|
||||
- API服务提供商配置
|
||||
- 模型配置
|
||||
- 模型任务配置
|
||||
|
||||
## 1. 版本信息
|
||||
|
||||
```toml
|
||||
[inner]
|
||||
version = "1.1.1"
|
||||
```
|
||||
|
||||
用于标识配置文件的版本，遵循语义化版本规则。
|
||||
|
||||
## 2. API服务提供商配置
|
||||
|
||||
### 2.1 基本配置
|
||||
|
||||
使用 `[[api_providers]]` 数组配置多个API服务提供商：
|
||||
|
||||
```toml
|
||||
[[api_providers]]
|
||||
name = "DeepSeek" # 服务商名称（自定义）
|
||||
base_url = "https://api.deepseek.cn/v1" # API服务的基础URL
|
||||
api_key = "your-api-key-here" # API密钥
|
||||
client_type = "openai" # 客户端类型
|
||||
max_retry = 2 # 最大重试次数
|
||||
timeout = 30 # 超时时间（秒）
|
||||
retry_interval = 10 # 重试间隔（秒）
|
||||
```
|
||||
|
||||
### 2.2 配置参数说明
|
||||
|
||||
| 参数 | 必填 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| `name` | ✅ | 服务商名称，需要在模型配置中引用 | - |
|
||||
| `base_url` | ✅ | API服务的基础URL | - |
|
||||
| `api_key` | ✅ | API密钥，请替换为实际密钥 | - |
|
||||
| `client_type` | ❌ | 客户端类型：`openai`（OpenAI格式）或 `aiohttp_gemini`(至少现在支持良好) | `openai` |
|
||||
| `max_retry` | ❌ | API调用失败时的最大重试次数 | 2 |
|
||||
| `timeout` | ❌ | API请求超时时间（秒） | 30 |
|
||||
| `retry_interval` | ❌ | 重试间隔时间（秒） | 10 |
|
||||
|
||||
### 2.3 支持的服务商示例
|
||||
|
||||
#### DeepSeek
|
||||
```toml
|
||||
[[api_providers]]
|
||||
name = "DeepSeek"
|
||||
base_url = "https://api.deepseek.cn/v1"
|
||||
api_key = "your-deepseek-api-key"
|
||||
client_type = "openai"
|
||||
```
|
||||
|
||||
#### SiliconFlow
|
||||
```toml
|
||||
[[api_providers]]
|
||||
name = "SiliconFlow"
|
||||
base_url = "https://api.siliconflow.cn/v1"
|
||||
api_key = "your-siliconflow-api-key"
|
||||
client_type = "openai"
|
||||
```
|
||||
|
||||
#### Google Gemini
|
||||
```toml
|
||||
[[api_providers]]
|
||||
name = "Google"
|
||||
base_url = "https://api.google.com/v1" #在MoFox-Bot中, 使用aiohttp_gemini客户端的提供商可以自定义base_url
|
||||
api_key = "your-google-api-key"
|
||||
client_type = "aiohttp_gemini" # 注意：Gemini需要使用特殊客户端
|
||||
```
|
||||
|
||||
## 3. 模型配置
|
||||
|
||||
### 3.1 基本模型配置
|
||||
|
||||
使用 `[[models]]` 数组配置多个模型：
|
||||
|
||||
```toml
|
||||
[[models]]
|
||||
model_identifier = "deepseek-chat" # 模型在API服务商中的标识符
|
||||
name = "deepseek-v3" # 自定义模型名称
|
||||
api_provider = "DeepSeek" # 引用的API服务商名称
|
||||
price_in = 2.0 # 输入价格（元/M token）
|
||||
price_out = 8.0 # 输出价格（元/M token）
|
||||
```
|
||||
|
||||
### 3.2 高级模型配置
|
||||
|
||||
#### 强制流式输出
|
||||
对于不支持非流式输出的模型：
|
||||
```toml
|
||||
[[models]]
|
||||
model_identifier = "some-model"
|
||||
name = "custom-name"
|
||||
api_provider = "Provider"
|
||||
force_stream_mode = true # 启用强制流式输出
|
||||
```
|
||||
|
||||
#### 额外参数配置`extra_params`
|
||||
```toml
|
||||
[[models]]
|
||||
model_identifier = "Qwen/Qwen3-8B"
|
||||
name = "qwen3-8b"
|
||||
api_provider = "SiliconFlow"
|
||||
[models.extra_params]
|
||||
enable_thinking = false # 禁用思考
|
||||
```
|
||||
这里的 `extra_params` 可以包含任何API服务商支持的额外参数配置，**配置时应参考相应的API文档**。
|
||||
|
||||
比如上面就是参考SiliconFlow的文档配置配置的`Qwen3`禁用思考参数。
|
||||
|
||||
|
||||
|
||||
以豆包文档为另一个例子
|
||||
|
||||
|
||||
|
||||
得到豆包`"doubao-seed-1-6-250615"`的禁用思考配置方法为
|
||||
```toml
|
||||
[[models]]
|
||||
# 你的模型
|
||||
[models.extra_params]
|
||||
thinking = {type = "disabled"} # 禁用思考
|
||||
```
|
||||
请注意，`extra_params` 的配置应该构成一个合法的TOML字典结构，具体内容取决于API服务商的要求。
|
||||
|
||||
**请注意，对于`client_type`为`gemini`的模型，此字段无效。**
|
||||
### 3.3 配置参数说明
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `model_identifier` | ✅ | API服务商提供的模型标识符 |
|
||||
| `name` | ✅ | 自定义模型名称，用于在任务配置中引用 |
|
||||
| `api_provider` | ✅ | 对应的API服务商名称 |
|
||||
| `price_in` | ❌ | 输入价格（元/M token），用于成本统计 |
|
||||
| `price_out` | ❌ | 输出价格（元/M token），用于成本统计 |
|
||||
| `force_stream_mode` | ❌ | 是否强制使用流式输出 |
|
||||
| `extra_params` | ❌ | 额外的模型参数配置 |
|
||||
|
||||
## 4. 模型任务配置
|
||||
|
||||
### utils - 工具模型
|
||||
用于表情包模块、取名模块、关系模块等核心功能：
|
||||
```toml
|
||||
[model_task_config.utils]
|
||||
model_list = ["siliconflow-deepseek-v3"]
|
||||
temperature = 0.2
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### utils_small - 小型工具模型
|
||||
用于高频率调用的场景，建议使用速度快的小模型：
|
||||
```toml
|
||||
[model_task_config.utils_small]
|
||||
model_list = ["qwen3-8b"]
|
||||
temperature = 0.7
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### replyer_1 - 主要回复模型
|
||||
首要回复模型，也用于表达器和表达方式学习：
|
||||
```toml
|
||||
[model_task_config.replyer_1]
|
||||
model_list = ["siliconflow-deepseek-v3"]
|
||||
temperature = 0.2
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### replyer_2 - 次要回复模型
|
||||
```toml
|
||||
[model_task_config.replyer_2]
|
||||
model_list = ["siliconflow-deepseek-v3"]
|
||||
temperature = 0.7
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### planner - 决策模型
|
||||
负责决定MaiBot该做什么：
|
||||
```toml
|
||||
[model_task_config.planner]
|
||||
model_list = ["siliconflow-deepseek-v3"]
|
||||
temperature = 0.3
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### emotion - 情绪模型
|
||||
负责MaiBot的情绪变化：
|
||||
```toml
|
||||
[model_task_config.emotion]
|
||||
model_list = ["siliconflow-deepseek-v3"]
|
||||
temperature = 0.3
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### memory - 记忆模型
|
||||
```toml
|
||||
[model_task_config.memory]
|
||||
model_list = ["qwen3-30b"]
|
||||
temperature = 0.7
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### vlm - 视觉语言模型
|
||||
用于图像识别：
|
||||
```toml
|
||||
[model_task_config.vlm]
|
||||
model_list = ["qwen2.5-vl-72b"]
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### voice - 语音识别模型
|
||||
```toml
|
||||
[model_task_config.voice]
|
||||
model_list = ["sensevoice-small"]
|
||||
```
|
||||
|
||||
### embedding - 嵌入模型
|
||||
```toml
|
||||
[model_task_config.embedding]
|
||||
model_list = ["bge-m3"]
|
||||
```
|
||||
|
||||
### tool_use - 工具调用模型
|
||||
需要使用支持工具调用的模型：
|
||||
```toml
|
||||
[model_task_config.tool_use]
|
||||
model_list = ["qwen3-14b"]
|
||||
temperature = 0.7
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### lpmm_entity_extract - 实体提取模型
|
||||
```toml
|
||||
[model_task_config.lpmm_entity_extract]
|
||||
model_list = ["siliconflow-deepseek-v3"]
|
||||
temperature = 0.2
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### lpmm_rdf_build - RDF构建模型
|
||||
```toml
|
||||
[model_task_config.lpmm_rdf_build]
|
||||
model_list = ["siliconflow-deepseek-v3"]
|
||||
temperature = 0.2
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
### lpmm_qa - 问答模型
|
||||
```toml
|
||||
[model_task_config.lpmm_qa]
|
||||
model_list = ["deepseek-r1-distill-qwen-32b"]
|
||||
temperature = 0.7
|
||||
max_tokens = 800
|
||||
```
|
||||
|
||||
## 5. 配置建议
|
||||
|
||||
### 5.1 Temperature 参数选择
|
||||
|
||||
| 任务类型 | 推荐温度 | 说明 |
|
||||
|----------|----------|------|
|
||||
| 精确任务（工具调用、实体提取） | 0.1-0.3 | 需要准确性和一致性 |
|
||||
| 创意任务（对话、记忆） | 0.5-0.8 | 需要多样性和创造性 |
|
||||
| 平衡任务（决策、情绪） | 0.3-0.5 | 平衡准确性和灵活性 |
|
||||
|
||||
### 5.2 模型选择建议
|
||||
|
||||
| 任务类型 | 推荐模型类型 | 示例 |
|
||||
|----------|--------------|------|
|
||||
| 高精度任务 | 大模型 | DeepSeek-V3, GPT-5,Gemini-2.5-Pro |
|
||||
| 高频率任务 | 小模型 | Qwen3-8B |
|
||||
| 多模态任务 | 专用模型 | Qwen2.5-VL, SenseVoice |
|
||||
| 工具调用 | 支持Function Call的模型 | Qwen3-14B |
|
||||
|
||||
### 5.3 成本优化
|
||||
|
||||
1. **分层使用**：核心功能使用高质量模型，辅助功能使用经济模型
|
||||
2. **合理配置max_tokens**：根据实际需求设置，避免浪费
|
||||
|
||||
## 6. 配置验证
|
||||
|
||||
### 6.1 必要检查项
|
||||
|
||||
1. ✅ API密钥是否正确配置
|
||||
2. ✅ 模型标识符是否与API服务商提供的一致
|
||||
3. ✅ 任务配置中引用的模型名称是否在models中定义
|
||||
4. ✅ 多模态任务是否配置了对应的专用模型
|
||||
|
||||
### 6.2 测试配置
|
||||
|
||||
建议在正式使用前：
|
||||
1. 使用少量测试数据验证配置
|
||||
2. 检查API调用是否正常
|
||||
3. 确认成本统计功能正常工作
|
||||
|
||||
## 7. 故障排除
|
||||
|
||||
### 7.1 常见问题
|
||||
|
||||
**问题1**: API调用失败
|
||||
- 检查API密钥是否正确
|
||||
- 确认base_url是否可访问
|
||||
- 检查模型标识符是否正确
|
||||
|
||||
**问题2**: 模型未找到
|
||||
- 确认模型名称在任务配置和模型定义中一致
|
||||
- 检查api_provider名称是否匹配
|
||||
|
||||
**问题3**: 响应异常
|
||||
- 检查温度参数是否合理（0-1之间）
|
||||
- 确认max_tokens设置是否合适
|
||||
- 验证模型是否支持所需功能
|
||||
|
||||
### 7.2 日志查看
|
||||
|
||||
查看 `logs/` 目录下的日志文件，寻找相关错误信息。
|
||||
|
||||
## 8. 更新和维护
|
||||
|
||||
1. **定期更新**: 关注API服务商的模型更新，及时调整配置
|
||||
2. **性能监控**: 监控模型调用的成本和性能
|
||||
3. **备份配置**: 在修改前备份当前配置文件
|
||||
|
||||
128
docs/guides/vector_db_usage_guide.md
Normal file
128
docs/guides/vector_db_usage_guide.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 统一向量数据库服务使用指南
|
||||
|
||||
本文档旨在说明如何在 `mmc` 项目中使用新集成的统一向量数据库服务。该服务提供了一个标准化的接口，用于与底层向量数据库（当前为 ChromaDB）进行交互，同时确保了代码的解耦和未来的可扩展性。
|
||||
|
||||
## 核心设计理念
|
||||
|
||||
1. **统一入口**: 所有对向量数据库的操作都应通过全局单例 `vector_db_service` 进行。
|
||||
2. **抽象接口**: 服务遵循 `VectorDBBase` 抽象基类定义的接口，未来可以轻松替换为其他向量数据库（如 Milvus, FAISS）而无需修改业务代码。
|
||||
3. **单例模式**: 整个应用程序共享一个数据库客户端实例，避免了资源浪费和管理混乱。
|
||||
4. **数据隔离**: 使用不同的 `collection` 名称来隔离不同业务模块（如语义缓存、瞬时记忆）的数据。在 `collection` 内部，使用 `metadata` 字段（如 `chat_id`）来隔离不同用户或会话的数据。
|
||||
|
||||
## 如何使用
|
||||
|
||||
### 1. 导入服务
|
||||
|
||||
在任何需要使用向量数据库的文件中，只需导入全局服务实例：
|
||||
|
||||
```python
|
||||
from src.common.vector_db import vector_db_service
|
||||
```
|
||||
|
||||
### 2. 主要操作
|
||||
|
||||
`vector_db_service` 对象提供了所有你需要的方法，这些方法都定义在 `VectorDBBase` 中。
|
||||
|
||||
#### a. 获取或创建集合 (Collection)
|
||||
|
||||
在操作数据之前，你需要先指定一个集合。如果集合不存在，它将被自动创建。
|
||||
|
||||
```python
|
||||
# 为语义缓存创建一个集合
|
||||
vector_db_service.get_or_create_collection(name="semantic_cache")
|
||||
|
||||
# 为瞬时记忆创建一个集合
|
||||
vector_db_service.get_or_create_collection(
|
||||
name="instant_memory",
|
||||
metadata={"hnsw:space": "cosine"} # 可以传入特定于实现的参数
|
||||
)
|
||||
```
|
||||
|
||||
#### b. 添加数据
|
||||
|
||||
使用 `add` 方法向指定集合中添加向量、文档和元数据。
|
||||
|
||||
```python
|
||||
collection_name = "instant_memory"
|
||||
chat_id = "user_123"
|
||||
message_id = "msg_abc"
|
||||
embedding_vector = [0.1, 0.2, 0.3, ...] # 你的 embedding 向量
|
||||
content = "你好，这是一个测试消息"
|
||||
|
||||
vector_db_service.add(
|
||||
collection_name=collection_name,
|
||||
embeddings=[embedding_vector],
|
||||
documents=[content],
|
||||
metadatas=[{
|
||||
"chat_id": chat_id,
|
||||
"timestamp": 1678886400.0,
|
||||
"sender": "user"
|
||||
}],
|
||||
ids=[message_id]
|
||||
)
|
||||
```
|
||||
|
||||
#### c. 查询数据
|
||||
|
||||
使用 `query` 方法来查找相似的向量。你可以使用 `where` 子句来过滤元数据。
|
||||
|
||||
```python
|
||||
query_vector = [0.11, 0.22, 0.33, ...] # 用于查询的向量
|
||||
collection_name = "instant_memory"
|
||||
chat_id_to_query = "user_123"
|
||||
|
||||
results = vector_db_service.query(
|
||||
collection_name=collection_name,
|
||||
query_embeddings=[query_vector],
|
||||
n_results=5, # 返回最相似的5个结果
|
||||
where={"chat_id": chat_id_to_query} # **重要**: 使用 where 来隔离不同聊天的数据
|
||||
)
|
||||
|
||||
# results 的结构:
|
||||
# {
|
||||
# 'ids': [['msg_abc']],
|
||||
# 'distances': [[0.0123]],
|
||||
# 'metadatas': [[{'chat_id': 'user_123', ...}]],
|
||||
# 'embeddings': None,
|
||||
# 'documents': [['你好，这是一个测试消息']]
|
||||
# }
|
||||
print(results)
|
||||
```
|
||||
|
||||
#### d. 删除数据
|
||||
|
||||
你可以根据 `id` 或 `where` 条件来删除数据。
|
||||
|
||||
```python
|
||||
# 根据 ID 删除
|
||||
vector_db_service.delete(
|
||||
collection_name="instant_memory",
|
||||
ids=["msg_abc"]
|
||||
)
|
||||
|
||||
# 根据 where 条件删除 (例如，删除某个用户的所有记忆)
|
||||
vector_db_service.delete(
|
||||
collection_name="instant_memory",
|
||||
where={"chat_id": "user_123"}
|
||||
)
|
||||
```
|
||||
|
||||
#### e. 获取集合数量
|
||||
|
||||
使用 `count` 方法获取一个集合中的条目总数。
|
||||
|
||||
```python
|
||||
count = vector_db_service.count(collection_name="semantic_cache")
|
||||
print(f"语义缓存集合中有 {count} 条数据。")
|
||||
```
|
||||
**注意**: `count` 方法目前返回整个集合的条目数，不会根据 `where` 条件进行过滤。
|
||||
|
||||
### 3. 代码位置
|
||||
|
||||
- **抽象基类**: [`mmc/src/common/vector_db/base.py`](mmc/src/common/vector_db/base.py)
|
||||
- **ChromaDB 实现**: [`mmc/src/common/vector_db/chromadb_impl.py`](mmc/src/common/vector_db/chromadb_impl.py)
|
||||
- **服务入口**: [`mmc/src/common/vector_db/__init__.py`](mmc/src/common/vector_db/__init__.py)
|
||||
|
||||
---
|
||||
|
||||
这份完整的文档应该能帮助您和团队的其他成员正确地使用新的向量数据库服务。如果您有任何其他问题，请随时提出。
|
||||
Reference in New Issue
Block a user