cutThenThink/docs/ai_module.md

# 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 字符）
   - 使用缓存避免重复分类
   - 批量处理时控制并发数