重构:添加模型服务模块,支持嵌入和重排服务的自动降级

新增功能:
- 创建 app/model_services 模块,提供统一的模型服务获取接口
- 实现 BaseServiceProvider 基类和 FallbackServiceChain 降级链
- 实现 get_embedding_service():优先本地 llama.cpp,降级到智谱 API
- 实现 get_rerank_service():优先本地 llama.cpp,降级到智谱 API
- 支持单例管理,确保全局只有一个服务实例

修改内容:
- 更新 app/config.py,添加智谱 API 相关配置
- 修改 rag_core/vector_store.py:支持接受外部传入的 embeddings
- 修改 rag_core/retriever_factory.py:支持接受外部传入的 embeddings
- 修改 app/agent/rag_initializer.py:使用 get_embedding_service()
- 修改 app/rag/pipeline.py:使用 get_rerank_service()
- 修改 app/memory/mem0_client.py:智能判断可用服务配置 mem0
- 修改 rag_indexer/index_builder.py:支持使用新服务,保持向后兼容
- 修改 rag_indexer/config.py:添加智谱配置

环境变量:
- ZHIPUAI_API_KEY:智谱 API 密钥(必选)
- ZHIPU_EMBEDDING_MODEL:可选,默认 embedding-3
- ZHIPU_RERANK_MODEL:可选,默认 rerank-2
- ZHIPU_API_BASE:可选,默认 https://open.bigmodel.cn/api/paas/v4
This commit is contained in:
2026-04-24 22:52:36 +08:00
parent 4722e2646a
commit 8db63e7a8d
13 changed files with 794 additions and 58 deletions

View File

@@ -0,0 +1,31 @@
"""
模型服务模块model_services
提供统一的嵌入和重排模型服务获取接口,支持自动降级:
1. 优先使用本地 llama.cpp 服务
2. 本地服务不可用时,自动降级到智谱 API 服务
使用方法:
from app.model_services import get_embedding_service, get_rerank_service, BaseReranker
# 获取嵌入服务LangChain 兼容的 Embeddings
embeddings = get_embedding_service()
# 获取重排服务
reranker = get_rerank_service()
sorted_docs = reranker.compress_documents(documents, query, top_n=5)
环境变量配置:
# 智谱 API 配置
ZHIPUAI_API_KEY=your_api_key
ZHIPU_EMBEDDING_MODEL=embedding-3 # 可选embedding-2、embedding-3
ZHIPU_RERANK_MODEL=rerank-2 # 可选rerank-1、rerank-2
ZHIPU_API_BASE=https://open.bigmodel.cn/api/paas/v4
# 本地 llama.cpp 服务配置(原有配置保持不变)
LLAMACPP_EMBEDDING_URL=http://localhost:port/v1
LLAMACPP_RERANKER_URL=http://localhost:port/v1
LLAMACPP_API_KEY=your_api_key
"""

View File

@@ -0,0 +1,14 @@
"""
模型服务模块
提供统一的嵌入和重排模型服务获取接口,支持自动降级。
"""
from .embedding_services import get_embedding_service
from .rerank_services import get_rerank_service, BaseReranker
__all__ = [
"get_embedding_service",
"get_rerank_service",
"BaseReranker"
]

View File

