文本 embedding 与图片 embedding 已拆分为两个独立进程 / 端口

tangwang
1 parent 7214c2e7
Showing 16 changed files with 229 additions and 150 deletions Show diff stats
docs/CNCLIP_SERVICE说明文档.md
docs/DEVELOPER_GUIDE.md
docs/QUICKSTART.md
docs/TEI_SERVICE说明文档.md
docs/Usage-Guide.md
docs/向量化模块和API说明文档.md
docs/工作总结-微服务性能优化与架构.md
docs/搜索API对接指南.md
docs/缓存与Redis使用说明.md
embeddings/README.md
embeddings/cache_keys.py
embeddings/image_encoder.py
embeddings/text_encoder.py
scripts/trace_indexer_calls.sh
utils/__init__.py
utils/cache.py
@@ -5,7 +5,7 @@
 ## 1. 作用与边界
 - `cnclip` 是独立 gRPC 服务（默认 `grpc://127.0.0.1:51000`）。
-- `embedding` 服务（6005）在 `USE_CLIP_AS_SERVICE=true` 时调用它完成 `/embed/image`。
+- 图片 embedding 服务（默认 `6008`）在 `USE_CLIP_AS_SERVICE=true` 时调用它完成 `/embed/image`。
 - `cnclip` 不负责文本向量；文本向量由 TEI（8080）负责。
 ## 2. 代码与脚本入口
@@ -90,7 +90,7 @@ CNCLIP_MODEL_NAME=CN-CLIP/ViT-H-14 ./scripts/service_ctl.sh start cnclip
 ```bash
 ./scripts/service_ctl.sh start cnclip
-# 或一次启动可选能力：./scripts/service_ctl.sh start embedding tei cnclip
+# 或一次启动可选能力：./scripts/service_ctl.sh start embedding embedding-image tei cnclip
 ```
 ### 6.2 设备选择优先级
@@ -162,9 +162,9 @@ GPU 模式下应出现 `clip_server` 相关 `python` 进程及显存占用。
 ### 7.5 与 embedding 服务联调
 ```bash
-./scripts/start_embedding_service.sh
+./scripts/start_embedding_image_service.sh
-curl -sS -X POST "http://127.0.0.1:6005/embed/image" \
+curl -sS -X POST "http://127.0.0.1:6008/embed/image" \
   -H "Content-Type: application/json" \
   -d '["https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg"]'
 ```
@@ -92,7 +92,8 @@ MySQL (店匠 SPU/SKU)
 | backend | 6002 | 搜索 API（含 admin） | ✓ |
 | indexer | 6004 | 索引 API（reindex/build-docs 等） | ✓ |
 | frontend | 6003 | 调试 UI | ✓ |
-| embedding | 6005 | 向量服务（文本/图片） | 可选 |
+| embedding | 6005 | 文本向量服务 | 可选 |
+| embedding-image | 6008 | 图片向量服务 | 可选 |
 | translator | 6006 | 翻译服务（`POST /translate` 支持单条或批量 list；批量失败用 `null` 占位） | 可选 |
 | reranker | 6007 | 重排服务 | 可选 |
@@ -156,8 +157,8 @@ docs/                # 文档（含本指南）
 ### 4.6 embeddings
-- **职责**：提供向量服务（FastAPI）：`POST /embed/text`、`POST /embed/image`；服务内按配置加载文本后端（如 Qwen3-Embedding-0.6B）与图像后端（如 clip-as-service 或本地 CN-CLIP），实现协议即可插拔。
-- **原则**：图片后端实现 `embeddings/protocols.ImageEncoderProtocol`；文本后端与参数统一从 `config/config.yaml -> services.embedding.backend(s)` 读取。
+- **职责**：提供向量服务（FastAPI）：文本服务默认监听 `6005`，图片服务默认监听 `6008`；对外暴露 `POST /embed/text`、`POST /embed/image`、`GET /health`、`GET /ready`；服务内按配置加载文本后端（如 Qwen3-Embedding-0.6B）与图像后端（如 clip-as-service 或本地 CN-CLIP），实现协议即可插拔。
+- **原则**：图片后端实现 `embeddings/protocols.ImageEncoderProtocol`；文本后端与参数统一从 `config/config.yaml -> services.embedding.backend(s)` 读取；文本与图片流量应通过独立进程和独立 inflight limit 做隔离。
 - **详见**：`embeddings/README.md`、本指南 §7.5–§7.6。
 ### 4.7 reranker
@@ -57,7 +57,8 @@ source activate.sh
 | backend | 6002 | ✓ | 搜索 API（`/search/*`）+ 管理接口（`/admin/*`） |
 | indexer | 6004 | ✓ | 索引 API（`/indexer/*`） |
 | frontend | 6003 | ✓ | 调试 UI |
