257 lines
6.6 KiB
Markdown
257 lines
6.6 KiB
Markdown
# 🤖 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！ |