# Embeddings 模块
  
  **请求示例**见 `docs/QUICKSTART.md` §3.3。

  **专项文档**：
  - `../docs/TEI_SERVICE说明文档.md`
  - `../docs/CNCLIP_SERVICE说明文档.md`

  
  ---

  
  这个目录是一个完整的“向量化模块”，包含：
  
  - **HTTP 客户端**：`text_encoder.py` / `image_encoder.py`（供搜索/索引模块调用）

  - **本地模型实现**：`text_embedding_sentence_transformers.py` / `clip_model.py`

  - **clip-as-service 客户端**：`clip_as_service_encoder.py`（图片向量，推荐）

  - **向量化服务（FastAPI）**：`server.py`
  - **统一配置**：`config.py`

  - **接口契约**：`protocols.ImageEncoderProtocol`（图片编码统一为 `encode_image_urls(urls, batch_size, normalize_embeddings)`，本地 CN-CLIP 与 clip-as-service 均实现该接口）

  说明：历史上的云端 embedding 试验实现（DashScope）已从主仓库移除。当前默认部署为**文本服务 6005** 与**图片服务 6008** 两条链路，也兼容 `all` 模式单进程启动。

  
  ### 文本向量后端（默认）
  

  - 6005 文本向量服务默认后端：`TEI`（Text Embeddings Inference）
  - 默认模型：`Qwen/Qwen3-Embedding-0.6B`
  - 后端配置来源：`config/config.yaml -> services.embedding.backend/backends`
  - 环境变量覆盖：`EMBEDDING_BACKEND`、`TEI_BASE_URL`、`TEI_TIMEOUT_SEC`

  ### 服务接口
  

  - 文本服务（默认 `6005`）
    - `POST /embed/text`
    - `GET /health`
    - `GET /ready`
  - 图片服务（默认 `6008`）
    - `POST /embed/image`
    - `GET /health`
    - `GET /ready`
  

  - `POST /embed/text`
    - 入参：`["文本1", "文本2", ...]`

    - 可选 query 参数：`normalize=true|false`（不传则使用服务端默认）

    - 出参：`[[...], [...], ...]`（与输入按 index 对齐，失败直接报错）

  
  - `POST /embed/image`
    - 入参：`["url或本地路径1", ...]`

    - 可选 query 参数：`normalize=true|false`（不传则使用服务端默认）

    - 出参：`[[...], [...], ...]`（与输入按 index 对齐，失败直接报错）

  ### Redis 向量缓存
  
  - Value 格式没有变化，仍然是 **BF16 bytes**：
    - 写入：`float32 -> BF16 -> bytes`
    - 读取：`bytes -> BF16 -> float32`
  - 现在是**双层缓存**：
    - client 侧：`text_encoder.py` / `image_encoder.py`
    - service 侧：`server.py`
  - 当前主 key 格式：
    - 文本：`embedding:embed:norm{0|1}:{text}`
    - 图片：`embedding:image:embed:norm{0|1}:{url_or_path}`
  - 当前实现不再兼容历史 key 规则，只保留这一套格式，减少代码路径和缓存歧义。
  
  ### 压力隔离与拒绝策略
  
  - 文本与图片各自有独立 admission control：
    - `TEXT_MAX_INFLIGHT`
    - `IMAGE_MAX_INFLIGHT`
  - 图片服务可以配置得比文本更严格。
  - 请求若是 full-cache-hit，会在服务端直接返回，不占用模型并发槽位。
  - 超过处理能力时直接拒绝，比无限排队更稳定。
  

  ### 图片向量：clip-as-service（推荐）
  
  默认使用 `third-party/clip-as-service` 的 Jina CLIP 服务生成图片向量。
  

  1. **安装 embedding 专用环境**（首次使用）：

     ```bash

     ./scripts/setup_embedding_venv.sh
     ```
     如需使用本地 `local_st` 文本后端，再执行：
     ```bash
     INSTALL_LOCAL_ST=1 ./scripts/setup_embedding_venv.sh

     ```
  

  2. **启动 CN-CLIP 服务**（独立 gRPC 服务，默认端口 51000，详见 `../docs/CNCLIP_SERVICE说明文档.md`）：

     ```bash
     ./scripts/start_cnclip_service.sh
     ```
  
  3. **配置**（`embeddings/config.py` 或环境变量）：
     - `USE_CLIP_AS_SERVICE=true`（默认）
     - `CLIP_AS_SERVICE_SERVER=grpc://127.0.0.1:51000`

     - `CLIP_AS_SERVICE_MODEL_NAME=CN-CLIP/ViT-L-14`
     - `scripts/start_cnclip_service.sh` 默认会读取同一个 `CLIP_AS_SERVICE_MODEL_NAME`，也可用 `CNCLIP_MODEL_NAME` 或 `--model-name` 临时覆盖

  ### 启动服务
  

  使用仓库脚本启动：

  
  ```bash

  # GPU（需 nvidia-container-toolkit）

  TEI_DEVICE=cuda ./scripts/start_tei_service.sh

  
  # CPU

  TEI_DEVICE=cpu ./scripts/start_tei_service.sh

  ./scripts/start_embedding_text_service.sh
  ./scripts/start_embedding_image_service.sh
  
  # 或兼容入口
  ./scripts/start_embedding_service.sh text
  ./scripts/start_embedding_service.sh image

  ```
  
  ### 修改配置
  
  编辑 `embeddings/config.py`：
  

  - `PORT`: combined 模式默认端口（默认 6005）

  - `TEXT_MODEL_ID`, `TEXT_DEVICE`, `TEXT_BATCH_SIZE`, `TEXT_NORMALIZE_EMBEDDINGS`

  - `IMAGE_NORMALIZE_EMBEDDINGS`（默认 true）

  - `USE_CLIP_AS_SERVICE`, `CLIP_AS_SERVICE_SERVER`, `CLIP_AS_SERVICE_MODEL_NAME`：图片向量（clip-as-service）

  - `IMAGE_MODEL_NAME`, `IMAGE_DEVICE`：本地 CN-CLIP（当 `USE_CLIP_AS_SERVICE=false` 时）

  - TEI 相关：`TEI_DEVICE`、`TEI_VERSION`、`TEI_MAX_BATCH_TOKENS`、`TEI_MAX_CLIENT_BATCH_SIZE`、`TEI_HEALTH_TIMEOUT_SEC`

  - 分流/限流相关：
    - `EMBEDDING_SERVICE_KIND=all|text|image`
    - `EMBEDDING_TEXT_PORT`
    - `EMBEDDING_IMAGE_PORT`
    - `TEXT_MAX_INFLIGHT`
    - `IMAGE_MAX_INFLIGHT`