-| embedding | 6005 | - | 向量服务（`/embed/text`, `/embed/image`） |
+| embedding | 6005 | - | 文本向量服务（`/embed/text`） |
+| embedding-image | 6008 | - | 图片向量服务（`/embed/image`） |
 | translator | 6006 | - | 翻译服务（`/translate`） |
 | reranker | 6007 | - | 重排服务（`/rerank`） |
@@ -135,21 +136,22 @@ curl -X POST http://localhost:6004/indexer/build-docs \
 API 文档：`http://localhost:6004/docs`
-#### Embedding 服务（6005）
+#### Embedding 服务（文本 6005 / 图片 6008）
 ```bash
 # TEI（文本向量后端，默认）
 # GPU（需 nvidia-container-toolkit）
 TEI_DEVICE=cuda ./scripts/start_tei_service.sh
-# Embedding API（会校验 TEI /health）
-./scripts/start_embedding_service.sh
+# Embedding API（text 会校验 TEI /health）
+./scripts/start_embedding_text_service.sh
+./scripts/start_embedding_image_service.sh
 curl -X POST http://localhost:6005/embed/text \
   -H "Content-Type: application/json" \
   -d '["衣服", "Bohemian Maxi Dress"]'
-curl -X POST http://localhost:6005/embed/image \
+curl -X POST http://localhost:6008/embed/image \
   -H "Content-Type: application/json" \
   -d '["https://example.com/img.jpg"]'
 ```
@@ -157,7 +159,7 @@ curl -X POST http://localhost:6005/embed/image \
 说明：
 - TEI 默认镜像按 `TEI_VERSION` 组装：`cuda-<version>`（默认 `1.9`）。
 - `TEI_DEVICE=cuda` 时会严格校验 Docker GPU runtime；未配置会直接报错退出。
-- `/embed/image` 依赖 `cnclip`（`grpc://127.0.0.1:51000`），未启动时 embedding 服务会启动失败。
+- `/embed/image` 依赖 `cnclip`（`grpc://127.0.0.1:51000`），未启动时图片 embedding 服务会启动失败。
 #### Translator 服务（6006）
@@ -530,6 +532,7 @@ curl http://localhost:6002/health
 curl http://localhost:6002/admin/health
 curl http://localhost:6004/health
 curl http://localhost:6005/health
+curl http://localhost:6008/health
 curl http://localhost:6006/health
 curl http://localhost:6007/health
 ```
@@ -5,7 +5,7 @@
 ## 1. 作用与边界
 - TEI 提供文本向量 HTTP 服务（默认 `http://127.0.0.1:8080`）。
-- 本项目中 `embedding` 服务（6005）默认把文本向量请求转发到 TEI。
+- 本项目中文本 embedding 服务（默认 `6005`）把文本向量请求转发到 TEI。
 - TEI 仅负责文本向量，不负责图片向量（图片向量由 `cnclip` 提供）。
 ## 2. 代码与脚本入口
@@ -13,7 +13,7 @@
 - 启动脚本：`scripts/start_tei_service.sh`
 - 停止脚本：`scripts/stop_tei_service.sh`
 - 统一编排：`scripts/service_ctl.sh`
-- embedding 服务启动脚本（会校验 TEI 健康）：`scripts/start_embedding_service.sh`
+- 文本 embedding 服务启动脚本（会校验 TEI 健康）：`scripts/start_embedding_text_service.sh`
 ## 3. 前置条件
@@ -117,7 +117,7 @@ curl -sS http://127.0.0.1:8080/embed \
 ### 6.3 与 embedding 服务联调
 ```bash
-./scripts/start_embedding_service.sh
+./scripts/start_embedding_text_service.sh
 curl -sS -X POST "http://127.0.0.1:6005/embed/text" \
   -H "Content-Type: application/json" \
@@ -152,7 +152,7 @@ curl -sS -X POST &quot;http://127.0.0.1:6005/embed/text&quot; \
 启动全套（含 TEI）：
 ```bash
