# 向量化模块

  **快速上手**：见 `docs/QUICKSTART.md` 第 3.3 节。

  ## 服务接口

  - 文本服务：`POST http://localhost:6005/embed/text`
  - 图片服务：`POST http://localhost:6008/embed/image`
  - 健康检查：`GET /health`
  - 就绪检查：`GET /ready`
  
  ## 当前架构
  
  - 文本 embedding 与图片 embedding 已拆分为两个独立进程 / 端口：
    - text: `6005`
    - image: `6008`
  - 两侧有独立并发控制：
    - `TEXT_MAX_INFLIGHT`
    - `IMAGE_MAX_INFLIGHT`
  - 两侧都接入 Redis 向量缓存，value 统一使用 BF16 bytes 存储。
  
  ## 缓存
  
  - 当前是双层缓存：
    - 调用侧 client 先查 Redis
    - 服务侧收到请求后再查 Redis
  - 当前主 key 规则：
    - 文本：`embedding:embed:norm{0|1}:{text}`
    - 图片：`embedding:image:embed:norm{0|1}:{url_or_path}`
  - full-cache-hit 时，服务会直接返回，不占用模型 lane。

  ## 配置

  - Provider/URL：`config/config.yaml` 的 `services.embedding`

  - 文本服务 URL：`services.embedding.providers.http.text_base_url`
  - 图片服务 URL：`services.embedding.providers.http.image_base_url`

  - 文本模型：`embeddings/config.py` 的 `TEXT_MODEL_ID`（默认 `Qwen/Qwen3-Embedding-0.6B`）
  - 运行参数：`TEXT_DEVICE`、`TEXT_BATCH_SIZE`、`TEXT_NORMALIZE_EMBEDDINGS`

  详见 `embeddings/README.md`。