# Embeddings 模块

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

---

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

- **HTTP 客户端**：`text_encoder.py` / `image_encoder.py`（供搜索/索引模块调用）
- **本地模型实现**：`bge_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 均实现该接口）

### 服务接口

- `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**（首次使用）：
   ```bash
   pip install -e third-party/clip-as-service/client
   ```

2. **启动 CN-CLIP 服务**（独立 gRPC 服务，默认端口 51000，详见 `docs/CNCLIP_SERVICE说明文档.md`）：
   ```bash
   ./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）：

```bash
./scripts/start_embedding_service.sh
```

### 修改配置

编辑 `embeddings/config.py`：

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