-TEI_DEVICE=cuda ./scripts/service_ctl.sh start tei cnclip embedding translator reranker
+TEI_DEVICE=cuda ./scripts/service_ctl.sh start tei cnclip embedding embedding-image translator reranker
 ```
 仅启动 TEI：
@@ -335,7 +335,8 @@ python -m http.server 6003
 | Backend API | 6002 | http://localhost:6002 |
 | Indexer API | 6004 | http://localhost:6004 |
 | Frontend Web | 6003 | http://localhost:6003 |
-| Embedding (optional) | 6005 | http://localhost:6005 |
+| Embedding Text (optional) | 6005 | http://localhost:6005 |
+| Embedding Image (optional) | 6008 | http://localhost:6008 |
 | TEI (optional) | 8080 | http://localhost:8080 |
 | Translation (optional) | 6006 | http://localhost:6006 |
 | Reranker (optional) | 6007 | http://localhost:6007 |
@@ -380,7 +381,8 @@ INDEXER_PORT=6004
 # Optional service ports
 FRONTEND_PORT=6003
-EMBEDDING_PORT=6005
+EMBEDDING_TEXT_PORT=6005
+EMBEDDING_IMAGE_PORT=6008
 TEI_PORT=8080
 CNCLIP_PORT=51000
 TRANSLATION_PORT=6006
@@ -4,12 +4,36 @@
 ## 服务接口
-- `POST /embed/text`：文本向量，入参 `["text1", "text2"]`，出参 `[[...], [...]]`
-- `POST /embed/image`：图片向量，入参 `["url1", "url2"]`，出参 `[[...], [...]]`
+- 文本服务：`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`
@@ -16,12 +16,12 @@
 | **vLLM** | 高吞吐推理框架，更适合生成式与重排混合场景 | 纯 embedding 场景通常不作为首选 |
 | **TEI** | HuggingFace 官方 embedding 专用推理服务，Docker 部署 | **当前最优选型** |
-**当前方案**：以 **TEI** 为文本向量后端，模型为 `Qwen/Qwen3-Embedding-0.6B`，embedding 服务（端口 **6005**）将 `POST /embed/text` 请求转发至 TEI（默认端口 **8080**）。
+**当前方案**：以 **TEI** 为文本向量后端，模型为 `Qwen/Qwen3-Embedding-0.6B`；文本 embedding 服务（端口 **6005**）将 `POST /embed/text` 请求转发至 TEI（默认端口 **8080**）。
 **具体配置与脚本**：
 - **配置**：`config/config.yaml` → `services.embedding.backend: "tei"`，`services.embedding.backends.tei.base_url: "http://127.0.0.1:8080"`、`model_id: "Qwen/Qwen3-Embedding-0.6B"`、`timeout_sec: 20`。
 - **启动**：`scripts/start_tei_service.sh`（Docker 容器）；环境变量：`TEI_DEVICE=cuda`（默认）、`TEI_PORT=8080`、`TEI_MODEL_ID=Qwen/Qwen3-Embedding-0.6B`、`TEI_VERSION=1.9`、`TEI_MAX_BATCH_TOKENS=4096`、`TEI_MAX_CLIENT_BATCH_SIZE=24`、`TEI_DTYPE=float16`；T4 自动选镜像 `ghcr.io/huggingface/text-embeddings-inference:turing-1.9`。
-- **编排**：`./scripts/service_ctl.sh start tei` 或 `start embedding`（embedding 会校验 TEI `/health` 后再就绪）。
+- **编排**：`./scripts/service_ctl.sh start tei` 或 `start embedding`（text embedding 会校验 TEI `/health` 后再就绪）。
 **工程化收益**：
 - **独立服务**：TEI 以 Docker 容器运行，与主程序 `.venv` 解耦；embedding 使用 `.venv-embedding`，便于独立扩缩容与升级。
@@ -71,7 +71,7 @@ instruction: &quot;Given a shopping query, rank product titles by relevance&quot;
 **具体内容**：
 - **端口**：clip-as-service 默认 **51000**（`CNCLIP_PORT`）；文本走 TEI（8080），图片走 clip-as-service。
-- **API**：embedding 服务（6005）统一暴露 `POST /embed/text` 与 `POST /embed/image`；图片请求由 `embeddings/server.py` 按配置调用实现 `ImageEncoderProtocol` 的后端（clip-as-service 或本地 CN-CLIP）。
+- **API**：文本 embedding 服务默认暴露 `POST /embed/text`（6005），图片 embedding 服务默认暴露 `POST /embed/image`（6008）；图片请求由 `embeddings/server.py` 按配置调用实现 `ImageEncoderProtocol` 的后端（clip-as-service 或本地 CN-CLIP）。
 - **环境与启停**：CN-CLIP 使用独立虚拟环境 `.venv-cnclip`；启动 `scripts/start_cnclip_service.sh`，或 `./scripts/service_ctl.sh start cnclip`；设备可通过 `CNCLIP_DEVICE=cuda`（默认）或 `cpu` 指定。
 - **配置**：图片后端在 `config/config.yaml` 的 `services.embedding` 下配置（若存在 image 相关 backend）；clip-as-service 默认模型由 `embeddings/config.py` 的 `CLIP_AS_SERVICE_MODEL_NAME` 控制，flow 配置在 `third-party/clip-as-service/server/torch-flow-temp.yml`。
@@ -127,8 +127,8 @@ instruction: &quot;Given a shopping query, rank product titles by relevance&quot;
 - **脚本**：`scripts/service_ctl.sh` 统一负责各服务的生命周期与监控；依赖 `scripts/lib/load_env.sh` 与项目根目录 `.env`。
 - **服务与端口**：
   - 核心：backend **6002**、indexer **6004**、frontend **6003**。
-  - 可选：embedding **6005**、translator **6006**、reranker **6007**、tei **8080**、cnclip **51000**。
-  - 端口可由环境变量覆盖：`API_PORT`、`INDEXER_PORT`、`FRONTEND_PORT`、`EMBEDDING_PORT`、`TRANSLATION_PORT`、`RERANKER_PORT`、`TEI_PORT`、`CNCLIP_PORT`。
+  - 可选：embedding(text) **6005**、embedding-image **6008**、translator **6006**、reranker **6007**、tei **8080**、cnclip **51000**。
+  - 端口可由环境变量覆盖：`API_PORT`、`INDEXER_PORT`、`FRONTEND_PORT`、`EMBEDDING_TEXT_PORT`、`EMBEDDING_IMAGE_PORT`、`TRANSLATION_PORT`、`RERANKER_PORT`、`TEI_PORT`、`CNCLIP_PORT`。
 - **命令**：
   - `./scripts/service_ctl.sh start [service...]` 或 `start all`（all = tei cnclip embedding translator reranker backend indexer frontend，按依赖顺序）；`stop`、`restart` 同参数；`status` 默认列出所有服务。
   - 启动时：backend/indexer/frontend/embedding/translator/reranker 会写 pid 到 `logs/<service>.pid`，并执行 `wait_for_health`（GET `http://127.0.0.1:<port>/health`）；reranker 健康重试 90 次，其余 30 次；TEI 校验 Docker 容器存在且 `/health` 成功；cnclip 无 HTTP 健康则仅校验进程/端口。
