feat: 实现CutThenThink P0阶段核心功能
项目初始化 - 创建完整项目结构（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>
This commit is contained in:
congsh
249
docs/ai_module.md
Normal file
249
docs/ai_module.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 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 字符）
|
||||
- 使用缓存避免重复分类
|
||||
- 批量处理时控制并发数
|
||||
Reference in New Issue
Block a user