@@ -0,0 +1,139 @@
"""
模型服务获取器基类和自动降级机制模块
本模块提供:
1. 统一的服务获取器基类,支持服务可用性检查和自动降级
2. 单例模式的服务管理器,确保全局只有一个服务实例
3. 支持链式降级策略,主服务失败时自动尝试备用服务
主要功能:
- BaseServiceProvider所有服务获取器的基类
- FallbackServiceChain链式降级处理器
- SingletonServiceManager单例服务管理器
"""
import abc
from typing import Generic, TypeVar, List, Optional, Any, Callable
from functools import wraps
import logging
logger = logging.getLogger(__name__)
T = TypeVar('T')
class BaseServiceProvider(abc.ABC, Generic[T]):
"""
服务获取器基类,所有具体服务获取器都需要继承此类
"""
def __init__(self, name: str):
self._name = name
self._service_instance: Optional[T] = None
@abc.abstractmethod
def is_available(self) -> bool:
"""
检查服务是否可用
Returns:
bool: 服务是否可用
"""
pass
@abc.abstractmethod
def get_service(self) -> T:
"""
获取服务实例
Returns:
T: 服务实例
"""
pass
@property
def name(self) -> str:
"""获取服务名称"""
return self._name
class FallbackServiceChain(Generic[T]):
"""
链式降级处理器,支持多级备用服务
"""
def __init__(self, primary: BaseServiceProvider[T], fallbacks: List[BaseServiceProvider[T]]):
self._primary = primary
self._fallbacks = fallbacks
self._providers = [primary] + fallbacks
def get_available_service(self) -> T:
"""
获取第一个可用的服务
Returns:
T: 可用的服务实例
Raises:
RuntimeError: 如果没有可用的服务
"""
for provider in self._providers:
try:
if provider.is_available():
logger.info(f"使用服务: {provider.name}")
return provider.get_service()
else:
logger.warning(f"服务不可用: {provider.name},尝试下一个...")
except Exception as e:
logger.warning(f"服务 {provider.name} 检查失败: {e},尝试下一个...")
raise RuntimeError(f"没有可用的服务,尝试了: {[p.name for p in self._providers]}")
def get_all_providers(self) -> List[BaseServiceProvider[T]]:
"""
获取所有服务提供者(主服务 + 备用服务)
Returns:
List[BaseServiceProvider[T]]: 服务提供者列表
"""
return self._providers.copy()
class SingletonServiceManager:
"""
单例服务管理器,确保全局只有一个服务实例
"""
_instances: dict = {}
@classmethod
def get_or_create(cls, key: str, creator: Callable[[], Any]) -> Any:
"""
获取或创建单例实例
Args:
key: 单例键
creator: 创建函数
Returns:
Any: 单例实例
"""
if key not in cls._instances:
cls._instances[key] = creator()
logger.debug(f"创建单例实例: {key}")
return cls._instances[key]
@classmethod
def clear(cls, key: Optional[str] = None):
"""
清除单例实例
Args:
key: 单例键,如果为 None 则清除所有
"""
if key is None:
cls._instances.clear()
logger.debug("清除所有单例实例")
elif key in cls._instances:
del cls._instances[key]
logger.debug(f"清除单例实例: {key}")

View File