@@ -157,8 +157,8 @@ curl -X POST &quot;http://43.166.252.75:6002/search/&quot; \
 | 服务 | 端口 | 接口 | 说明 |
 |------|------|------|------|
-| 向量服务 | 6005 | `POST /embed/text` | 文本向量化 |
-| 向量服务 | 6005 | `POST /embed/image` | 图片向量化 |
+| 向量服务（文本） | 6005 | `POST /embed/text` | 文本向量化 |
+| 向量服务（图片） | 6008 | `POST /embed/image` | 图片向量化 |
 | 翻译服务 | 6006 | `POST /translate` | 文本翻译（支持 qwen-mt / llm / deepl / 本地模型） |
 | 重排服务 | 6007 | `POST /rerank` | 检索结果重排 |
 | 内容理解（Indexer 内） | 6004 | `POST /indexer/enrich-content` | 根据商品标题生成 qanchors、tags 等，供 indexer 微服务组合方式使用 |
@@ -1691,7 +1691,8 @@ curl -X POST &quot;http://localhost:6004/indexer/enrich-content&quot; \
 | 服务 | 默认端口 | Base URL | 说明 |
 |------|----------|----------|------|
-| 向量服务 | 6005 | `http://localhost:6005` | 文本/图片向量化，用于语义搜索与以图搜图 |
+| 向量服务（文本） | 6005 | `http://localhost:6005` | 文本向量化，用于 query/doc 语义检索 |
+| 向量服务（图片） | 6008 | `http://localhost:6008` | 图片向量化，用于以图搜图 |
 | 翻译服务 | 6006 | `http://localhost:6006` | 多语言翻译（云端与本地模型统一入口） |
 | 重排服务 | 6007 | `http://localhost:6007` | 对检索结果进行二次排序 |
@@ -1700,13 +1701,28 @@ curl -X POST &quot;http://localhost:6004/indexer/enrich-content&quot; \
 ### 7.1 向量服务（Embedding）
-- **Base URL**: `http://localhost:6005`（可通过 `EMBEDDING_SERVICE_URL` 覆盖）
-- **启动**: `./scripts/start_embedding_service.sh`
+- **Base URL**:
+  - 文本：`http://localhost:6005`（可通过 `EMBEDDING_TEXT_SERVICE_URL` 覆盖）
+  - 图片：`http://localhost:6008`（可通过 `EMBEDDING_IMAGE_SERVICE_URL` 覆盖）
+- **启动**:
+  - 文本：`./scripts/start_embedding_text_service.sh`
+  - 图片：`./scripts/start_embedding_image_service.sh`
+  - 兼容入口：`./scripts/start_embedding_service.sh text|image|all`
 - **依赖**:
   - 文本向量后端默认走 TEI（`http://127.0.0.1:8080`）
   - 图片向量依赖 `cnclip`（`grpc://127.0.0.1:51000`）
   - TEI 默认使用 GPU（`TEI_DEVICE=cuda`）；当配置为 GPU 且不可用时会启动失败（不会自动降级到 CPU）
   - cnclip 默认使用 `cuda`；若配置为 `cuda` 但 GPU 不可用会启动失败（不会自动降级到 `cpu`）
+  - 当前单机部署建议保持单实例，通过**文本/图片拆分 + 独立限流**隔离压力
+
+补充说明：
+
+- 文本和图片现在已经拆成**不同进程 / 不同端口**，避免图片下载与编码波动影响文本向量化。
+- 服务端对 text / image 有**独立 admission control**：
+  - `TEXT_MAX_INFLIGHT`
+  - `IMAGE_MAX_INFLIGHT`
+- 当超过处理能力时，服务会直接返回过载错误，而不是无限排队。
+- `GET /health` 会返回各自的 `limits`、`stats`、`cache_enabled` 等状态；`GET /ready` 用于就绪探针。
 #### 7.1.1 `POST /embed/text` — 文本向量化
