142 lines
4.9 KiB
Markdown
142 lines
4.9 KiB
Markdown
# 表情包API
|
||
|
||
表情包API模块提供表情包的获取、查询和管理功能，让插件能够智能地选择和使用表情包。
|
||
|
||
## 导入方式
|
||
|
||
```python
|
||
from src.plugin_system.apis import emoji_api
|
||
# 或者
|
||
from src.plugin_system import emoji_api
|
||
```
|
||
|
||
## 二步走识别优化
|
||
|
||
从新版本开始，表情包识别系统采用了**二步走识别 + 智能缓存**的优化方案：
|
||
|
||
### **收到表情包时的识别流程**
|
||
1. **第一步**：VLM视觉分析 - 生成详细描述
|
||
2. **第二步**：LLM情感分析 - 基于详细描述提取核心情感标签
|
||
3. **缓存机制**：将情感标签缓存到数据库，详细描述保存到Images表
|
||
|
||
### **注册表情包时的优化**
|
||
- **智能复用**：优先从Images表获取已有的详细描述
|
||
- **避免重复**：如果表情包之前被收到过，跳过VLM调用
|
||
- **性能提升**：减少不必要的AI调用，降低延时和成本
|
||
|
||
### **缓存策略**
|
||
- **ImageDescriptions表**：缓存最终的情感标签（用于快速显示）
|
||
- **Images表**：保存详细描述（用于注册时复用）
|
||
- **双重检查**：防止并发情况下的重复生成
|
||
|
||
## 主要功能
|
||
|
||
### 1. 表情包获取
|
||
```python
|
||
async def get_by_description(description: str) -> Optional[Tuple[str, str, str]]:
|
||
```
|
||
根据场景描述选择表情包
|
||
|
||
**Args：**
|
||
- `description`：表情包的描述文本，例如"开心"、"难过"、"愤怒"等
|
||
|
||
**Returns：**
|
||
- `Optional[Tuple[str, str, str]]`：一个元组: (表情包的base64编码, 描述, 情感标签)，如果未找到匹配的表情包则返回None
|
||
|
||
#### 示例
|
||
```python
|
||
emoji_result = await emoji_api.get_by_description("大笑")
|
||
if emoji_result:
|
||
emoji_base64, description, matched_scene = emoji_result
|
||
print(f"获取到表情包: {description}, 场景: {matched_scene}")
|
||
# 可以将emoji_base64用于发送表情包
|
||
```
|
||
|
||
### 2. 随机获取表情包
|
||
```python
|
||
async def get_random(count: Optional[int] = 1) -> List[Tuple[str, str, str]]:
|
||
```
|
||
随机获取指定数量的表情包
|
||
|
||
**Args：**
|
||
- `count`：要获取的表情包数量，默认为1
|
||
|
||
**Returns：**
|
||
- `List[Tuple[str, str, str]]`：一个包含多个表情包的列表，每个元素是一个元组: (表情包的base64编码, 描述, 情感标签)，如果未找到或出错则返回空列表
|
||
|
||
### 3. 根据情感获取表情包
|
||
```python
|
||
async def get_by_emotion(emotion: str) -> Optional[Tuple[str, str, str]]:
|
||
```
|
||
根据情感标签获取表情包
|
||
|
||
**Args：**
|
||
- `emotion`：情感标签，例如"开心"、"悲伤"、"愤怒"等
|
||
|
||
**Returns：**
|
||
- `Optional[Tuple[str, str, str]]`：一个元组: (表情包的base64编码, 描述, 情感标签)，如果未找到则返回None
|
||
|
||
### 4. 获取表情包数量
|
||
```python
|
||
def get_count() -> int:
|
||
```
|
||
获取当前可用表情包的数量
|
||
|
||
### 5. 获取表情包系统信息
|
||
```python
|
||
def get_info() -> Dict[str, Any]:
|
||
```
|
||
获取表情包系统的基本信息
|
||
|
||
**Returns：**
|
||
- `Dict[str, Any]`：包含表情包数量、描述等信息的字典，包含以下键：
|
||
- `current_count`：当前表情包数量
|
||
- `max_count`：最大表情包数量
|
||
- `available_emojis`：当前可用的表情包数量
|
||
|
||
### 6. 获取所有可用的情感标签
|
||
```python
|
||
def get_emotions() -> List[str]:
|
||
```
|
||
获取所有可用的情感标签 **（已经去重）**
|
||
|
||
### 7. 获取所有表情包描述
|
||
```python
|
||
def get_descriptions() -> List[str]:
|
||
```
|
||
获取所有表情包的描述列表
|
||
|
||
## 场景描述说明
|
||
|
||
### 常用场景描述
|
||
表情包系统支持多种具体的场景描述，举例如下：
|
||
|
||
- **开心类场景**：开心的大笑、满意的微笑、兴奋的手舞足蹈
|
||
- **无奈类场景**：表示无奈和沮丧、轻微的讽刺、无语的摇头
|
||
- **愤怒类场景**：愤怒和不满、生气的瞪视、暴躁的抓狂
|
||
- **惊讶类场景**：震惊的表情、意外的发现、困惑的思考
|
||
- **可爱类场景**：卖萌的表情、撒娇的动作、害羞的样子
|
||
|
||
### 情感关键词示例
|
||
系统支持的情感关键词举例如下：
|
||
- 大笑、微笑、兴奋、手舞足蹈
|
||
- 无奈、沮丧、讽刺、无语、摇头
|
||
- 愤怒、不满、生气、瞪视、抓狂
|
||
- 震惊、意外、困惑、思考
|
||
- 卖萌、撒娇、害羞、可爱
|
||
|
||
### 匹配机制
|
||
- **精确匹配**：优先匹配完整的场景描述，如"开心的大笑"
|
||
- **关键词匹配**：如果没有精确匹配，则根据关键词进行模糊匹配
|
||
- **语义匹配**：系统会理解场景的语义含义进行智能匹配
|
||
|
||
## 注意事项
|
||
|
||
1. **异步函数**：部分函数是异步的，需要使用 `await`
|
||
2. **返回格式**：表情包以base64编码返回，可直接用于发送
|
||
3. **错误处理**：所有函数都有错误处理，失败时返回None，空列表或默认值
|
||
4. **使用统计**：系统会记录表情包的使用次数
|
||
5. **文件依赖**：表情包依赖于本地文件，确保表情包文件存在
|
||
6. **编码格式**：返回的是base64编码的图片数据，可直接用于网络传输
|
||
7. **场景理解**：系统能理解具体的场景描述，比简单的情感分类更准确
|