@@ -0,0 +1,213 @@
"""
嵌入模型服务模块
本模块提供统一的嵌入模型服务获取接口,支持自动降级:
1. 优先使用本地 llama.cpp 嵌入服务
2. 本地服务不可用时,自动降级到智谱 API 嵌入服务
主要功能:
- LocalLlamaCppEmbeddingProvider本地 llama.cpp 嵌入服务提供者
- ZhipuEmbeddingProvider智谱 API 嵌入服务提供者
- get_embedding_service():获取嵌入服务的统一接口
"""
import logging
from typing import List
import httpx
from langchain_core.embeddings import Embeddings
from .base import (
BaseServiceProvider,
FallbackServiceChain,
SingletonServiceManager
)
from ..config import (
LLAMACPP_EMBEDDING_URL,
LLAMACPP_API_KEY,
ZHIPUAI_API_KEY,
ZHIPU_EMBEDDING_MODEL,
ZHIPU_API_BASE
)
logger = logging.getLogger(__name__)
class LocalLlamaCppEmbeddingProvider(BaseServiceProvider[Embeddings]):
"""
本地 llama.cpp 嵌入服务提供者
"""
def __init__(self, model: str = "Qwen3-Embedding-0.6B-Q8_0"):
super().__init__("local_llamacpp_embedding")
self._model = model
def is_available(self) -> bool:
"""
检查本地 llama.cpp 嵌入服务是否可用
Returns:
bool: 服务是否可用
"""
if not LLAMACPP_EMBEDDING_URL:
logger.warning("LLAMACPP_EMBEDDING_URL 未配置")
return False
try:
# 尝试嵌入一个测试字符串
embedder = LocalLlamaCppEmbedder(model=self._model)
test_embedding = embedder.embed_query("test")
logger.info(f"本地 llama.cpp 嵌入服务可用,维度: {len(test_embedding)}")
return True
except Exception as e:
logger.warning(f"本地 llama.cpp 嵌入服务不可用: {e}")
return False
def get_service(self) -> Embeddings:
"""
获取本地 llama.cpp 嵌入服务
Returns:
Embeddings: LangChain 兼容的嵌入实例
"""
if self._service_instance is None:
embedder = LocalLlamaCppEmbedder(model=self._model)
self._service_instance = embedder.as_langchain_embeddings()
return self._service_instance
class ZhipuEmbeddingProvider(BaseServiceProvider[Embeddings]):
"""
智谱 API 嵌入服务提供者
"""
def __init__(self, model: str | None = None):
super().__init__("zhipu_embedding")
self._model = model or ZHIPU_EMBEDDING_MODEL
def is_available(self) -> bool:
"""
检查智谱 API 嵌入服务是否可用
Returns:
bool: 服务是否可用
"""
if not ZHIPUAI_API_KEY:
logger.warning("ZHIPUAI_API_KEY 未配置")
return False
try:
# 测试智谱 API 是否可用
from zhipuai import ZhipuAI
client = ZhipuAI(api_key=ZHIPUAI_API_KEY)
response = client.embeddings.create(
model=self._model,
input=["test"]
)
logger.info(f"智谱嵌入服务可用,维度: {len(response.data[0].embedding)}")
return True
except ImportError:
logger.warning("zhipuai 库未安装")
return False
except Exception as e:
logger.warning(f"智谱嵌入服务不可用: {e}")
return False
def get_service(self) -> Embeddings:
"""
获取智谱 API 嵌入服务
Returns:
Embeddings: LangChain 兼容的嵌入实例
"""
if self._service_instance is None:
from langchain_zhipu import ZhipuAIEmbeddings
self._service_instance = ZhipuAIEmbeddings(
model=self._model,
api_key=ZHIPUAI_API_KEY
)
return self._service_instance
class LocalLlamaCppEmbedder:
"""
通过 OpenAI 兼容 API 封装 llama.cpp 嵌入服务
"""
def __init__(self, model: str = "Qwen3-Embedding-0.6B-Q8_0"):
self.base_url = LLAMACPP_EMBEDDING_URL
self.api_key = LLAMACPP_API_KEY
self.model = model
def as_langchain_embeddings(self) -> Embeddings:
"""创建 LangChain 兼容的嵌入实例"""
return _LlamaCppLangchainAdapter(self)
def embed_documents(self, texts: List[str]) -> List[List[float]]:
"""嵌入一批文档"""
return self._call_embedding_api(texts)
def embed_query(self, text: str) -> List[float]:
"""嵌入单个查询"""
return self._call_embedding_api([text])[0]
def _call_embedding_api(self, texts: List[str]) -> List[List[float]]:
"""直接调用 llama.cpp 嵌入 API"""
headers = {"Content-Type": "application/json"}
if self.api_key:
headers["Authorization"] = f"Bearer {self.api_key}"
base = self.base_url.rstrip("/")
if not base.endswith("/v1"):
base = base + "/v1"
payload = {
"input": texts,
"model": self.model,
}
with httpx.Client(timeout=120) as client:
response = client.post(
f"{base}/embeddings",
headers=headers,
json=payload,
)
response.raise_for_status()
data = response.json()
if isinstance(data, list):
return [item["embedding"] for item in data]
elif isinstance(data, dict) and "data" in data:
return [item["embedding"] for item in sorted(data["data"], key=lambda x: x["index"])]
else:
raise ValueError(f"未知的嵌入 API 响应格式: {data}")
class _LlamaCppLangchainAdapter(Embeddings):
"""
将 LlamaCppEmbedder 适配为 LangChain Embeddings 接口
"""
def __init__(self, embedder: "LocalLlamaCppEmbedder"):
self._embedder = embedder
def embed_documents(self, texts: List[str]) -> List[List[float]]:
return self._embedder.embed_documents(texts)
def embed_query(self, text: str) -> List[float]:
return self._embedder.embed_query(text)
def get_embedding_service() -> Embeddings:
"""
获取嵌入服务(带自动降级)
Returns:
Embeddings: LangChain 兼容的嵌入实例
"""
def _create_chain():
primary = LocalLlamaCppEmbeddingProvider()
fallback = ZhipuEmbeddingProvider()
return FallbackServiceChain(primary, [fallback])
chain = SingletonServiceManager.get_or_create("embedding_service_chain", _create_chain)
return chain.get_available_service()

View File

