# MaskCodeOCR

**Repository Path**: xiaoa7/mask-code-ocr

## Basic Information

- **Project Name**: MaskCodeOCR
- **Description**: 基于大模型（LLM）视觉接口的**验证码识别 / 算术题计算** HTTP 服务（Golang 实现）。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MaskCodeOCR

基于大模型（LLM）视觉接口的**验证码识别 / 算术题计算** HTTP 服务（Golang 实现）。

## 项目简介

MaskCodeOCR 是一个用 **Golang** 编写的 HTTP 接口服务，核心能力是：**接收 Base64 编码的图片，调用大模型的视觉（多模态）接口做 OCR 识别**。重点解决两类场景：

- **验证码识别**：纯数字、纯英文字母、数字 + 字母混合；
- **算术题计算**：识别数学表达式（如 `3 + 5 = ?`、`12 × 4`），并直接返回计算结果。

你只需把图片以 **Base64** 形式 POST 给本服务，即可拿到识别结果或答案。常用于登录、注册、接口调用等场景的「打码 / 识别验证码」后端能力。

## 功能特性

- 📷 接收 **Base64** 编码的图像内容（JPEG / PNG / BMP 等常见格式）
- 🔢 识别**数字验证码**（如 `482913`）
- 🔠 识别**字母验证码**（大小写，如 `AbCx`）
- 🔤 识别**数字 + 字母混合**验证码（如 `7F3K9`）
- ➗ 识别**算术题 / 数学表达式**并返回答案（如 `3 + 5` → `8`）
- 🤖 `auto` 自动判断类型，也可强制指定 `code` / `math`
- 🚀 对接大模型视觉接口（OpenAI 兼容，可通过配置切换网关）
- ⚡ Golang 实现，基于标准库 `net/http`，依赖最小、部署轻量

## 快速开始

### 环境要求

- Go 1.20+
- 一个可用的**大模型视觉 API Key**（OpenAI 或兼容接口）

### 1. 配置

```bash
cp config.example.yaml config.yaml
```

编辑 `config.yaml`，填入真实 API Key 与视觉模型：

```yaml
server:
  port: 8080

llm:
  provider: openai          # openai / openai-compatible
  api_key: "sk-xxxx"        # 你的视觉模型 API Key（不能为占位符）
  model: "gpt-4o-mini"      # 视觉模型名称
  base_url: "https://api.openai.com/v1"
  timeout: 30               # 请求超时（秒）
```

> `config.yaml` 含真实密钥，**不入库**；只提交 `config.example.yaml`（占位符 `sk-xxxx`）。

### 2. 运行

```bash
go mod tidy
go run main.go -config config.yaml
```

服务默认监听 `http://localhost:8080`。

### 3. 调用 `POST /ocr`

```bash
curl -X POST http://localhost:8080/ocr \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "<你的Base64>", "type": "auto"}'
```

验证码响应：

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "type": "code",
    "text": "7F3K9",
    "expression": "",
    "answer": "",
    "elapsed_ms": 823
  }
}
```

算术题响应（图片为 `3 + 5 = ?`）：

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "type": "math",
    "text": "3 + 5 = ?",
    "expression": "3 + 5",
    "answer": "8",
    "elapsed_ms": 823
  }
}
```

### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `image_base64` | string | 是 | 图片的 Base64 编码（建议纯 Base64；带 `data:...;base64,` 前缀也会宽容解析）。上限 8MB |
| `type` | string | 否 | `auto`（自动，默认）/ `code`（验证码）/ `math`（算术题） |

### 业务状态码

| code | 语义 |
|------|------|
| `0` | 成功 |
| `400` | 参数错误（Base64 为空/过大/非法、type 非法） |
| `401` | API Key 无效 |
| `500` | 服务端 / 大模型错误 |

> 所有接口 HTTP 状态码固定为 200，业务结果由 `code` 字段表达。

## 文档

| 文档 | 说明 |
|------|------|
| [架构设计](docs/architecture.md) | 分层、模块职责、数据流与设计决策 |
| [API 接口文档](docs/api.md) | 接口、请求/响应、错误对照 |
| [配置指南](docs/configuration.md) | 配置项、加载与校验规则 |
| [开发与测试](docs/development.md) | 环境、命令、测试与扩展指南 |
| [部署与运维](docs/deployment.md) | 构建、运行、部署与排错 |

## 技术架构

```
客户端 POST /ocr (JSON: image_base64 + type)
  → handler (校验请求、统一响应)
      → service (Base64 解码、Prompt 构造、结果解析)
          → llm (Provider 抽象 → openai 实现)
              → 大模型视觉接口 (OpenAI 兼容 /chat/completions)
```

采用 `internal/` 包裹业务代码，依赖方向自上而下单向，便于测试与扩展。详见 [architecture.md](docs/architecture.md)。

## 项目结构

```
maskcodeocr/
├── main.go                  # 程序入口，装配并启动 HTTP 服务
├── go.mod / go.sum
├── config.example.yaml      # 配置示例（入库，占位符）
├── config.yaml              # 本地真实配置（不入库）
├── AGENTS.md                # 项目开发规范
├── README.md
├── docs/                    # 项目文档
└── internal/
    ├── config/   配置加载与校验
    ├── llm/      大模型 provider 抽象与 OpenAI 实现
    ├── service/  业务逻辑（Base64/Prompt/结果解析）
    └── handler/  HTTP 路由与统一响应
```

## 开发与验证

```bash
go build ./...    # 编译
go vet ./...      # 静态检查
go test ./...     # 测试
```

提交前需保证以上全部通过。详见 [development.md](docs/development.md)。

## License

MIT