## 基于 `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 + 本地模型 `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` 环境创建并安装成功：

   ```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`