@@ -0,0 +1,233 @@
"""
重排模型服务模块
本模块提供统一的重排模型服务获取接口,支持自动降级:
1. 优先使用本地 llama.cpp 重排服务
2. 本地服务不可用时,自动降级到智谱 API 重排服务
主要功能:
- LocalLlamaCppRerankProvider本地 llama.cpp 重排服务提供者
- ZhipuRerankProvider智谱 API 重排服务提供者
- get_rerank_service():获取重排服务的统一接口
"""
import logging
from typing import List
import requests
from langchain_core.documents import Document
from .base import (
BaseServiceProvider,
FallbackServiceChain,
SingletonServiceManager
)
from ..config import (
LLAMACPP_RERANKER_URL,
LLAMACPP_API_KEY,
ZHIPUAI_API_KEY,
ZHIPU_RERANK_MODEL,
ZHIPU_API_BASE
)
logger = logging.getLogger(__name__)
class BaseReranker:
"""
重排器基类,定义统一的接口
"""
def compress_documents(self, documents: List[Document], query: str, top_n: int = 5) -> List[Document]:
"""
对文档进行重排序
Args:
documents: 待排序的文档列表
query: 查询字符串
top_n: 返回前 N 个结果
Returns:
排序后的文档列表
"""
raise NotImplementedError
class LocalLlamaCppReranker(BaseReranker):
"""
使用远程 llama.cpp 服务对检索结果重排序
"""
def __init__(self, base_url: str, api_key: str, model: str = "bge-reranker-v2-m3", timeout: int = 60):
self.base_url = base_url
self.api_key = api_key
self.model = model
self.timeout = timeout
self.endpoint = f"{self.base_url}/rerank"
def compress_documents(self, documents: List[Document], query: str, top_n: int = 5) -> List[Document]:
"""
对文档进行重排序
"""
if not documents:
return []
# 准备请求体
payload = {
"model": self.model,
"query": query,
"documents": [doc.page_content for doc in documents],
"top_n": top_n
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {self.api_key}"
}
try:
response = requests.post(self.endpoint, json=payload, headers=headers, timeout=self.timeout)
response.raise_for_status()
results = response.json()
# 解析返回结果
sorted_indices = [item["index"] for item in results["results"]]
sorted_docs = [documents[idx] for idx in sorted_indices]
return sorted_docs
except Exception as e:
logger.warning(f"远程重排序过程出错,返回原始前 {top_n} 个结果: {e}")
return documents[:top_n]
class ZhipuReranker(BaseReranker):
"""
使用智谱 API 对检索结果重排序
"""
def __init__(self, model: str | None = None):
self.model = model or ZHIPU_RERANK_MODEL
self.api_key = ZHIPUAI_API_KEY
def compress_documents(self, documents: List[Document], query: str, top_n: int = 5) -> List[Document]:
"""
对文档进行重排序
"""
if not documents:
return []
try:
from zhipuai import ZhipuAI
client = ZhipuAI(api_key=self.api_key)
response = client.rerank.create(
model=self.model,
query=query,
documents=[doc.page_content for doc in documents],
top_n=top_n
)
sorted_indices = [item.index for item in response.results]
sorted_docs = [documents[idx] for idx in sorted_indices]
return sorted_docs
except Exception as e:
logger.warning(f"智谱重排序过程出错,返回原始前 {top_n} 个结果: {e}")
return documents[:top_n]
class LocalLlamaCppRerankProvider(BaseServiceProvider[BaseReranker]):
"""
本地 llama.cpp 重排服务提供者
"""
def __init__(self, model: str = "bge-reranker-v2-m3"):
super().__init__("local_llamacpp_rerank")
self._model = model
def is_available(self) -> bool:
"""
检查本地 llama.cpp 重排服务是否可用
"""
if not LLAMACPP_RERANKER_URL:
logger.warning("LLAMACPP_RERANKER_URL 未配置")
return False
try:
# 测试重排服务
test_docs = [Document(page_content="test document 1"), Document(page_content="test document 2")]
reranker = LocalLlamaCppReranker(
base_url=LLAMACPP_RERANKER_URL,
api_key=LLAMACPP_API_KEY,
model=self._model
)
result = reranker.compress_documents(test_docs, "test query", top_n=1)
logger.info(f"本地 llama.cpp 重排服务可用")
return True
except Exception as e:
logger.warning(f"本地 llama.cpp 重排服务不可用: {e}")
return False
def get_service(self) -> BaseReranker:
"""
获取本地 llama.cpp 重排服务
"""
if self._service_instance is None:
self._service_instance = LocalLlamaCppReranker(
base_url=LLAMACPP_RERANKER_URL,
api_key=LLAMACPP_API_KEY,
model=self._model
)
return self._service_instance
class ZhipuRerankProvider(BaseServiceProvider[BaseReranker]):
"""
智谱 API 重排服务提供者
"""
def __init__(self, model: str | None = None):
super().__init__("zhipu_rerank")
self._model = model or ZHIPU_RERANK_MODEL
def is_available(self) -> bool:
"""
检查智谱 API 重排服务是否可用
"""
if not ZHIPUAI_API_KEY:
logger.warning("ZHIPUAI_API_KEY 未配置")
return False
try:
# 测试重排服务
test_docs = [Document(page_content="test document 1"), Document(page_content="test document 2")]
reranker = ZhipuReranker(model=self._model)
result = reranker.compress_documents(test_docs, "test query", top_n=1)
logger.info(f"智谱重排服务可用")
return True
except ImportError:
logger.warning("zhipuai 库未安装")
return False
except Exception as e:
logger.warning(f"智谱重排服务不可用: {e}")
return False
def get_service(self) -> BaseReranker:
"""
获取智谱 API 重排服务
"""
if self._service_instance is None:
self._service_instance = ZhipuReranker(model=self._model)
return self._service_instance
def get_rerank_service() -> BaseReranker:
"""
获取重排服务(带自动降级)
Returns:
BaseReranker: 重排服务实例
"""
def _create_chain():
primary = LocalLlamaCppRerankProvider()
fallback = ZhipuRerankProvider()
return FallbackServiceChain(primary, [fallback])
chain = SingletonServiceManager.get_or_create("rerank_service_chain", _create_chain)
return chain.get_available_service()