Provider 架构与扩展指南

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

扩展重排/向量化后端（如新增 Qwen3-Reranker、vLLM 等）：请同时参阅 模块扩展规范（MODULE_EXTENSION_SPEC.md），其中定义了服务内后端协议、统一配置结构与可插拔实现方式。

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 块。

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 中补充参数