## 基于 `clip-server` 的向量服务（平级替代 `embeddings`）
  
  本模块说明如何在 **独立环境** 中部署基于 `jina-ai/clip-as-service` 仓库的向量服务（实际安装包为 `clip-server` / `clip-client`），用于替代当前仓库里的本地 `embeddings` 服务（`embeddings/server.py`）。
  
  > 设计目标：  
  > - 与项目主环境（`searchengine` conda env）**完全隔离**  
  > - 使用官方开源项目 [`jina-ai/clip-as-service`](https://github.com/jina-ai/clip-as-service)（对应 PyPI 包：`clip-server` / `clip-client`）  
  > - 提供简单的 **安装 / 启动 / 停止脚本**  
  
  ---
  
  ## 1. 环境准备（独立环境）
  
  推荐使用 Conda 新建一个专用环境（与本项目的 `searchengine` 环境隔离）：
  
  ```bash

  # 1）加载 conda（你的 conda 是 ~/anaconda3/bin/conda → CONDA_ROOT=~/anaconda3）
  export CONDA_ROOT=${CONDA_ROOT:-$HOME/anaconda3}   # 或你的 Conda 安装路径
  source "$CONDA_ROOT/etc/profile.d/conda.sh"

  
  # 2）创建 clip 向量服务专用环境
  conda create -n clip_service python=3.9 -y
  
  # 3）激活环境
  conda activate clip_service
  
  # 4）安装 clip-server / clip-client（其内部依赖 jina）
  #    如需绕过镜像问题，可显式使用官方 PyPI 源：
  #    pip install -i https://pypi.org/simple "clip-server" "clip-client"
  pip install "clip-server" "clip-client"
  ```
  
  > 如果你不使用 Conda，也可以改用 `python -m venv` 创建虚拟环境，  
  > 但务必保证 **不要与主项目共用同一个 Python 环境**。
  
  ---
  
  ## 2. 启动 / 停止脚本
  
  本仓库在 `scripts/` 目录下提供了两个脚本（需要手动赋权一次）：
  
  ```bash
  chmod +x scripts/start_clip_service.sh
  chmod +x scripts/stop_clip_service.sh
  ```
  
  ### 2.1 启动服务
  
  ```bash

  cd /data/saas-search

  ./scripts/start_clip_service.sh
  ```
  
  脚本行为：
  

  - 自动 `cd` 到仓库根目录
  - 尝试加载 `$CONDA_ROOT/etc/profile.d/conda.sh` 并激活 `clip_service` 环境（可通过 `export CONDA_ROOT=...` 适配新机器）

  - 使用 `nohup python -m clip_server` 启动服务到后台
  - 将日志写入 `logs/clip_service.log`
  - 将进程号写入 `logs/clip_service.pid`
  
  默认情况下，`clip-server` 会监听在 **`grpc://0.0.0.0:51000`**（gRPC 协议，端口 51000）。
  
  > ⚠️ **重要**：客户端连接时请使用端口 **51000**，不是 23456 或其他端口。
  
  ### 2.2 停止服务
  
  ```bash

  cd /data/saas-search

  ./scripts/stop_clip_service.sh
  ```
  
  脚本行为：
  
  - 读取 `logs/clip_service.pid` 中的 PID
  - 如果进程存在则发送 `kill` 终止
  - 清理 `logs/clip_service.pid`
  
  ---
  
  ## 3. 与现有 `embeddings` 服务的关系
  
  - 现有本地向量服务：  
    - 启动脚本：`./scripts/start_embedding_service.sh`  
    - 实现：`embeddings/server.py`（FastAPI + 本地模型 `bge_model.py` / `clip_model.py`）  
  - 新增的 `clip-server`：  
    - 使用官方实现，单独进程、单独环境  
    - 面向图像 / 文本的 CLIP 向量化服务  
  
  ### 使用建议
  
  - 如果你想继续使用本仓库自带的本地模型服务，保持原有脚本不变即可：  
    - `./scripts/start_embedding_service.sh`
  - 如果你想用 `clip-as-service` 替代原来的本地服务，可以：
    - 在上游调用代码中，将向量请求切换到 `clip-as-service` 对应的端口 / 接口
    - 或者增加一个适配层，将 `clip-as-service` 封装成与 `POST /embed/text` / `POST /embed/image` 相同的接口（视具体场景而定）
  
  ---
  
  ## 4. 基本验证
  
  1. 确认 `clip_service` 环境创建并安装成功：
  
     ```bash

     export CONDA_ROOT=${CONDA_ROOT:-$HOME/anaconda3}
     source "$CONDA_ROOT/etc/profile.d/conda.sh"

     conda activate clip_service
     python -c "import jina; print('jina version:', jina.__version__)"
     ```
  
  2. 启动服务并查看日志：
  
     ```bash

     cd /data/saas-search

     ./scripts/start_clip_service.sh
     tail -f logs/clip_service.log
     ```
  
     服务启动后，默认监听在 **`grpc://0.0.0.0:51000`**（gRPC 协议，端口 51000）。
  
  3. 测试客户端连接（在 `clip_service` 环境中）：
  
     ```python
     from clip_client import Client
     
     # 注意：默认端口是 51000，不是 23456
     c = Client('grpc://0.0.0.0:51000')
     
     # 测试连接
     c.profile()
     
     # 测试文本向量化
     r = c.encode(['First do it', 'then do it right', 'then do it better'])
     print(r.shape)  # 应该输出 [3, 512] 或类似形状
     
     # 测试图像向量化
     r = c.encode(['https://picsum.photos/200'])
     print(r.shape)  # 应该输出 [1, 512] 或类似形状
     ```
  
  4. 如果不再需要服务，执行：
  
     ```bash
     ./scripts/stop_clip_service.sh
     ```
  
  ### 常见问题
  
  **Q: 连接被拒绝（Connection refused）？**  
  A: 请确认：
  - 服务已启动（检查 `logs/clip_service.log` 和进程）
  - 客户端使用的端口是 **51000**（不是 23456）
  - 客户端地址格式正确：`grpc://0.0.0.0:51000` 或 `grpc://localhost:51000`
  
  **Q: Gateway 启动了但 worker 连接失败？**  
  A: 可能原因：
  - Worker 进程（clip_t）还在启动中，模型加载需要时间（首次启动可能需要下载模型）
  - 检查日志中是否有模型下载或加载错误：
    ```bash
    tail -f logs/clip_service.log | grep -E "(ERROR|WARNING|model|download)"
    ```
  - 如果持续失败，尝试重启服务：
    ```bash
    ./scripts/stop_clip_service.sh
    ./scripts/start_clip_service.sh
    ```
  
  **Q: 如何查看服务实际监听的端口？**  
  A: 查看启动日志：
  ```bash
  tail -f logs/clip_service.log | grep "bound to"
  ```
  或检查进程监听的端口：
  ```bash
  lsof -i :51000
  # 或
  netstat -tlnp | grep 51000
  ```
  
  **Q: 如何确认服务完全就绪？**  
  A: 查看日志，确认看到类似输出：
  ```
  INFO   gateway/rep-0@XXXXX start server bound to 0.0.0.0:51000
  ```
  然后等待几秒让 worker 进程启动，再测试客户端连接。
  
  ---
  
  ## 5. 参考
  
  - 项目地址：`https://github.com/jina-ai/clip-as-service`
  - 本项目向量模块文档：`embeddings/README.md`、`CLOUD_EMBEDDING_README.md`