AccountingBot/README.md

🤖 AI 记账助手 (AccountingBot)

基于 Telegram Bot 的智能记账助手，支持图片识别和自然语言输入，使用本地部署的 Qwen3-VL 视觉大模型进行账单解析。

✨ 功能特点

• 🖼️ 图片识别：拍照上传小票、截图，AI 自动识别金额、类别和时间
• 💬 文本输入：发送"昨天晚上火锅花了238元"等自然语言，智能解析
• 📊 数据管理：查看、编辑、删除历史账单
• 📈 数据导出：一键导出 CSV 报表，包含分类统计和占比分析
• 🔐 多用户支持：每个用户独立的记账数据
• 🚀 本地部署：所有数据和 AI 模型完全本地化，保护隐私

🏗️ 技术架构

┌─────────────────┐
│  Telegram Bot   │  ← 用户交互界面
└────────┬────────┘
         │
┌────────▼────────┐
│   Bot Service   │  ← aiogram 3.x + FSM 状态管理
└────┬───────┬────┘
     │       │
     │       └─────────────┐
     │                     │
┌────▼──────┐      ┌──────▼───────┐
│PostgreSQL │      │ Ollama + GPU │  ← Qwen3-VL 视觉模型
└───────────┘      └──────────────┘

核心组件

• Bot Service: Python + aiogram 3.x
• VLM Service: Ollama + Qwen3-VL (本地 GPU 推理)
• Database: PostgreSQL 15
• 容器编排: Docker Compose + NVIDIA Runtime

📦 快速开始

环境要求

• Docker & Docker Compose
• NVIDIA GPU + nvidia-docker (用于 VLM 推理)
• Telegram Bot Token

1. 克隆项目

git clone <your-repo-url>
cd AccountingBot

2. 配置环境变量

创建 .env 文件：

# Telegram Bot 配置
TG_TOKEN=your_telegram_bot_token
ADMIN_ID=123456789  # 你的个人TG ID，用于接收系统通知或管理

# 数据库配置
POSTGRES_USER=accounting
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=accounting_db
DB_URL=postgresql+asyncpg://accounting:your_secure_password@db:5432/accounting_db

# VLM 模型配置
OLLAMA_BASE_URL=http://vlm-service:11434
VLM_MODEL=qwen3-vl:8b  # 或其他 Qwen 视觉模型
MAX_CONCURRENT_INFERENCE=1  # GPU 并发数限制

# 全局代理（可选）
GLOBAL_PROXY=socks5://proxy_host:port

3. 启动服务

# 构建并启动所有服务
docker compose up -d

# 首次启动需要拉取 VLM 模型（约 2-5GB）
docker exec vlm_service ollama pull qwen2.5-vl:3b

# 查看日志
docker compose logs -f bot

4. 验证部署

在 Telegram 中向你的 Bot 发送 /start，应该会收到欢迎消息。

🎮 使用指南

基础命令

命令	说明
/start	开始使用，查看帮助
/edit	管理历史账单（查看、修改、删除）
/export	导出 CSV 报表（含分类统计）

记账方式

方式一：拍照上传

直接发送小票照片或消费截图，Bot 会自动识别：

• 💰 金额
• 🏷️ 类别（餐饮、交通、购物等）
• 📅 交易时间

方式二：文本输入

发送自然语言描述，例如：

• "今天午饭花了45.5元"
• "昨天打车30块"
• "上周五买书200元"

数据管理

1. 查看账单：/edit → 分页浏览历史记录
2. 编辑记录：点击记录编号 → 修改金额/类别
3. 删除记录：详情页点击 🗑️ 删除按钮
4. 导出数据：/export → 下载 CSV 文件

📂 项目结构

AccountingBot/
├── docker-compose.yml          # 容器编排配置
├── .env                        # 环境变量（需自行创建）
├── bot/
│   ├── Dockerfile              # Bot 服务镜像
│   ├── main.py                 # 主程序（FSM 状态机 + 路由）
│   ├── database.py             # SQLAlchemy 数据模型
│   ├── vlm.py                  # VLM 调用封装
│   └── requirements.txt        # Python 依赖
└── data/
    ├── postgres/               # 数据库持久化目录
    ├── ollama/                 # VLM 模型存储
    └── temp/                   # 临时文件

🔧 核心依赖

Python 包

• aiogram>=3.0.0 - Telegram Bot 框架
• sqlalchemy[asyncio] - 异步 ORM
• asyncpg - PostgreSQL 异步驱动
• httpx - 异步 HTTP 客户端（调用 Ollama）
• pillow - 图片处理

Docker 镜像

• python:3.11-slim - Bot 运行环境
• ollama/ollama:latest - VLM 服务
• postgres:15-alpine - 数据库

🎯 高级配置

模型选择

支持任何 Ollama 兼容的视觉模型：

# 小模型（4B，显存约 3GB）
ollama pull qwen3-vl:4b

# 中等模型（8B，显存约 8GB）
ollama pull qwen3-vl:8b

# 大模型（30B，显存约 20GB）
ollama pull qwen3-vl:30b

修改 .env 中的 VLM_MODEL 变量即可切换。

并发控制

MAX_CONCURRENT_INFERENCE 控制同时处理的推理请求数：

• 单卡环境推荐设为 1
• 多卡环境可适当增加

代理配置

如果 Telegram API 访问受限，配置代理：

GLOBAL_PROXY=http://127.0.0.1:1080

📊 数据库表结构

CREATE TABLE records (
    id SERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL,           -- Telegram User ID
    amount FLOAT NOT NULL,             -- 金额
    category VARCHAR(100),             -- 类别
    transaction_time TIMESTAMP,        -- 交易时间
    INDEX idx_user_id (user_id)
);

🐛 故障排查

Bot 无响应

# 检查服务状态
docker compose ps

# 查看 Bot 日志
docker compose logs bot

# 检查数据库连接
docker exec accounting_bot python -c "from database import init_db; import asyncio; asyncio.run(init_db())"

VLM 推理失败

# 检查模型是否已拉取
docker exec vlm_service ollama list

# 测试模型推理
docker exec vlm_service ollama run qwen2.5-vl:3b "hi"

# 查看 GPU 占用
nvidia-smi

数据库连接失败

# 检查数据库健康状态
docker compose exec db pg_isready -U accounting

# 重启数据库
docker compose restart db

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

📄 开源协议

MIT License

🙏 致谢

• aiogram - 现代化的 Telegram Bot 框架
• Ollama - 本地大模型部署工具
• Qwen-VL - 阿里通义千问视觉模型

---

⭐ 如果这个项目对你有帮助，请给个 Star！