# 🤖 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. 克隆项目

```bash
git clone <your-repo-url>
cd AccountingBot
```

### 2. 配置环境变量

创建 `.env` 文件：

```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. 启动服务

```bash
# 构建并启动所有服务
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 兼容的视觉模型：

```bash
# 小模型（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 访问受限，配置代理：

```env
GLOBAL_PROXY=http://127.0.0.1:1080
```

## 📊 数据库表结构

```sql
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 无响应
```bash
# 检查服务状态
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 推理失败
```bash
# 检查模型是否已拉取
docker exec vlm_service ollama list

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

# 查看 GPU 占用
nvidia-smi
```

### 数据库连接失败
```bash
# 检查数据库健康状态
docker compose exec db pg_isready -U accounting

# 重启数据库
docker compose restart db
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

## 📄 开源协议

MIT License

## 🙏 致谢

- [aiogram](https://github.com/aiogram/aiogram) - 现代化的 Telegram Bot 框架
- [Ollama](https://ollama.com/) - 本地大模型部署工具
- [Qwen-VL](https://github.com/QwenLM/Qwen-VL) - 阿里通义千问视觉模型

---

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