# 向量化模块

**快速上手**：见 `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`。