c4a77f8aa4
项目初始化 - 创建完整项目结构（src/, data/, docs/, examples/, tests/） - 配置requirements.txt依赖 - 创建.gitignore P0基础框架 - 数据库模型：Record模型，6种分类类型 - 配置管理：YAML配置，支持AI/OCR/云存储/UI配置 - OCR模块：PaddleOCR本地识别，支持云端扩展 - AI模块：支持OpenAI/Claude/通义/Ollama，6种分类 - 存储模块：完整CRUD，搜索，统计，导入导出 - 主窗口框架：侧边栏导航，米白配色方案 - 图片处理：截图/剪贴板/文件选择/图片预览 - 处理流程整合：OCR→AI→存储串联，Markdown展示，剪贴板复制 - 分类浏览：卡片网格展示，分类筛选，搜索，详情查看 技术栈 - PyQt6 + SQLAlchemy + PaddleOCR + OpenAI/Claude SDK - 共47个Python文件，4000+行代码 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
250 lines
5.0 KiB
Markdown
250 lines
5.0 KiB
Markdown
# AI 模块文档
|
||
|
||
## 概述
|
||
|
||
AI 模块 (`src/core/ai.py`) 提供了文本分类功能，使用 AI 服务自动将文本分类为 6 种类型之一，并生成结构化的 Markdown 内容。
|
||
|
||
## 支持的分类类型
|
||
|
||
| 类型 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| TODO | 待办事项 | "今天要完成的任务：写代码、测试" |
|
||
| NOTE | 笔记 | "Python 装饰器是一种语法糖..." |
|
||
| IDEA | 灵感 | "突然想到一个产品创意..." |
|
||
| REF | 参考资料 | "API 接口：GET /api/users" |
|
||
| FUNNY | 搞笑文案 | "程序员最讨厌的事：写注释" |
|
||
| TEXT | 纯文本 | 其他无法明确分类的内容 |
|
||
|
||
## 快速开始
|
||
|
||
### 1. 使用配置文件
|
||
|
||
```python
|
||
from src.config.settings import get_settings
|
||
from src.core.ai import classify_text
|
||
|
||
settings = get_settings()
|
||
result = classify_text("待分析的文本", settings.ai)
|
||
|
||
print(result.category) # TODO
|
||
print(result.content) # Markdown 格式内容
|
||
```
|
||
|
||
### 2. 直接创建客户端
|
||
|
||
```python
|
||
from src.core.ai import AIClassifier
|
||
|
||
# OpenAI
|
||
client = AIClassifier.create_client(
|
||
provider="openai",
|
||
api_key="your-api-key",
|
||
model="gpt-4o-mini"
|
||
)
|
||
|
||
result = client.classify("今天要完成的任务...")
|
||
```
|
||
|
||
## 支持的 AI 提供商
|
||
|
||
### OpenAI
|
||
|
||
```python
|
||
client = AIClassifier.create_client(
|
||
provider="openai",
|
||
api_key="sk-...",
|
||
model="gpt-4o-mini" # 或 gpt-4o
|
||
)
|
||
```
|
||
|
||
**依赖**: `pip install openai`
|
||
|
||
### Anthropic (Claude)
|
||
|
||
```python
|
||
client = AIClassifier.create_client(
|
||
provider="anthropic",
|
||
api_key="sk-ant-...",
|
||
model="claude-3-5-sonnet-20241022"
|
||
)
|
||
```
|
||
|
||
**依赖**: `pip install anthropic`
|
||
|
||
### 通义千问
|
||
|
||
```python
|
||
client = AIClassifier.create_client(
|
||
provider="qwen",
|
||
api_key="sk-...",
|
||
model="qwen-turbo"
|
||
)
|
||
```
|
||
|
||
**依赖**: `pip install openai`
|
||
|
||
### Ollama (本地)
|
||
|
||
```python
|
||
client = AIClassifier.create_client(
|
||
provider="ollama",
|
||
api_key="",
|
||
model="llama3.2"
|
||
)
|
||
```
|
||
|
||
**依赖**: 安装 Ollama (https://ollama.ai/)
|
||
|
||
## 分类结果
|
||
|
||
```python
|
||
result: ClassificationResult {
|
||
category: CategoryType.TODO,
|
||
confidence: 0.95,
|
||
title: "今天的工作任务",
|
||
content: "## 今天的工作任务\n- [ ] 写代码\n- [ ] 测试",
|
||
tags: ["任务", "工作"],
|
||
reasoning: "包含待办事项关键词"
|
||
}
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
```python
|
||
from src.core.ai import (
|
||
AIError,
|
||
AIAPIError,
|
||
AIRateLimitError,
|
||
AIAuthenticationError,
|
||
AITimeoutError
|
||
)
|
||
|
||
try:
|
||
result = client.classify(text)
|
||
except AIAuthenticationError:
|
||
print("API key 错误")
|
||
except AIRateLimitError:
|
||
print("请求过于频繁，请稍后重试")
|
||
except AITimeoutError:
|
||
print("请求超时")
|
||
except AIError as e:
|
||
print(f"AI 调用失败: {e}")
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
在 `~/.cutthenthink/config.yaml` 中配置：
|
||
|
||
```yaml
|
||
ai:
|
||
provider: openai # 或 anthropic, qwen, ollama
|
||
api_key: your-api-key
|
||
model: gpt-4o-mini
|
||
temperature: 0.7
|
||
max_tokens: 4096
|
||
timeout: 60
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
python3 tests/test_ai.py
|
||
```
|
||
|
||
## 示例
|
||
|
||
```bash
|
||
python3 examples/ai_example.py
|
||
```
|
||
|
||
## 与其他模块集成
|
||
|
||
### 与数据库模型集成
|
||
|
||
```python
|
||
from src.models.database import Record
|
||
from src.core.ai import classify_text
|
||
|
||
# AI 分类
|
||
result = classify_text(ocr_text, settings.ai)
|
||
|
||
# 保存到数据库
|
||
record = Record(
|
||
image_path="/path/to/image.png",
|
||
ocr_text=ocr_text,
|
||
category=result.category.value,
|
||
ai_result=result.content,
|
||
tags=result.tags
|
||
)
|
||
session.add(record)
|
||
session.commit()
|
||
```
|
||
|
||
### 与 OCR 模块集成
|
||
|
||
```python
|
||
from src.core.ocr import recognize_text
|
||
from src.core.ai import classify_text
|
||
|
||
# OCR 识别
|
||
ocr_result = recognize_text(image_path)
|
||
|
||
# AI 分类
|
||
ai_result = classify_text(ocr_result.text, settings.ai)
|
||
|
||
# 完整处理流程
|
||
print(f"识别文本: {ocr_result.text}")
|
||
print(f"分类: {ai_result.category}")
|
||
print(f"生成内容: {ai_result.content}")
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### AIClassifier
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `create_client()` | 创建 AI 客户端 |
|
||
| `classify()` | 对文本进行分类 |
|
||
|
||
### ClassificationResult
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| category | CategoryType | 分类类型 |
|
||
| confidence | float | 置信度 (0-1) |
|
||
| title | str | 生成的标题 |
|
||
| content | str | Markdown 内容 |
|
||
| tags | List[str] | 提取的标签 |
|
||
| reasoning | str | 分类理由 |
|
||
|
||
## 技术实现
|
||
|
||
- 使用 OpenAI SDK 作为基础 API 客户端
|
||
- 支持兼容 OpenAI API 的服务（通义千问、Ollama）
|
||
- 指数退避重试机制
|
||
- 智能响应解析（支持多种 JSON 格式）
|
||
- 类型安全（枚举、数据类）
|
||
|
||
## 最佳实践
|
||
|
||
1. **选择合适的模型**：
|
||
- OpenAI: `gpt-4o-mini`（快速、便宜）
|
||
- Claude: `claude-3-5-sonnet-20241022`（准确）
|
||
- 本地: `llama3.2`（隐私、免费）
|
||
|
||
2. **温度参数**：
|
||
- 0.0-0.3: 更确定性的输出
|
||
- 0.7: 平衡（推荐）
|
||
- 1.0-2.0: 更有创造性
|
||
|
||
3. **错误处理**：
|
||
- 始终捕获 AIError 异常
|
||
- 实现重试和降级逻辑
|
||
- 记录错误日志
|
||
|
||
4. **性能优化**：
|
||
- 限制输入文本长度（< 4000 字符）
|
||
- 使用缓存避免重复分类
|
||
- 批量处理时控制并发数
|