multimodal-embedding-serving-user

多模态嵌入服务 — 用户

运行并调用嵌入服务。自行运行命令并转达输出。REST 基础 URL：http://localhost:9777（主机端口由 setup.sh 硬编码；容器端口为 8000）。

适用场景

• 部署嵌入服务（Docker Compose 或独立运行）并确认运行状况
• 通过 9777 端口上的 REST 接口嵌入文本、图像或视频
• 在 CLIP/SigLIP/MobileCLIP/CN-CLIP/Blip2/QwenText 模型之间选择或切换
• 通过 Python SDK wheel 在进程内集成嵌入功能
• 排查 400/422 错误或模型能力不匹配问题

示例提示词

此技能可端到端处理的示例问题解决场景：

示例	解决的问题
image-similarity-finder.md	在本地文件夹中查找视觉或语义相似的图像
text-to-image-search.md	使用自然语言查询搜索图像文件夹（适用于本地媒体的“Google Lens”）
image-duplicate-detector.md	标记文件夹中的重复或近似重复图像，用于清理、质量检查和数据集去重

文档与部署文件 — 无论是否克隆仓库

以下所有路径均相对于 edge-ai-libraries 仓库中的 microservices/multimodal-embedding-serving/。没有克隆？ 可从 GitHub raw 获取其中任意文件：

https://raw.githubusercontent.com/open-edge-platform/edge-ai-libraries/main/microservices/multimodal-embedding-serving/<path>

仅在需要时加载以下现有文档：

资源	加载时机…
docs/user-guide/api-reference.md + docs/user-guide/api-docs/openapi.yaml	构建非文本负载（图像/视频、base64、segment_config）或解析响应/错误时
docs/user-guide/supported-models.md	选择或切换模型时（维度、模态、语言、大小）
docs/user-guide/sdk-usage.md + docs/user-guide/wheel-installation.md	通过 Python SDK wheel 在进程内集成时
docs/user-guide/get-started.md	需要更多 curl 示例和环境变量表时
setup.sh、docker/compose.yaml	使用下文中的部署文件时

1. 上下文路由 — 克隆仓库还是独立运行？REST 还是 SDK？

• 需要在 Python 进程内集成（无需单独的服务端）：该服务也可用作 SDK — 使用 poetry build 构建 wheel（需要仓库），并使用 get_model_handler(...) + EmbeddingModel；请参阅 docs/user-guide/sdk-usage.md。经验法则：默认使用 REST；当 Python 进程需要大量嵌入，且每项都进行一次 HTTP 跳转会成为主要开销时，选择 SDK。注意：MobileCLIP/Blip2 附加组件仅存在于 Docker 镜像中，且该 wheel 不在 PyPI 上。
• 否则，检测是否已克隆仓库：

  [ -f setup.sh ] && grep -q 'name = "multimodal-embedding-serving"' pyproject.toml 2>/dev/null \
    && echo REPO || echo STANDALONE
  

  REPO → 从微服务根目录执行步骤 2。STANDALONE → 获取两个部署文件，然后执行完全相同的步骤 2：

  RAW=https://raw.githubusercontent.com/open-edge-platform/edge-ai-libraries/main/microservices/multimodal-embedding-serving
  mkdir -p embedding-serving/docker && cd embedding-serving
  curl -fsSL $RAW/setup.sh -o setup.sh
  curl -fsSL $RAW/docker/compose.yaml -o docker/compose.yaml
  

  如果已在运行（curl -sf localhost:9777/health）→ 执行步骤 3。

2. 启动（两种上下文完全相同）

1. 选择模型 — 默认使用 CLIP/clip-vit-b-32（512 维，支持文本、图像和视频）。 权衡取舍：docs/user-guide/supported-models.md。
2. 必须通过 source 执行 setup.sh；如果未设置 EMBEDDING_MODEL_NAME，脚本会立即失败。REGISTRY_URL=intel 用于选择预构建镜像；--no-build 可阻止从源代码构建。在后台运行 — 首次启动时会下载模型：

   bash -c 'export EMBEDDING_MODEL_NAME="CLIP/clip-vit-b-32" REGISTRY_URL=intel TAG=latest \
     && source setup.sh && docker compose -f docker/compose.yaml up -d --no-build'
   

   Intel GPU：还需执行 export EMBEDDING_DEVICE=GPU（随后 setup.sh 会自动启用 OpenVINO + THROUGHPUT 模式）。
3. 等待就绪：

   until curl -sf http://localhost:9777/health; do sleep 5; done
   

3. 能力检查（处理非文本输入前必须执行）

curl -s http://localhost:9777/model/capabilities

QwenText 模型仅支持文本 — 图像/视频请求会返回 400。GET /model/current 会显示请求中应使用的准确已加载模型 ID。

4. 嵌入

文本（单个字符串或字符串列表）：

curl -s http://localhost:9777/embeddings -H 'Content-Type: application/json' -d '{
  "model": "CLIP/clip-vit-b-32",
  "input": {"type": "text", "text": "a red truck at a loading dock"},
  "encoding_format": "float"
}'

响应：{"embedding": [...]} —— 文本/图像会返回一个一维向量；视频输入会返回按帧排列的向量列表。

• model 必须与已加载的模型一致（否则返回 400）。
• 图像：{"type":"image_url","image_url":"https://…"}（纯字符串，不是嵌套对象）或 image_base64。视频：使用 video_url/video_base64/video_frames，并配合 segment_config（num_frames 默认值为 64、extraction_fps、frame_indexes）——完整格式和示例见： docs/user-guide/api-reference.md。

5. 停止 / 清理

• docker compose -f docker/compose.yaml down
• 卷 ov-models（模型缓存）和 data-prep 会保留；移除它们将强制重新下载——请先与用户确认。

故障排查

症状	可能原因 → 操作
source setup.sh 打印 ERROR 并停止	未导出 EMBEDDING_MODEL_NAME → 先导出该变量
9777 端口无响应	仍在启动/下载 → 执行 docker logs -f multimodal-embedding-serving
400“模型不匹配”	请求中的 model ≠ 已加载的模型 → 执行 GET /model/current
图像/视频请求返回 400“不支持的模态”	使用了仅支持文本的模型（QwenText）→ 切换模型或发送文本
首次非文本请求较慢	OpenVINO 延迟转换/编译 → 仅首次出现，属正常情况
/embeddings 返回 422	input 联合类型格式错误 → 检查 docs/user-guide/api-reference.md 中的格式
9777 端口占用	停止冲突的服务（EMBEDDING_SERVER_PORT 在 setup.sh 中硬编码）