Upload docs/INFERENCE.md with huggingface_hub

docs/INFERENCE.md

@@ -1,12 +1,10 @@
-# 推理指南 (INFERENCE.md)
+# 推理指南 / Inference Guide
 
-> **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).
+---
 
-## 规格速览
+## 中文
+
+### 规格速览
 
 | 项 | 值 |
 |---|---|
@@ -18,14 +16,10 @@
 | 解码 | 每位置 argmax → 数字 |
 | ONNX opset | 18 |
 
-**预处理只有 3 步，无其他**：
-1. 转 RGB
-2. 缩放到 160x64（双线性）
-3. 除以 255
-
-不做灰度、不做去噪、不做归一化均值方差。
+预处理只有 3 步，无其他：RGB → 缩放到 160x64（双线性）→ 除以 255。
+不做灰度、不去噪、不做均值方差归一化。
 
-## Python
+### Python
 
 ```bash
 pip install onnxruntime pillow numpy
@@ -52,13 +46,12 @@ def solve_captcha(img_bytes_or_path, model_path="model.onnx"):
     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)
+### Go (onnxruntime_go)
 
-依赖: `github.com/yalue/onnxruntime_go` + onnxruntime 共享库 (.dylib/.so)。
+依赖：`github.com/yalue/onnxruntime_go` + onnxruntime 共享库（.dylib/.so）。
 
 ```go
 package main
@@ -85,12 +78,8 @@ type Solver struct {
 }
 
 func NewSolver(modelPath, libPath string) (*Solver, error) {
-    if libPath != "" {
-        ort.SetSharedLibraryPath(libPath)
-    }
-    if err := ort.InitializeEnvironment(); err != nil {
-        return nil, err
-    }
+    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))
@@ -105,48 +94,160 @@ func NewSolver(modelPath, libPath string) (*Solver, error) {
 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 }
+    // 模型输入为 NCHW：先写全部 R，再 G，再 B
+    for y := 0; y < inH; y++ { for x := 0; x < inW; x++ { r,_,_,_ := dst.At(x,y).RGBA(); data[idx]=float32(r>>8)/255; idx++ } }
+    for y := 0; y < inH; y++ { for x := 0; x < inW; x++ { _,g,_,_ := dst.At(x,y).RGBA(); data[idx]=float32(g>>8)/255; idx++ } }
+    for y := 0; y < inH; y++ { for x := 0; x < inW; x++ { _,_,b,_ := dst.At(x,y).RGBA(); data[idx]=float32(b>>8)/255; idx++ } }
 
+    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 }
-        }
+        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` 传字节。
+> 注意：`onnxruntime_go.NewSession` 从文件读模型。若用 `go:embed` 内嵌模型，
+> 改用 `NewSessionWithONNXData` 传字节。
+
+### 性能
+
+- 单张推理：约 5-15ms（CPU，M1/现代 x86）
+- 全流程（加载+预处理+推理）：约 10-30ms
+- 无 GPU 依赖，内存占用 < 50MB
+
+---
+
+## English
+
+### Specification
+
+| Item | Value |
+|---|---|
+| Input name | `input` |
+| Input shape | `[batch, 3, 64, 160]` |
+| Input type | float32, range [0,1] (RGB) |
+| Output name | `logits` |
+| Output shape | `[batch, 4, 10]` |
+| Decode | argmax per position → digit |
+| ONNX opset | 18 |
+
+Preprocessing is only three steps: RGB → resize to 160x64 (bilinear) → divide by 255.
+No grayscale, no denoising, no mean/std normalization.
+
+### 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)
+
+Deps: `github.com/yalue/onnxruntime_go` + the onnxruntime shared library (.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 }
+    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
+    // NCHW layout: all R, then all G, then all B
+    for y := 0; y < inH; y++ { for x := 0; x < inW; x++ { r,_,_,_ := dst.At(x,y).RGBA(); data[idx]=float32(r>>8)/255; idx++ } }
+    for y := 0; y < inH; y++ { for x := 0; x < inW; x++ { _,g,_,_ := dst.At(x,y).RGBA(); data[idx]=float32(g>>8)/255; idx++ } }
+    for y := 0; y < inH; y++ { for x := 0; x < inW; x++ { _,_,b,_ := dst.At(x,y).RGBA(); data[idx]=float32(b>>8)/255; idx++ } }
+
+    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
+}
+```
 
-## 与 southplus-cli 集成
+> Note: `onnxruntime_go.NewSession` reads the model from a file. If you embed it with
+> `go:embed`, use `NewSessionWithONNXData` with the bytes instead.
 
-项目内已有 `internal/captcha/onnx_solver.go` 骨架，需按上面的 Go 示例适配:
-- 输入 3 通道 (非 1)
-- 去掉旧 CTC/去噪逻辑
-- 输出 4 位置 argmax (非 CTC 解码)
+### Performance
 
-## 性能
+- Single inference: ~5-15ms (CPU, M1/modern x86)
+- Full flow (load + preprocess + infer): ~10-30ms
+- No GPU needed, memory < 50MB
 
-- 单张推理: 约 5-15ms (CPU, M1/现代 x86)
-- 全流程 (加载 + 预处理 + 推理): 约 10-30ms
-- 无 GPU 依赖, 内存占用 < 50MB
+---