Geliebte
a3bbf33358
- Gin + config.yaml + SQLite 后端骨架，JWT 登录 + 管理员初始化
- web/ 原生单页：拖拽多图上传 → Agnes 免费识别 → 结果复制
- HTTP API：/api/v1/vision/analyze 免鉴权 + 令牌桶限流，支持程序直调
- cmd/vision-cli 独立 CLI 工具（复用 service 层，不依赖 Web 服务）
- build.bat / build.sh 构建脚本，移除 mcp-server
- 统一响应格式 {code, message, data}，CORS/JWT/限流中间件
Co-Authored-By: Claude <noreply@anthropic.com>
152 lines
5.2 KiB
Markdown
152 lines
5.2 KiB
Markdown
# vision-tool — 免费图片识别 👁️
|
||
|
||
基于 Go 的图片视觉分析工具，对接 **Agnes-2.0-Flash** 免费视觉模型（Sapiens AI）。提供 **Web 在线识别页面** 和 **CLI 工具** 两种形态，适用于 **UI 设计稿分析、布局结构解读、页面内容/文字提取** 等场景。
|
||
|
||
**核心思路：推理模型专心推理，图片理解交给免费小模型。成本为零。**
|
||
|
||
## ✨ 特性
|
||
|
||
- 🆓 完全免费（Agnes-2.0-Flash：Input $0 / Output $0）
|
||
- 🌐 Web 在线识别页：拖拽/多图上传 → 识别 → 复制结果
|
||
- 🖥️ 独立 CLI 工具（`vision-cli`）：不依赖 Web 服务，适合脚本/Claude Code 调用
|
||
- 🖼️ 多图对比、base64 直传（无需图床/公网 URL）
|
||
- 🔁 指数退避自动重试（429/5xx：2s → 5s → 8s → 11s）
|
||
- 🔧 配置：命令行 > 环境变量 > config.yaml > 内置默认
|
||
- 🔒 JWT 登录 + 管理员初始化（脚手架模板能力）
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
cd vision-tool
|
||
go build -o vision-tool.exe . # Web 服务（Windows）
|
||
go build -o vision-cli.exe ./cmd/vision-cli # CLI 工具
|
||
# 或直接运行 build.bat / build.sh
|
||
```
|
||
|
||
### Web 使用
|
||
|
||
```bash
|
||
go run . # 或 ./vision-tool.exe
|
||
# 打开 http://localhost:8080
|
||
```
|
||
|
||
1. 首次访问：初始化管理员账号（右上角）
|
||
2. 拖拽或点击选择图片（可多张）
|
||
3. （可选）输入自定义提问
|
||
4. 点击「开始识别」→ 得到识别结果，可一键复制
|
||
|
||
### CLI 使用
|
||
|
||
```bash
|
||
./vision-cli.exe photo.jpg # 识别图片
|
||
./vision-cli.exe -q --no-think screenshot.png # 安静模式 + 关闭思考（Claude Code 推荐）
|
||
./vision-cli.exe -prompt "提取图中所有文字" img.png
|
||
./vision-cli.exe -q img1.png img2.png # 多图对比
|
||
./vision-cli.exe --apikey YOUR_KEY image.png # 指定 Key
|
||
```
|
||
|
||
Claude Code 在线调用方式：粘贴图片后执行
|
||
|
||
```bash
|
||
/path/to/vision-cli.exe -q --no-think "/path/to/image.png"
|
||
```
|
||
|
||
## 📡 HTTP API
|
||
|
||
统一响应格式：`{code, message, data}`（`code=0` 为成功）
|
||
|
||
### 在线图片识别（免鉴权 + 限流）
|
||
|
||
```bash
|
||
curl -F "images=@a.png" -F "images=@b.png" \
|
||
-F "prompt=比较这两张图的异同" \
|
||
http://localhost:8080/api/v1/vision/analyze
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {
|
||
"result": "……识别结果文本……",
|
||
"images": ["/uploads/xxx.png"],
|
||
"usage": {"prompt_tokens": 120, "completion_tokens": 80, "total_tokens": 200}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 完整接口清单
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|---|---|---|
|
||
| `/api/health` | GET | 健康检查 |
|
||
| `/api/v1/admin/check` | GET | 管理员是否已初始化 |
|
||
| `/api/v1/admin/init` | POST | 初始化管理员 `{username, password}` |
|
||
| `/api/v1/auth/login` | POST | 登录 `{username, password}` → `{token}` |
|
||
| `/api/v1/user/profile` | GET | 当前用户信息（需 `Authorization: Bearer <token>`） |
|
||
| `/api/v1/vision/analyze` | POST | 图片识别（multipart：`images` × 1-N + 可选 `prompt`） |
|
||
| `/uploads/*` | GET | 上传图片静态访问 |
|
||
|
||
## ⚙️ 配置（config.yaml）
|
||
|
||
```yaml
|
||
server:
|
||
port: 8080
|
||
database:
|
||
driver: sqlite # 当前仅 sqlite（pure-go，无需 CGO）
|
||
path: ./data/app.db
|
||
auto_migrate: true
|
||
jwt:
|
||
secret: "change-me-in-production"
|
||
expire_hours: 720
|
||
upload:
|
||
path: uploads
|
||
max_size: 10485760 # 10MB
|
||
ai:
|
||
api_key: "sk-..." # Agnes API Key（或环境变量 AGNES_API_KEY）
|
||
base_url: "https://apihub.agnes-ai.com/v1/chat/completions"
|
||
model: "agnes-2.0-flash"
|
||
```
|
||
|
||
配置优先级：`命令行参数 > 环境变量（AGNES_API_KEY）> config.yaml > 内置默认（内置免费 Key）`
|
||
|
||
## 🧱 项目结构
|
||
|
||
```
|
||
vision-tool/
|
||
├── main.go # Web 服务入口（Gin + //go:embed web）
|
||
├── config.yaml # 统一配置
|
||
├── build.bat / build.sh # 构建脚本
|
||
├── cmd/
|
||
│ └── vision-cli/ # 独立 CLI 工具（打包为单个二进制）
|
||
├── internal/
|
||
│ ├── config/ # 配置加载（yaml + 环境变量覆盖）
|
||
│ ├── database/ # GORM + SQLite 初始化 + AutoMigrate
|
||
│ ├── model/ # 数据模型 + 统一响应格式
|
||
│ ├── repository/ # 数据访问层
|
||
│ ├── service/ # 业务逻辑（auth / vision 免费模型调用）
|
||
│ ├── handler/ # HTTP 处理器
|
||
│ ├── middleware/ # CORS / JWT / 令牌桶限流
|
||
│ └── router/ # 路由注册 + 前端内嵌 + SPA 回退
|
||
└── web/ # 原生单页（在线图片识别，内嵌进二进制）
|
||
├── index.html
|
||
├── css/style.css
|
||
└── js/app.js
|
||
```
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
- 支持图片格式：PNG / JPG / GIF / WebP / BMP / TIFF
|
||
- 单张图片上限 10MB（config.yaml 可调）
|
||
- 识别接口免鉴权但有限流（10 req/s），如需生产部署请修改 JWT secret
|
||
- 生产环境建议 `auto_migrate: false`，手动管理数据库结构
|
||
- 图片过大时建议先压缩（降低延迟与体积）
|
||
|
||
---
|
||
|
||
Made with ❤️ — 推理模型专心推理，图片理解交给免费小模型。
|