@@ -1724,7 +1740,7 @@ curl -X POST &quot;http://localhost:6004/indexer/enrich-content&quot; \
 **完整 curl 示例**:
 ```bash
-curl -X POST "http://localhost:6005/embed/text" \
+curl -X POST "http://localhost:6005/embed/text?normalize=true" \
   -H "Content-Type: application/json" \
   -d '["芭比娃娃 儿童玩具", "纯棉T恤 短袖"]'
 ```
@@ -1733,7 +1749,7 @@ curl -X POST &quot;http://localhost:6005/embed/text&quot; \
 将图片 URL 或路径转为向量，用于以图搜图。
-前置条件：`cnclip` 服务已启动（默认端口 `51000`）。若未启动，`/embed/image` 会返回 500。
+前置条件：`cnclip` 服务已启动（默认端口 `51000`）。若未启动，图片 embedding 服务启动会失败或请求返回错误。
 **请求体**（JSON 数组）:
 ```json
@@ -1747,7 +1763,7 @@ curl -X POST &quot;http://localhost:6005/embed/text&quot; \
 **完整 curl 示例**:
 ```bash
-curl -X POST "http://localhost:6005/embed/image" \
+curl -X POST "http://localhost:6008/embed/image?normalize=true" \
   -H "Content-Type: application/json" \
   -d '["https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg"]'
 ```
@@ -1756,9 +1772,32 @@ curl -X POST &quot;http://localhost:6005/embed/image&quot; \
 ```bash
 curl "http://localhost:6005/health"
+curl "http://localhost:6008/health"
+```
+
+返回中会包含：
+
+- `service_kind`：`text` / `image` / `all`
+- `cache_enabled`：text/image Redis 缓存是否可用
+- `limits`：当前 inflight limit、active、rejected_total 等
+- `stats`：request_total、cache_hits、cache_misses、avg_latency_ms 等
+
+#### 7.1.4 `GET /ready` — 就绪检查
+
+```bash
+curl "http://localhost:6005/ready"
+curl "http://localhost:6008/ready"
 ```
-#### 7.1.4 TEI 统一调优建议（主服务）
+#### 7.1.5 缓存与限流说明
+
+- 文本与图片都会先查 Redis 向量缓存。
+- Redis 中 value 仍是 **BF16 bytes**，读取后恢复成 `float32` 返回。
+- cache key 已区分 `normalize=true/false`，避免不同归一化策略命中同一条缓存。
+- 当服务端发现请求是 **full-cache-hit** 时，会直接返回，不占用模型并发槽位。
+- 当服务端发现超过 `TEXT_MAX_INFLIGHT` / `IMAGE_MAX_INFLIGHT` 时，会直接拒绝，而不是无限排队。
+
+#### 7.1.6 TEI 统一调优建议（主服务）
 使用单套主服务即可同时兼顾：
 - 在线 query 向量化（低延迟，常见 `batch=1~4`）
@@ -1773,7 +1812,8 @@ curl &quot;http://localhost:6005/health&quot;
 默认端口：
 - TEI: `http://127.0.0.1:8080`
-- 向量服务（`/embed/text`）: `http://127.0.0.1:6005`
+- 文本向量服务（`/embed/text`）: `http://127.0.0.1:6005`
+- 图片向量服务（`/embed/image`）: `http://127.0.0.1:6008`
 当前主 TEI 启动默认值（已按 T4/短文本场景调优）：
 - `TEI_MAX_BATCH_TOKENS=4096`
@@ -19,7 +19,7 @@
 | 模块 / 场景 | Key 模板 | Value 内容示例 | 过期策略 | 备注 |
 |------------|----------|----------------|----------|------|
-| 向量缓存（text/image embedding） | `{EMBEDDING_CACHE_PREFIX}:{query_or_url}` / `{EMBEDDING_CACHE_PREFIX}:image:{url_or_path}` | **BF16 bytes**（每维 2 字节大端存储），读取后恢复为 `np.float32` | TTL=`REDIS_CONFIG["cache_expire_days"]` 天；访问时滑动过期 | 见 `embeddings/text_encoder.py`（文本）与 `embeddings/image_encoder.py`（图片）；前缀由 `REDIS_CONFIG["embedding_cache_prefix"]` 控制 |
+| 向量缓存（text/image embedding） | 文本：`{EMBEDDING_CACHE_PREFIX}:embed:norm{0|1}:{text}`；图片：`{EMBEDDING_CACHE_PREFIX}:image:embed:norm{0|1}:{url_or_path}` | **BF16 bytes**（每维 2 字节大端存储），读取后恢复为 `np.float32` | TTL=`REDIS_CONFIG["cache_expire_days"]` 天；访问时滑动过期 | 见 `embeddings/text_encoder.py`、`embeddings/image_encoder.py`、`embeddings/server.py`；前缀由 `REDIS_CONFIG["embedding_cache_prefix"]` 控制 |
 | 翻译结果缓存（translator service） | `trans:{model}:{target_lang}:{source_text[:4]}{sha256(source_text)}` | 机翻后的单条字符串 | TTL=`services.translation.cache.ttl_seconds` 秒；可配置滑动过期 | 见 `translation/service.py` + `config/config.yaml` |
 | 商品内容理解缓存（anchors / 语义属性 / tags） | `{ANCHOR_CACHE_PREFIX}:{tenant_or_global}:{target_lang}:{md5(title)}` | `json.dumps(dict)`，包含 id/title/category/tags/anchor_text 等 | TTL=`ANCHOR_CACHE_EXPIRE_DAYS` 天 | 见 `indexer/product_enrich.py` |
