ACR Service API

更新：2026-06-02

一页结论

• 当前服务是工业化骨架，不是最终生产网关
• 已提供最小可调用能力：
  1. health
  2. ready
  3. config
  4. cache
  5. recognize
  6. index build
• 已补充：服务就绪探针、基础缓存可见性、索引/模型存在性检查
• 下一阶段重点是：鉴权、异步任务、ANN 索引、监控、错误码规范化

---

1. 服务结构图

flowchart LR
    C[Client] --> H[/health]
    C --> H2[/ready]
    C --> G[/config]
    C --> C2[/cache]
    C --> R[/recognize]
    C --> I[/index/build]

    R --> E[Hybrid Engine Cache]
    I --> B[Index Builders]

---

2. Endpoint 表

Endpoint	方法	作用
/health	GET	健康检查
/config	GET	查看默认配置
/ready	GET	查看模型/索引/manifest 是否就绪
/cache	GET	查看当前 engine cache 状态
/recognize	POST	输入 query，输出候选
/index/build	POST	触发离线索引构建

---

3. 请求流程图

sequenceDiagram
    participant Client
    participant API
    participant Engine

    Client->>API: POST /recognize
    API->>Engine: load matcher/index/model
    Engine-->>API: top-k candidates
    API-->>Client: JSON result

---

4. 文字说明

4.1 为什么先暴露文件路径 API

当前阶段优先验证系统闭环，不急于引入上传存储层与异步 job orchestration。

4.2 /config 的作用

帮助服务侧和调用侧快速确认当前默认数据目录、模型路径与索引前缀。

4.3 后续生产化差距

• 缺鉴权
• 缺对象存储上传
• 缺异步索引任务
• 缺可观测性
• 缺错误码与 SLA 规范

---

5. 细节附录

/health

返回：

{"status":"ok","service":"acr","version":"0.2.0"}

/config

返回：

{
  "data_dir":"data/synthetic_v2",
  "model_path":"data/models_v3/best_model.pt",
  "index_prefix":"data/index_v3/reference",
  "device":"cpu"
}

/ready

返回：

{
  "service":"acr",
  "version":"0.3.0",
  "ready":true,
  "files":{...},
  "manifests":[...],
  "engine_cache_size":0
}

/cache

返回当前进程内 engine cache 统计。

Sources

• See references-and-sources.md for the current source map.