Upload docs/zh/INFERENCE.md with huggingface_hub

docs/zh/INFERENCE.md

@@ -0,0 +1,120 @@
+# 推理指南
+
+## 规格速览
+
+| 项 | 值 |
+|---|---|
+| 输入名 | `input` |
+| 输入形状 | `[batch, 3, 64, 160]` |
+| 输入类型 | float32, 值域 [0,1] (RGB) |
+| 输出名 | `logits` |
+| 输出形状 | `[batch, 4, 10]` |
+| 解码 | 每位置 argmax → 数字 |
+| ONNX opset | 18 |
+
+预处理只有 3 步，无其他：RGB → 缩放到 160x64（双线性）→ 除以 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"
+    "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：先写全部 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 } }
+        code[p] = '0' + byte(best)
+    }
+    return string(code), nil
+}
+```
+
+> 注意：`onnxruntime_go.NewSession` 从文件读模型。若用 `go:embed` 内嵌模型，改用 `NewSessionWithONNXData` 传字节。
+
+## 性能
+
+- 单张推理：约 5-15ms（CPU，M1/现代 x86）
+- 全流程（加载+预处理+推理）：约 10-30ms
+- 无 GPU 依赖，内存占用 < 50MB