Geliebte
f9cdeb5d64
- 移除管理员初始化/登录/JWT 流程，改为固定进入密钥（19735500）， 首次启动自动初始化到数据库 settings 表（可改库更新） - analyze 接口支持可选密钥鉴权：X-Access-Key 请求头或 access_key 字段， 带密钥强制校验（错误 401），不带密钥保持免鉴权 - 解锁后顶栏"复制 API 文档"按钮：以当前访问 URL 为基础地址动态生成 Markdown 文档（免鉴权/带密钥两种 curl 示例，供智能体直接调用） - 白昼/黑夜主题切换：CSS 变量驱动，localStorage 持久化，默认跟随系统 - 修复 hidden 属性被 display:flex 覆盖导致解锁层无法隐藏的问题 - 页面去除"免费/Agnes"文案，页脚署名青梧映星软件开发工作室 - build.bat/build.sh 简化为 Linux 交叉编译（CGO_ENABLED=0） - 依赖精简：移除 golang-jwt/bcrypt，直接依赖仅 gin/sqlite/gorm/yaml Co-Authored-By: Claude <noreply@anthropic.com>
154 lines
5.4 KiB
Markdown
154 lines
5.4 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 > 内置默认
|
||
- 🔑 固定进入密钥（默认 `19735500`），密钥初始化到数据库，页面解锁后使用
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 构建
|
||
|
||
```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. 输入进入密钥（默认 `19735500`，存于数据库，可改库更新）解锁页面
|
||
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
|
||
|
||
# 带密钥调用（可选，密钥错误返回 401）
|
||
curl -H "X-Access-Key: 19735500" -F "images=@photo.png" \
|
||
http://localhost:8080/api/v1/vision/analyze
|
||
```
|
||
|
||
鉴权规则：请求头 `X-Access-Key`（或表单字段 `access_key`）提供密钥时强制校验，不提供则放行。
|
||
|
||
响应：
|
||
|
||
```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/auth/verify` | POST | 校验进入密钥 `{key}` → `{ok}`（密钥存于数据库） |
|
||
| `/api/v1/vision/analyze` | POST | 图片识别（multipart：`images` × 1-N + 可选 `prompt`；可选 `X-Access-Key` 密钥鉴权） |
|
||
| `/uploads/*` | GET | 上传图片静态访问 |
|
||
|
||
## ⚙️ 配置（config.yaml）
|
||
|
||
```yaml
|
||
server:
|
||
port: 8080
|
||
database:
|
||
driver: sqlite # 当前仅 sqlite（pure-go，无需 CGO）
|
||
path: ./data/app.db
|
||
auto_migrate: true
|
||
auth:
|
||
access_key: "19735500" # 进入密钥，首次启动初始化到数据库（可改库更新）
|
||
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/ # 数据模型 + 统一响应格式
|
||
│ ├── service/ # 业务逻辑（密钥校验 / vision 免费模型调用）
|
||
│ ├── handler/ # HTTP 处理器
|
||
│ ├── middleware/ # CORS / 令牌桶限流
|
||
│ └── 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 ❤️ — 推理模型专心推理，图片理解交给免费小模型。
|