README.md
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 这条统一向量服务链路。
文本向量后端（默认）
- 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
服务接口
POST /embed/text- 入参：
["文本1", "文本2", ...] - 可选 query 参数：
normalize=true|false（不传则使用服务端默认） - 出参：
[[...], [...], ...]（与输入按 index 对齐，失败直接报错）
- 入参：
POST /embed/image- 入参：
["url或本地路径1", ...] - 可选 query 参数：
normalize=true|false（不传则使用服务端默认） - 出参：
[[...], [...], ...]（与输入按 index 对齐，失败直接报错）
- 入参：
图片向量：clip-as-service（推荐）
默认使用 third-party/clip-as-service 的 Jina CLIP 服务生成图片向量。
安装 embedding 专用环境（首次使用）：
./scripts/setup_embedding_venv.sh如需使用本地
local_st文本后端，再执行：INSTALL_LOCAL_ST=1 ./scripts/setup_embedding_venv.sh启动 CN-CLIP 服务（独立 gRPC 服务，默认端口 51000，详见
../docs/CNCLIP_SERVICE说明文档.md）：./scripts/start_cnclip_service.sh配置（
embeddings/config.py或环境变量）：USE_CLIP_AS_SERVICE=true（默认）CLIP_AS_SERVICE_SERVER=grpc://127.0.0.1:51000CLIP_AS_SERVICE_MODEL_NAME=CN-CLIP/ViT-L-14scripts/start_cnclip_service.sh默认会读取同一个CLIP_AS_SERVICE_MODEL_NAME，也可用CNCLIP_MODEL_NAME或--model-name临时覆盖
启动服务
使用仓库脚本启动（默认端口 6005）：
# GPU（需 nvidia-container-toolkit）
TEI_DEVICE=cuda ./scripts/start_tei_service.sh
# CPU
TEI_DEVICE=cpu ./scripts/start_tei_service.sh
./scripts/start_embedding_service.sh
修改配置
编辑 embeddings/config.py：
PORT: 服务端口（默认 6005）TEXT_MODEL_ID,TEXT_DEVICE,TEXT_BATCH_SIZE,TEXT_NORMALIZE_EMBEDDINGSIMAGE_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