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. 使用配置文件

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. 直接创建客户端

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

client = AIClassifier.create_client(
    provider="openai",
    api_key="sk-...",
    model="gpt-4o-mini"  # 或 gpt-4o
)

依赖: pip install openai

Anthropic (Claude)

client = AIClassifier.create_client(
    provider="anthropic",
    api_key="sk-ant-...",
    model="claude-3-5-sonnet-20241022"
)

依赖: pip install anthropic

通义千问

client = AIClassifier.create_client(
    provider="qwen",
    api_key="sk-...",
    model="qwen-turbo"
)

依赖: pip install openai

Ollama (本地)

client = AIClassifier.create_client(
    provider="ollama",
    api_key="",
    model="llama3.2"
)

依赖: 安装 Ollama (https://ollama.ai/)

分类结果

result: ClassificationResult {
    category: CategoryType.TODO,
    confidence: 0.95,
    title: "今天的工作任务",
    content: "## 今天的工作任务\n- [ ] 写代码\n- [ ] 测试",
    tags: ["任务", "工作"],
    reasoning: "包含待办事项关键词"
}

错误处理

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 中配置：

ai:
  provider: openai  # 或 anthropic, qwen, ollama
  api_key: your-api-key
  model: gpt-4o-mini
  temperature: 0.7
  max_tokens: 4096
  timeout: 60

测试

python3 tests/test_ai.py

示例

python3 examples/ai_example.py

与其他模块集成

与数据库模型集成

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 模块集成

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