@@ -27,23 +27,49 @@
 ---
-## 2. 文本向量缓存（embeddings/text_encoder.py）
+## 2. 向量缓存（embeddings/text_encoder.py / embeddings/image_encoder.py / embeddings/server.py）
-- **代码位置**：`embeddings/text_encoder.py` 中 `TextEmbeddingEncoder`
-- **用途**：缓存调用向量服务（6005）的文本向量结果，避免重复计算。
+- **代码位置**：
+  - 调用侧：`embeddings/text_encoder.py`、`embeddings/image_encoder.py`
+  - 服务侧：`embeddings/server.py`
+  - 公共 Redis/BF16 编解码：`embeddings/redis_embedding_cache.py`、`embeddings/bf16.py`
+- **用途**：缓存文本/图片向量结果，避免重复推理、重复下载图片、重复占用模型并发槽位。
+
+### 2.0 当前缓存链路总览
+
+- 现在是**双层缓存**：
+  - **调用侧缓存**：`TextEmbeddingEncoder` / `CLIPImageEncoder` 在发 HTTP 请求前先查 Redis；
+  - **服务侧缓存**：`/embed/text` / `/embed/image` 在进入后端推理前再查 Redis。
+- 这次改动里，**BF16 存储格式本身没有变化**：
+  - 写入：`float32 -> BF16 -> bytes -> Redis`
+  - 读取：`Redis bytes -> BF16 -> float32(np.float32)`
+- 这次新增的核心变化是：
+  - **缓存 key 加入 normalize 维度**，避免 `normalize=true` 与 `normalize=false` 命中同一条缓存；
+  - **服务端也启用同一套 Redis 向量缓存**，而不是只有 client 侧缓存；
+  - **拆分 text / image 服务** 后，图片压力不会再拖慢文本服务；
+  - **服务侧 full-cache-hit 可直接返回**，不会再进入模型限流槽位。
 ### 2.1 Key 设计
-- 函数：`_get_cache_key(query: str, normalize_embeddings: bool) -> str`
+- 统一 helper：`embeddings/cache_keys.py`
+- 文本主 key：`build_text_cache_key(text, normalize=...)`
+- 图片主 key：`build_image_cache_key(url, normalize=...)`
 - 模板：
 ```text
-{EMBEDDING_CACHE_PREFIX}:{query}
+文本: {EMBEDDING_CACHE_PREFIX}:embed:norm{0|1}:{text}
+图片: {EMBEDDING_CACHE_PREFIX}:image:embed:norm{0|1}:{url_or_path}
 ```
 - 字段说明：
   - `EMBEDDING_CACHE_PREFIX`：来自 `REDIS_CONFIG["embedding_cache_prefix"]`，默认值为 `"embedding"`，可通过环境变量 `REDIS_EMBEDDING_CACHE_PREFIX` 覆盖；
-  - `query`：原始文本（未做哈希），注意长度特别长的 query 会直接出现在 key 中。
+  - `norm1` / `norm0`：分别表示 `normalize=true` / `normalize=false`；
+  - `text` / `url_or_path`：当前仍直接使用规范化后的原始输入，不做哈希。
+
+补充说明：
+
+- 本次把 raw key 格式统一成 `embed:norm{0|1}:...`，比以 `norm:` 开头更清晰，也更接近历史命名习惯。
+- 当前实现**不再兼容历史 key 协议**，只保留这一套主 key 规则，以降低运行时复杂度和歧义。
 ### 2.2 Value 与类型
@@ -68,6 +94,23 @@
   - 直接丢弃该缓存（并尝试 `delete` key）；
   - 回退为重新调用向量服务。
+### 2.5 服务拆分与缓存/限流关系
+
+- 当前默认部署形态：
+  - 文本 embedding 服务：`6005`
+  - 图片 embedding 服务：`6008`
+- 调用方配置：
+  - `EMBEDDING_TEXT_SERVICE_URL`
+  - `EMBEDDING_IMAGE_SERVICE_URL`
+- 服务端配置：
+  - `TEXT_MAX_INFLIGHT`
+  - `IMAGE_MAX_INFLIGHT`
+  - `EMBEDDING_SERVICE_KIND=all|text|image`
+- 关键行为：
+  - **full-cache-hit** 请求在服务端会直接返回，不占用 `TEXT_MAX_INFLIGHT` / `IMAGE_MAX_INFLIGHT`；
+  - **cache miss** 才会进入对应模型 lane；
+  - 因此高频重复图片请求不会再因为严格的图片限流而大量阻塞。
+
 ---
 ## 3. 翻译结果缓存（translation/service.py）
