ai-saas / saas-search

CLIP_SERVICE_README.md 5.89 KB

基于 clip-server 的向量服务（平级替代 embeddings）

本模块说明如何在 独立环境 中部署基于 jina-ai/clip-as-service 仓库的向量服务（实际安装包为 clip-server / clip-client），用于替代当前仓库里的本地 embeddings 服务（embeddings/server.py）。

设计目标：

  • 与项目主环境（searchengine conda env）完全隔离
  • 使用官方开源项目 <code>jina-ai/clip-as-service</code>（对应 PyPI 包：clip-server / clip-client）
  • 提供简单的 安装 / 启动 / 停止脚本

1. 环境准备（独立环境）

推荐使用 Conda 新建一个专用环境（与本项目的 searchengine 环境隔离）：

# 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/ 目录下提供了两个脚本（需要手动赋权一次）：

chmod +x scripts/start_clip_service.sh
chmod +x scripts/stop_clip_service.sh

2.1 启动服务

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 停止服务

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 + 本地模型 qwen3_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 环境创建并安装成功：
   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__)"
  1. 启动服务并查看日志：
   cd /data/saas-search
   ./scripts/start_clip_service.sh
   tail -f logs/clip_service.log

服务启动后，默认监听在 grpc://0.0.0.0:51000（gRPC 协议，端口 51000）。

  1. 测试客户端连接（在 clip_service 环境中）：
   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] 或类似形状
  1. 如果不再需要服务，执行：
   ./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: 查看启动日志：

tail -f logs/clip_service.log | grep "bound to"

或检查进程监听的端口：

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