Upload docs/INFERENCE.md with huggingface_hub

docs/INFERENCE.md

@@ -1,3 +1,152 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:a1d9f97f474c43b51e84cd78be7f2baee422c61a1f8df8b0ac76a9e18a55fa2b
-size 4417
+# 推理指南 (INFERENCE.md)
+
+> **English summary**: Model I/O — input `[batch,3,64,160]` float32 RGB (values 0..1),
+> output `[batch,4,10]` logits; argmax per position gives the 4 digits. Preprocessing is only
+> three steps: convert to RGB, resize to 160x64 (bilinear), divide by 255. No grayscale, no
+> denoise, no mean/std normalization. Runs in ~10-30ms on CPU. Go integration uses
+> `onnxruntime_go` with NCHW layout (all R, then all G, then all B).
+
+## 规格速览
+
+| 项 | 值 |
+|---|---|
+| 输入名 | `input` |
+| 输入形状 | `[batch, 3, 64, 160]` |
+| 输入类型 | float32, 值域 [0,1] (RGB) |
+| 输出名 | `logits` |
+| 输出形状 | `[batch, 4, 10]` |
+| 解码 | 每位置 argmax → 数字 |
+| ONNX opset | 18 |
+
+**预处理只有 3 步，无其他**：
+1. 转 RGB
+2. 缩放到 160x64（双线性）
+3. 除以 255
+
+不做灰度、不做去噪、不做归一化均值方差。
+
+## Python
+
+```bash
+pip install onnxruntime pillow numpy
+```
+
+```python
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+
+_SESSION = None
+
+def get_session(model_path="model.onnx"):
+    global _SESSION
+    if _SESSION is None:
+        _SESSION = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
+    return _SESSION
+
+def solve_captcha(img_bytes_or_path, model_path="model.onnx"):
+    sess = get_session(model_path)
+    im = Image.open(img_bytes_or_path).convert("RGB").resize((160, 64), Image.BILINEAR)
+    x = np.asarray(im, dtype=np.float32) / 255.0
+    x = x.transpose(2, 0, 1)[None]          # (1,3,64,160)
+    logits = sess.run(None, {"input": x})[0] # (1,4,10)
+    return "".join(str(int(logits[0, p].argmax())) for p in range(4))
+
+# 用法
+code = solve_captcha("captcha.png")   # "4821"
+```
+
+## Go (onnxruntime_go)
+
+依赖: `github.com/yalue/onnxruntime_go` + onnxruntime 共享库 (.dylib/.so)。
+
+```go
+package main
+
+import (
+    "bytes"
+    "fmt"
+    "image"
+    _ "image/png"
+
+    "golang.org/x/image/draw"
+    ort "github.com/yalue/onnxruntime_go"
+)
+
+const (
+    inW, inH = 160, 64
+    nDigits  = 4
+)
+
+type Solver struct {
+    sess *ort.Session[float32]
+    in   *ort.Tensor[float32]
+    out  *ort.Tensor[float32]
+}
+
+func NewSolver(modelPath, libPath string) (*Solver, error) {
+    if libPath != "" {
+        ort.SetSharedLibraryPath(libPath)
+    }
+    if err := ort.InitializeEnvironment(); err != nil {
+        return nil, err
+    }
+    in, err := ort.NewEmptyTensor[float32](ort.NewShape(1, 3, inH, inW))
+    if err != nil { return nil, err }
+    out, err := ort.NewEmptyTensor[float32](ort.NewShape(1, nDigits, 10))
+    if err != nil { in.Destroy(); return nil, err }
+    sess, err := ort.NewSession[float32](modelPath,
+        []string{"input"}, []string{"logits"},
+        []*ort.Tensor[float32]{in}, []*ort.Tensor[float32]{out})
+    if err != nil { in.Destroy(); out.Destroy(); return nil, err }
+    return &Solver{sess, in, out}, nil
+}
+
+func (s *Solver) Solve(png []byte) (string, error) {
+    src, _, err := image.Decode(bytes.NewReader(png))
+    if err != nil { return "", err }
+    // RGB 缩放到 160x64 (双线性)
+    dst := image.NewRGBA(image.Rect(0, 0, inW, inH))
+    draw.ApproxBiLinear.Scale(dst, dst.Bounds(), src, src.Bounds(), draw.Over, nil)
+
+    data := s.in.GetData()
+    idx := 0
+    for y := 0; y < inH; y++ {
+        for x := 0; x < inW; x++ {
+            r, g, b, _ := dst.At(x, y).RGBA()
+            data[idx+0] = float32(r>>8) / 255.0
+            data[idx+1] = float32(g>>8) / 255.0
+            data[idx+2] = float32(b>>8) / 255.0
+            idx += 3
+        }
+    }
+    if err := s.sess.Run(); err != nil { return "", err }
+
+    got := s.out.GetData()
+    code := make([]byte, nDigits)
+    for p := 0; p < nDigits; p++ {
+        best := 0
+        for c := 1; c < 10; c++ {
+            if got[p*10+c] > got[p*10+best] { best = c }
+        }
+        code[p] = '0' + byte(best)
+    }
+    return string(code), nil
+}
+```
+
+> 注意: `onnxruntime_go.NewSession` 从文件读取模型字节。若用 `go:embed`
+> 内嵌模型，改用 `NewSessionWithONNXData` 传字节。
+
+## 与 southplus-cli 集成
+
+项目内已有 `internal/captcha/onnx_solver.go` 骨架，需按上面的 Go 示例适配:
+- 输入 3 通道 (非 1)
+- 去掉旧 CTC/去噪逻辑
+- 输出 4 位置 argmax (非 CTC 解码)
+
+## 性能
+
+- 单张推理: 约 5-15ms (CPU, M1/现代 x86)
+- 全流程 (加载 + 预处理 + 推理): 约 10-30ms
+- 无 GPU 依赖, 内存占用 < 50MB