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
  • 请求体：["文本1", "文本2", ...]
  • 可选 query 参数：normalize=true|false
  • 返回：[[...], [...], ...]
  • 健康接口：GET /health、GET /ready
• 图片服务（默认 6008）
  • POST /embed/image
  • 请求体：["url或本地路径1", ...]
  • 可选 query 参数：normalize=true|false
  • 返回：[[...], [...], ...]
  • 健康接口：GET /health、GET /ready

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 专用环境（首次使用）：

   ./scripts/setup_embedding_venv.sh
   

   如需使用本地 local_st 文本后端，再执行：

   INSTALL_LOCAL_ST=1 ./scripts/setup_embedding_venv.sh
   

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

   ./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 临时覆盖

启动服务

使用仓库脚本启动：

# 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

修改配置

编辑 embeddings/config.py：

• PORT: all 模式单进程端口（默认 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