# Provider 架构与扩展指南

本文档说明如何统一管理翻译、向量化、重排等“能力提供者（provider）”。

## 1. 设计目标

- **调用方稳定**：业务代码不关心具体供应商，只调用统一接口。
- **配置可切换**：通过配置切换 provider，不改业务代码。
- **单一配置源**：所有 provider 配置在 `config/config.yaml` 的 `services` 块。

## 2. 当前落地状态

### 2.1 统一入口

- **模块**：`providers/`
- **工厂**：`create_translation_provider()`, `create_rerank_provider()`, `create_embedding_provider()`
- **配置**：`config/services_config.py` 从 `services` 块加载，env 可覆盖

### 2.2 翻译

- `providers/translation.py`：`direct`（进程内 Translator）、`http`（HTTP 服务）
- 调用方：`query/query_parser.py`, `indexer/indexing_utils.py`

### 2.3 重排

- `providers/rerank.py`：`http`（vllm 预留）
- 调用方：`search/rerank_client.py` → `run_rerank()`

### 2.4 向量化

- `providers/embedding.py`：`http`（vllm 预留）
- 封装 `BgeEncoder` / `CLIPImageEncoder`，URL 来自 `services_config`

## 3. 配置

**单一配置源**：`config/config.yaml` 的 `services` 块。

```yaml
services:
  translation:
    provider: "direct"  # direct | http
    providers:
      direct: { model: "qwen" }
      http: { base_url: "http://127.0.0.1:6006", model: "qwen", timeout_sec: 10.0 }
  embedding:
    provider: "http"
    providers:
      http: { base_url: "http://127.0.0.1:6005" }
  rerank:
    provider: "http"
    providers:
      http: { base_url: "http://127.0.0.1:6007" }
```

**环境变量**（部署态覆盖）：`TRANSLATION_PROVIDER`, `TRANSLATION_SERVICE_URL`, `EMBEDDING_SERVICE_URL`, `RERANKER_SERVICE_URL`

## 4. 新增 provider

1. 在 `providers/<capability>.py` 中实现新 provider 类
2. 在 `create_*_provider()` 中注册分支
3. 在 `config/config.yaml` 的 `services.<capability>.providers` 中补充参数