Embeddings 模块

请求示例见 docs/QUICKSTART.md §3.3。

---

这个目录是一个完整的“向量化模块”，包含：

• HTTP 客户端：text_encoder.py / image_encoder.py（供搜索/索引模块调用）
• 本地模型实现：qwen3_model.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)，本地 CN-CLIP 与 clip-as-service 均实现该接口）

说明：历史上的云端 embedding 试验实现（DashScope）已从主仓库移除，当前仅维护 6005 这条统一向量服务链路。

文本向量后端（默认）

• 6005 文本向量服务默认模型：Qwen/Qwen3-Embedding-0.6B
• 实现方式：SentenceTransformer（trust_remote_code=True）
• 向量归一化：默认开启（可通过环境变量关闭）

服务接口

• POST /embed/text

  • 入参：["文本1", "文本2", ...]
  • 出参：[[...], null, ...]（与输入按 index 对齐，失败为 null）

• POST /embed/image

  • 入参：["url或本地路径1", ...]
  • 出参：[[...], null, ...]（与输入按 index 对齐，失败为 null）

图片向量：clip-as-service（推荐）

默认使用 third-party/clip-as-service 的 Jina CLIP 服务生成图片向量。

1. 安装 clip-client（首次使用）：

   pip install -e third-party/clip-as-service/client
   

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

启动服务

使用仓库脚本启动（默认端口 6005）：

./scripts/start_embedding_service.sh

修改配置

编辑 embeddings/config.py：

• PORT: 服务端口（默认 6005）
• TEXT_MODEL_ID, TEXT_DEVICE, TEXT_BATCH_SIZE, TEXT_NORMALIZE_EMBEDDINGS
• USE_CLIP_AS_SERVICE, CLIP_AS_SERVICE_SERVER：图片向量（clip-as-service）
• IMAGE_MODEL_NAME, IMAGE_DEVICE：本地 CN-CLIP（当 USE_CLIP_AS_SERVICE=false 时）