125 lines
3.7 KiB
Python
125 lines
3.7 KiB
Python
"""
|
||
llm/providers/base_provider.py
|
||
LLM Provider 抽象基类：定义所有 Provider 必须实现的统一接口
|
||
"""
|
||
|
||
from abc import ABC, abstractmethod
|
||
from dataclasses import dataclass, field
|
||
from typing import Any
|
||
|
||
from mcp.mcp_protocol import ChainPlan, ToolSchema
|
||
|
||
|
||
# ════════════════════════════════════════════════════════════════
|
||
# Provider 返回数据结构
|
||
# ════════════════════════════════════════════════════════════════
|
||
|
||
@dataclass
|
||
class PlanResult:
|
||
"""
|
||
工具调用链规划结果
|
||
|
||
Attributes:
|
||
plan: 解析出的 ChainPlan（成功时）
|
||
raw_response: 原始 API 响应（用于调试）
|
||
usage: Token 用量统计
|
||
success: 是否成功
|
||
error: 失败原因
|
||
"""
|
||
plan: ChainPlan | None
|
||
raw_response: Any = None
|
||
usage: dict[str, int] = field(default_factory=dict)
|
||
success: bool = True
|
||
error: str = ""
|
||
|
||
@property
|
||
def prompt_tokens(self) -> int:
|
||
return self.usage.get("prompt_tokens", 0)
|
||
|
||
@property
|
||
def completion_tokens(self) -> int:
|
||
return self.usage.get("completion_tokens", 0)
|
||
|
||
|
||
@dataclass
|
||
class ReplyResult:
|
||
"""
|
||
最终回复生成结果
|
||
|
||
Attributes:
|
||
content: 生成的自然语言回复
|
||
usage: Token 用量统计
|
||
success: 是否成功
|
||
error: 失败原因
|
||
"""
|
||
content: str
|
||
usage: dict[str, int] = field(default_factory=dict)
|
||
success: bool = True
|
||
error: str = ""
|
||
|
||
|
||
# ════════════════════════════════════════════════════════════════
|
||
# 抽象基类
|
||
# ════════════════════════════════════════════════════════════════
|
||
|
||
class BaseProvider(ABC):
|
||
"""
|
||
LLM Provider 抽象基类
|
||
|
||
所有具体 Provider（OpenAI / Anthropic / Ollama）必须继承此类
|
||
并实现以下两个核心方法:
|
||
- plan_with_tools() 工具调用链规划（Function Calling）
|
||
- generate_reply() 最终回复生成
|
||
"""
|
||
|
||
@property
|
||
@abstractmethod
|
||
def provider_name(self) -> str:
|
||
"""Provider 名称标识，如 'openai' / 'anthropic'"""
|
||
...
|
||
|
||
@abstractmethod
|
||
def plan_with_tools(
|
||
self,
|
||
messages: list[dict],
|
||
tool_schemas: list[ToolSchema],
|
||
) -> PlanResult:
|
||
"""
|
||
使用 Function Calling 规划工具调用链
|
||
|
||
Args:
|
||
messages: 对话历史消息列表（OpenAI 格式）
|
||
tool_schemas: 可用工具的 Schema 列表
|
||
|
||
Returns:
|
||
PlanResult 实例
|
||
"""
|
||
...
|
||
|
||
@abstractmethod
|
||
def generate_reply(
|
||
self,
|
||
messages: list[dict],
|
||
) -> ReplyResult:
|
||
"""
|
||
基于完整对话历史（含工具执行结果）生成最终回复
|
||
|
||
Args:
|
||
messages: 包含 tool 角色消息的完整对话历史
|
||
|
||
Returns:
|
||
ReplyResult 实例
|
||
"""
|
||
...
|
||
|
||
def health_check(self) -> bool:
|
||
"""
|
||
连通性检测（可选实现）
|
||
|
||
Returns:
|
||
True 表示 API 可用
|
||
"""
|
||
return True
|
||
|
||
def __repr__(self) -> str:
|
||
return f"{self.__class__.__name__}(provider={self.provider_name})" |