@@ -16,7 +16,7 @@
 - **统一配置**：`config.py`
 - **接口契约**：`protocols.ImageEncoderProtocol`（图片编码统一为 `encode_image_urls(urls, batch_size, normalize_embeddings)`，本地 CN-CLIP 与 clip-as-service 均实现该接口）
-说明：历史上的云端 embedding 试验实现（DashScope）已从主仓库移除，当前仅维护 6005 这条统一向量服务链路。
+说明：历史上的云端 embedding 试验实现（DashScope）已从主仓库移除。当前默认部署为**文本服务 6005** 与**图片服务 6008** 两条链路，也兼容 `all` 模式单进程启动。
 ### 文本向量后端（默认）
@@ -27,6 +27,15 @@
 ### 服务接口
+- 文本服务（默认 `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`（不传则使用服务端默认）
@@ -37,6 +46,28 @@
   - 可选 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 服务生成图片向量。
@@ -63,7 +94,7 @@
 ### 启动服务
-使用仓库脚本启动（默认端口 6005）：
+使用仓库脚本启动：
 ```bash
 # GPU（需 nvidia-container-toolkit）
@@ -72,16 +103,27 @@ TEI_DEVICE=cuda ./scripts/start_tei_service.sh
 # CPU
 TEI_DEVICE=cpu ./scripts/start_tei_service.sh
-./scripts/start_embedding_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`: 服务端口（默认 6005）
+- `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`
-"""Shared cache key helpers for embedding inputs."""
+"""Shared cache key helpers for embedding inputs.
+
+Current canonical raw-key format:
+- text:  ``embed:norm1:<text>`` / ``embed:norm0:<text>``
+- image: ``embed:norm1:<url>``  / ``embed:norm0:<url>``
+
+`RedisEmbeddingCache` adds the configured key prefix and optional namespace on top.
+"""
 from __future__ import annotations
 def build_text_cache_key(text: str, *, normalize: bool) -> str:
     normalized_text = str(text or "").strip()
-    return f"norm:{1 if normalize else 0}:text:{normalized_text}"
+    return f"embed:norm{1 if normalize else 0}:{normalized_text}"
 def build_image_cache_key(url: str, *, normalize: bool) -> str:
     normalized_url = str(url or "").strip()
-    return f"norm:{1 if normalize else 0}:image:{normalized_url}"
+    return f"embed:norm{1 if normalize else 0}:{normalized_url}"
@@ -127,10 +127,10 @@ class CLIPImageEncoder:
             cached = self.cache.get(cache_key)
             if cached is not None:
                 results.append(cached)
-            else:
-                results.append(np.array([], dtype=np.float32))  # placeholder
-                pending_positions.append(pos)
-                pending_urls.append(url)
+                continue
+            results.append(np.array([], dtype=np.float32))  # placeholder
+            pending_positions.append(pos)
+            pending_urls.append(url)
         for i in range(0, len(pending_urls), batch_size):
             batch_urls = pending_urls[i : i + batch_size]
@@ -164,12 +164,14 @@ class TextEmbeddingEncoder:
         normalize_embeddings: bool,
     ) -> Optional[np.ndarray]:
         """Get embedding from cache if exists (with sliding expiration)."""
-        embedding = self.cache.get(build_text_cache_key(query, normalize=normalize_embeddings))
+        cache_key = build_text_cache_key(query, normalize=normalize_embeddings)
+        embedding = self.cache.get(cache_key)
         if embedding is not None:
             logger.debug(
-                "Cache hit for text embedding | normalize=%s query=%s",
+                "Cache hit for text embedding | normalize=%s query=%s key=%s",
                 normalize_embeddings,
                 query,
+                cache_key,
             )
         return embedding
@@ -14,7 +14,8 @@ echo &quot;索引服务调用方排查&quot;
 echo "=========================================="
 INDEXER_PORT="${INDEXER_PORT:-6004}"
-EMBEDDING_PORT="${EMBEDDING_PORT:-6005}"
+EMBEDDING_TEXT_PORT="${EMBEDDING_TEXT_PORT:-${EMBEDDING_PORT:-6005}}"
+EMBEDDING_IMAGE_PORT="${EMBEDDING_IMAGE_PORT:-6008}"
 echo ""
 echo "1. 监听端口 6004 的进程（Indexer 服务）"
@@ -37,10 +38,10 @@ else
 fi
 echo ""
