ai-saas / saas-search

Blame view

embeddings/README.md 2.83 KB
Edit Raw Normal View History
42e3aea6   tangwang   tidy 
1
2
3
4
5
 
  # Embeddings 模块
  
  **请求示例**见 `docs/QUICKSTART.md` §3.3。
  
  ---
7bfb9946   tangwang   向量化模块 
6
7
8
9
 
  
  这个目录是一个完整的“向量化模块”，包含：
  
  - **HTTP 客户端**：`text_encoder.py` / `image_encoder.py`（供搜索/索引模块调用）
950a640e   tangwang   embeddings 
10
 
  - **本地模型实现**：`qwen3_model.py` / `clip_model.py`
c10f90fe   tangwang   cnclip 
11
 
  - **clip-as-service 客户端**：`clip_as_service_encoder.py`（图片向量，推荐）
7bfb9946   tangwang   向量化模块 
12
13
 
  - **向量化服务（FastAPI）**：`server.py`
  - **统一配置**：`config.py`
c10f90fe   tangwang   cnclip 
14
 
  - **接口契约**：`protocols.ImageEncoderProtocol`（图片编码统一为 `encode_image_urls(urls, batch_size)`，本地 CN-CLIP 与 clip-as-service 均实现该接口）
7bfb9946   tangwang   向量化模块 
15
950a640e   tangwang   embeddings 
16
17
18
19
 
  说明：历史上的云端 embedding 试验实现（DashScope）已从主仓库移除，当前仅维护 6005 这条统一向量服务链路。
  
  ### 文本向量后端（默认）
07cf5a93   tangwang   START_EMBEDDING=... 
20
21
22
23
 
  - 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`
950a640e   tangwang   embeddings 
24
7bfb9946   tangwang   向量化模块 
25
26
27
28
 
  ### 服务接口
  
  - `POST /embed/text`
    - 入参：`["文本1", "文本2", ...]`
07cf5a93   tangwang   START_EMBEDDING=... 
29
 
    - 出参：`[[...], [...], ...]`（与输入按 index 对齐，失败直接报错）
7bfb9946   tangwang   向量化模块 
30
31
32
 
  
  - `POST /embed/image`
    - 入参：`["url或本地路径1", ...]`
07cf5a93   tangwang   START_EMBEDDING=... 
33
 
    - 出参：`[[...], [...], ...]`（与输入按 index 对齐，失败直接报错）
7bfb9946   tangwang   向量化模块 
34
c10f90fe   tangwang   cnclip 
35
36
37
38
 
  ### 图片向量：clip-as-service（推荐）
  
  默认使用 `third-party/clip-as-service` 的 Jina CLIP 服务生成图片向量。
07cf5a93   tangwang   START_EMBEDDING=... 
39
 
  1. **安装 embedding 专用环境**（首次使用）：
c10f90fe   tangwang   cnclip 
40
 
     ```bash
07cf5a93   tangwang   START_EMBEDDING=... 
41
42
43
44
45
 
     ./scripts/setup_embedding_venv.sh
     ```
     如需使用本地 `local_st` 文本后端，再执行：
     ```bash
     INSTALL_LOCAL_ST=1 ./scripts/setup_embedding_venv.sh
c10f90fe   tangwang   cnclip 
46
47
48
49
50
51
52
53
54
55
56
 
     ```
  
  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`
7bfb9946   tangwang   向量化模块 
57
58
59
60
61
 
  ### 启动服务
  
  使用仓库脚本启动（默认端口 6005）：
  
  ```bash
07cf5a93   tangwang   START_EMBEDDING=... 
62
63
64
65
66
67
 
  # GPU（需 nvidia-container-toolkit）
  TEI_USE_GPU=1 ./scripts/start_tei_service.sh
  
  # CPU
  TEI_USE_GPU=0 ./scripts/start_tei_service.sh
7bfb9946   tangwang   向量化模块 
68
69
70
71
72
73
74
75
 
  ./scripts/start_embedding_service.sh
  ```
  
  ### 修改配置
  
  编辑 `embeddings/config.py`：
  
  - `PORT`: 服务端口（默认 6005）
950a640e   tangwang   embeddings 
76
 
  - `TEXT_MODEL_ID`, `TEXT_DEVICE`, `TEXT_BATCH_SIZE`, `TEXT_NORMALIZE_EMBEDDINGS`
c10f90fe   tangwang   cnclip 
77
78
 
  - `USE_CLIP_AS_SERVICE`, `CLIP_AS_SERVICE_SERVER`：图片向量（clip-as-service）
  - `IMAGE_MODEL_NAME`, `IMAGE_DEVICE`：本地 CN-CLIP（当 `USE_CLIP_AS_SERVICE=false` 时）
07cf5a93   tangwang   START_EMBEDDING=... 
79
 
  - TEI 相关：`TEI_USE_GPU`、`TEI_VERSION`、`TEI_MAX_BATCH_TOKENS`、`TEI_MAX_CLIENT_BATCH_SIZE`、`TEI_HEALTH_TIMEOUT_SEC`