-echo "3. 连接到 6005 的客户端（Indexer 会调用 Embedding 服务）"
+echo "3. 连接到 Embedding 服务的客户端"
 echo "------------------------------------------"
 if command -v ss >/dev/null 2>&1; then
-  ss -tnp 2>/dev/null | grep ":${EMBEDDING_PORT}" || echo "  (当前无活跃连接)"
+  ss -tnp 2>/dev/null | grep -E ":${EMBEDDING_TEXT_PORT}|:${EMBEDDING_IMAGE_PORT}" || echo "  (当前无活跃连接)"
 fi
 echo ""
@@ -63,12 +64,13 @@ echo &quot;    全量: curl -X POST http://localhost:${INDEXER_PORT}/indexer/reindex 
 echo "    增量: curl -X POST http://localhost:${INDEXER_PORT}/indexer/index -d '{\"tenant_id\":\"170\",\"spu_ids\":[\"123\"]}'"
 echo ""
 echo "  - Indexer 内部会调用:"
-echo "    - Embedding 服务 (${EMBEDDING_PORT}): POST /embed/text"
+echo "    - Text Embedding 服务 (${EMBEDDING_TEXT_PORT}): POST /embed/text"
+echo "    - Image Embedding 服务 (${EMBEDDING_IMAGE_PORT}): POST /embed/image"
 echo "    - Qwen API: dashscope.aliyuncs.com (翻译、LLM 分析)"
 echo "    - MySQL: 商品数据"
 echo "    - Elasticsearch: 写入索引"
 echo ""
 echo "6. 实时监控连接（按 Ctrl+C 停止）"
 echo "------------------------------------------"
-echo "  运行: watch -n 2 'ss -tnp | grep -E \":${INDEXER_PORT}|:${EMBEDDING_PORT}\"'"
+echo "  运行: watch -n 2 'ss -tnp | grep -E \":${INDEXER_PORT}|:${EMBEDDING_TEXT_PORT}|:${EMBEDDING_IMAGE_PORT}\"'"
 echo ""
@@ -2,7 +2,7 @@
 from .db_connector import create_db_connection, get_connection_from_config, test_connection
 from .es_client import ESClient, get_es_client_from_env
-from .cache import EmbeddingCache, DictCache
+from .cache import DictCache
 __all__ = [
     'create_db_connection',
@@ -10,6 +10,5 @@ __all__ = [
     'test_connection',
     'ESClient',
     'get_es_client_from_env',
-    'EmbeddingCache',
     'DictCache',
 ]
-"""
-Cache utility for storing embedding results.
-"""
+"""Small file-backed cache helpers."""
 import json
-import hashlib
-import pickle
 from pathlib import Path
 from typing import Any, Optional
-import numpy as np
-
-
-class EmbeddingCache:
-    """
-    Simple file-based cache for embeddings.
-
-    Uses MD5 hash of input text/URL as cache key.
-    """
-
-    def __init__(self, cache_dir: str = ".cache/embeddings"):
-        self.cache_dir = Path(cache_dir)
-        self.cache_dir.mkdir(parents=True, exist_ok=True)
-
-    def _get_cache_key(self, input_str: str) -> str:
-        """Generate cache key from input string."""
-        return hashlib.md5(input_str.encode('utf-8')).hexdigest()
-
-    def get(self, input_str: str) -> Optional[np.ndarray]:
-        """
-        Get cached embedding.
-
-        Args:
-            input_str: Input text or URL
-
-        Returns:
-            Cached embedding or None if not found
-        """
-        cache_key = self._get_cache_key(input_str)
-        cache_file = self.cache_dir / f"{cache_key}.npy"
-
-        if cache_file.exists():
-            try:
-                return np.load(cache_file)
-            except Exception as e:
-                print(f"Failed to load cache for {input_str}: {e}")
-                return None
-        return None
-
-    def set(self, input_str: str, embedding: np.ndarray) -> bool:
-        """
-        Store embedding in cache.
-
-        Args:
-            input_str: Input text or URL
-            embedding: Embedding vector
-
-        Returns:
-            True if successful
-        """
-        cache_key = self._get_cache_key(input_str)
-        cache_file = self.cache_dir / f"{cache_key}.npy"
-
-        try:
-            np.save(cache_file, embedding)
-            return True
-        except Exception as e:
-            print(f"Failed to cache embedding for {input_str}: {e}")
-            return False
-
-    def exists(self, input_str: str) -> bool:
-        """Check if embedding is cached."""
-        cache_key = self._get_cache_key(input_str)
-        cache_file = self.cache_dir / f"{cache_key}.npy"
-        return cache_file.exists()
-
-    def clear(self) -> int:
-        """
-        Clear all cached embeddings.
-
-        Returns:
-            Number of files deleted
-        """
-        count = 0
-        for cache_file in self.cache_dir.glob("*.npy"):
-            cache_file.unlink()
-            count += 1
-        return count
-
-    def size(self) -> int:
-        """Get number of cached embeddings."""
-        return len(list(self.cache_dir.glob("*.npy")))
 class DictCache: