385 lines
14 KiB
Python
385 lines
14 KiB
Python
"""
|
||
llm/providers/openai_provider.py
|
||
OpenAI Provider：使用 Function Calling 实现工具链规划与回复生成
|
||
|
||
核心流程:
|
||
1. plan_with_tools()
|
||
messages + tools → OpenAI API
|
||
→ 解析 tool_calls → ChainPlan
|
||
|
||
2. generate_reply()
|
||
messages（含 tool 结果）→ OpenAI API
|
||
→ 最终自然语言回复
|
||
|
||
依赖:
|
||
pip install openai>=1.0.0
|
||
"""
|
||
|
||
import json
|
||
import time
|
||
from typing import Any
|
||
|
||
from config.settings import LLMConfig
|
||
from llm.providers.base_provider import BaseProvider, PlanResult, ReplyResult
|
||
from mcp.mcp_protocol import ChainPlan, ToolSchema, ToolStep
|
||
from utils.logger import get_logger
|
||
|
||
# OpenAI SDK（运行时导入，避免未安装时整体崩溃）
|
||
try:
|
||
from openai import (
|
||
APIConnectionError,
|
||
APIStatusError,
|
||
APITimeoutError,
|
||
AuthenticationError,
|
||
OpenAI,
|
||
RateLimitError,
|
||
)
|
||
_OPENAI_AVAILABLE = True
|
||
except ImportError:
|
||
_OPENAI_AVAILABLE = False
|
||
|
||
|
||
class OpenAIProvider(BaseProvider):
|
||
"""
|
||
OpenAI Provider 实现
|
||
|
||
支持:
|
||
- 标准 OpenAI API（gpt-4o / gpt-4-turbo / gpt-3.5-turbo 等）
|
||
- 兼容 OpenAI 协议的第三方代理（通过 api_base_url 配置）
|
||
- Function Calling 多工具并行/串行规划
|
||
- 自动重试（RateLimit / 网络超时）
|
||
- API 不可用时降级到规则引擎
|
||
|
||
配置示例（config.yaml）:
|
||
llm:
|
||
provider: "openai"
|
||
model_name: "gpt-4o"
|
||
api_key: "sk-..."
|
||
api_base_url: "" # 留空使用官方地址
|
||
temperature: 0.2 # 规划任务建议低温度
|
||
function_calling: true
|
||
"""
|
||
|
||
# 系统 Prompt：指导 LLM 进行多步骤工具规划
|
||
_PLANNER_SYSTEM_PROMPT = """\
|
||
你是一个智能任务规划助手，擅长将用户需求分解为多个工具调用步骤。
|
||
|
||
## 工作原则
|
||
1. 仔细分析用户需求，判断是否需要调用工具
|
||
2. 如需多个工具，按逻辑顺序依次调用
|
||
3. 当后续步骤依赖前步结果时，先完成前步再继续
|
||
4. 每次只规划并调用当前最合适的工具
|
||
5. 所有工具执行完毕后，整合结果给出最终回复
|
||
"""
|
||
|
||
# 回复生成系统 Prompt
|
||
_REPLY_SYSTEM_PROMPT = """\
|
||
你是一个友好、专业的 AI 助手。
|
||
请基于已执行的工具调用结果，用清晰、自然的语言回答用户的问题。
|
||
回复要简洁明了，重点突出工具执行的关键结果。
|
||
"""
|
||
|
||
def __init__(self, cfg: LLMConfig):
|
||
self.cfg = cfg
|
||
self.logger = get_logger("LLM")
|
||
self._client: "OpenAI | None" = None
|
||
|
||
if not _OPENAI_AVAILABLE:
|
||
self.logger.warning("⚠️ openai 包未安装，请执行: pip install openai>=1.0.0")
|
||
else:
|
||
self._init_client()
|
||
|
||
# ── Provider 标识 ────────────────────────────────────────────
|
||
|
||
@property
|
||
def provider_name(self) -> str:
|
||
return "openai"
|
||
|
||
# ── 客户端初始化 ─────────────────────────────────────────────
|
||
|
||
def _init_client(self) -> None:
|
||
"""初始化 OpenAI 客户端"""
|
||
if not self.cfg.api_key:
|
||
self.logger.warning(
|
||
"⚠️ LLM_API_KEY 未设置，OpenAI API 调用将失败。\n"
|
||
" 请设置环境变量: export LLM_API_KEY=sk-..."
|
||
)
|
||
|
||
kwargs: dict[str, Any] = {
|
||
"api_key": self.cfg.api_key or "sk-placeholder",
|
||
"timeout": self.cfg.timeout,
|
||
"max_retries": self.cfg.max_retries,
|
||
}
|
||
if self.cfg.api_base_url:
|
||
kwargs["base_url"] = self.cfg.api_base_url
|
||
self.logger.info(f"🔗 使用自定义 API 地址: {self.cfg.api_base_url}")
|
||
|
||
self._client = OpenAI(**kwargs)
|
||
self.logger.info(
|
||
f"✅ OpenAI 客户端初始化完成\n"
|
||
f" model = {self.cfg.model_name}\n"
|
||
f" base_url = {self.cfg.api_base_url or 'https://api.openai.com/v1'}\n"
|
||
f" max_retries= {self.cfg.max_retries}"
|
||
)
|
||
|
||
# ════════════════════════════════════════════════════════════
|
||
# 核心接口实现
|
||
# ════════════════════════════════════════════════════════════
|
||
|
||
def plan_with_tools(
|
||
self,
|
||
messages: list[dict],
|
||
tool_schemas: list[ToolSchema],
|
||
) -> PlanResult:
|
||
"""
|
||
调用 OpenAI Function Calling 规划工具调用链
|
||
|
||
OpenAI 消息格式:
|
||
[
|
||
{"role": "system", "content": "..."},
|
||
{"role": "user", "content": "用户输入"},
|
||
]
|
||
|
||
OpenAI tools 格式:
|
||
[
|
||
{
|
||
"type": "function",
|
||
"function": {
|
||
"name": "calculator",
|
||
"description": "计算数学表达式",
|
||
"parameters": {"type": "object", "properties": {...}}
|
||
}
|
||
}
|
||
]
|
||
|
||
返回 tool_calls 示例:
|
||
[
|
||
{
|
||
"id": "call_abc123",
|
||
"type": "function",
|
||
"function": {"name": "calculator", "arguments": '{"expression":"1+1"}'}
|
||
}
|
||
]
|
||
"""
|
||
if not self._client:
|
||
return PlanResult(plan=None, success=False, error="OpenAI 客户端未初始化")
|
||
|
||
# 构造 OpenAI tools 参数
|
||
tools = self._build_openai_tools(tool_schemas)
|
||
self.logger.debug(f"📤 发送规划请求，tools 数量: {len(tools)}")
|
||
self.logger.debug(f"📤 消息历史长度: {len(messages)}")
|
||
|
||
try:
|
||
response = self._client.chat.completions.create(
|
||
model=self.cfg.model_name,
|
||
messages=messages,
|
||
tools=tools,
|
||
tool_choice="auto", # 由模型决定是否调用工具
|
||
temperature=self.cfg.temperature,
|
||
max_tokens=self.cfg.max_tokens,
|
||
)
|
||
|
||
usage = self._extract_usage(response)
|
||
self.logger.info(
|
||
f"📊 Token 用量: prompt={usage.get('prompt_tokens', 0)}, "
|
||
f"completion={usage.get('completion_tokens', 0)}"
|
||
)
|
||
|
||
# 解析 tool_calls → ChainPlan
|
||
choice = response.choices[0]
|
||
message = choice.message
|
||
|
||
if not message.tool_calls:
|
||
# 模型决定不调用工具，直接回复
|
||
self.logger.info("💬 模型决策: 无需工具，直接回复")
|
||
return PlanResult(
|
||
plan=ChainPlan(goal="", steps=[]),
|
||
raw_response=response,
|
||
usage=usage,
|
||
)
|
||
|
||
plan = self._parse_tool_calls(message.tool_calls)
|
||
self.logger.info(f"📋 解析到 {plan.step_count} 个工具调用步骤")
|
||
return PlanResult(
|
||
plan=plan,
|
||
raw_response=response,
|
||
usage=usage,
|
||
)
|
||
|
||
except AuthenticationError as e:
|
||
return self._handle_error("认证失败，请检查 API Key", e)
|
||
except RateLimitError as e:
|
||
return self._handle_error("请求频率超限，请稍后重试", e)
|
||
except APITimeoutError as e:
|
||
return self._handle_error(f"请求超时（>{self.cfg.timeout}s）", e)
|
||
except APIConnectionError as e:
|
||
return self._handle_error("网络连接失败，请检查网络或 api_base_url", e)
|
||
except APIStatusError as e:
|
||
return self._handle_error(f"API 错误 HTTP {e.status_code}: {e.message}", e)
|
||
except Exception as e:
|
||
return self._handle_error(f"未知错误: {e}", e)
|
||
|
||
def generate_reply(
|
||
self,
|
||
messages: list[dict],
|
||
) -> ReplyResult:
|
||
"""
|
||
基于完整对话历史（含工具执行结果）生成最终自然语言回复
|
||
|
||
消息格式示例（含工具结果）:
|
||
[
|
||
{"role": "system", "content": "..."},
|
||
{"role": "user", "content": "搜索天气然后计算..."},
|
||
{"role": "assistant", "content": None,
|
||
"tool_calls": [{"id":"call_1","function":{"name":"web_search",...}}]},
|
||
{"role": "tool", "content": "搜索结果...", "tool_call_id": "call_1"},
|
||
{"role": "assistant", "content": None,
|
||
"tool_calls": [{"id":"call_2","function":{"name":"calculator",...}}]},
|
||
{"role": "tool", "content": "计算结果: 312", "tool_call_id": "call_2"},
|
||
]
|
||
"""
|
||
if not self._client:
|
||
return ReplyResult(content="", success=False, error="OpenAI 客户端未初始化")
|
||
|
||
self.logger.debug(f"📤 发送回复生成请求，消息长度: {len(messages)}")
|
||
|
||
try:
|
||
response = self._client.chat.completions.create(
|
||
model=self.cfg.model_name,
|
||
messages=messages,
|
||
temperature=self.cfg.temperature,
|
||
max_tokens=self.cfg.max_tokens,
|
||
)
|
||
|
||
content = response.choices[0].message.content or ""
|
||
usage = self._extract_usage(response)
|
||
self.logger.info(
|
||
f"✅ 回复生成成功，长度: {len(content)} chars，"
|
||
f"Token: {usage.get('completion_tokens', 0)}"
|
||
)
|
||
return ReplyResult(content=content, usage=usage)
|
||
|
||
except AuthenticationError as e:
|
||
return ReplyResult(content="", success=False,
|
||
error=f"认证失败: {e}")
|
||
except RateLimitError as e:
|
||
return ReplyResult(content="", success=False,
|
||
error=f"频率超限: {e}")
|
||
except APITimeoutError as e:
|
||
return ReplyResult(content="", success=False,
|
||
error=f"请求超时: {e}")
|
||
except Exception as e:
|
||
return ReplyResult(content="", success=False,
|
||
error=f"生成回复失败: {e}")
|
||
|
||
def health_check(self) -> bool:
|
||
"""发送最小请求检测 API 连通性"""
|
||
if not self._client:
|
||
return False
|
||
try:
|
||
self._client.chat.completions.create(
|
||
model=self.cfg.model_name,
|
||
messages=[{"role": "user", "content": "hi"}],
|
||
max_tokens=1,
|
||
)
|
||
return True
|
||
except Exception:
|
||
return False
|
||
|
||
# ════════════════════════════════════════════════════════════
|
||
# 工具方法
|
||
# ════════════════════════════════════════════════════════════
|
||
|
||
@staticmethod
|
||
def _build_openai_tools(tool_schemas: list[ToolSchema]) -> list[dict]:
|
||
"""
|
||
将 ToolSchema 列表转换为 OpenAI tools 参数格式
|
||
|
||
OpenAI 格式:
|
||
{
|
||
"type": "function",
|
||
"function": {
|
||
"name": "calculator",
|
||
"description": "计算数学表达式",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"expression": {"type": "string", "description": "..."}
|
||
},
|
||
"required": ["expression"]
|
||
}
|
||
}
|
||
}
|
||
"""
|
||
tools = []
|
||
for schema in tool_schemas:
|
||
tools.append({
|
||
"type": "function",
|
||
"function": {
|
||
"name": schema.name,
|
||
"description": schema.description,
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": schema.parameters,
|
||
"required": list(schema.parameters.keys()),
|
||
},
|
||
},
|
||
})
|
||
return tools
|
||
|
||
@staticmethod
|
||
def _parse_tool_calls(tool_calls: list) -> ChainPlan:
|
||
"""
|
||
将 OpenAI tool_calls 解析为 ChainPlan
|
||
|
||
OpenAI tool_calls 格式:
|
||
[
|
||
{
|
||
"id": "call_abc123",
|
||
"type": "function",
|
||
"function": {
|
||
"name": "calculator",
|
||
"arguments": '{"expression": "1+2"}' ← JSON 字符串
|
||
}
|
||
}
|
||
]
|
||
"""
|
||
steps: list[ToolStep] = []
|
||
for idx, tc in enumerate(tool_calls):
|
||
fn = tc.function
|
||
tool_name = fn.name
|
||
try:
|
||
arguments = json.loads(fn.arguments)
|
||
except json.JSONDecodeError:
|
||
arguments = {"raw": fn.arguments}
|
||
|
||
steps.append(ToolStep(
|
||
step_id=idx + 1,
|
||
tool_name=tool_name,
|
||
arguments=arguments,
|
||
description=f"调用 {tool_name}（由 OpenAI Function Calling 规划）",
|
||
depends_on=list(range(1, idx + 1)) if idx > 0 else [],
|
||
))
|
||
|
||
goal = " → ".join(s.tool_name for s in steps)
|
||
return ChainPlan(
|
||
goal=goal,
|
||
steps=steps,
|
||
is_single=len(steps) == 1,
|
||
)
|
||
|
||
@staticmethod
|
||
def _extract_usage(response: Any) -> dict[str, int]:
|
||
"""提取 Token 用量信息"""
|
||
if hasattr(response, "usage") and response.usage:
|
||
return {
|
||
"prompt_tokens": response.usage.prompt_tokens,
|
||
"completion_tokens": response.usage.completion_tokens,
|
||
"total_tokens": response.usage.total_tokens,
|
||
}
|
||
return {}
|
||
|
||
def _handle_error(self, msg: str, exc: Exception) -> PlanResult:
|
||
self.logger.error(f"❌ OpenAI API 错误: {msg}")
|
||
self.logger.debug(f" 原始异常: {exc}")
|
||
return PlanResult(plan=None, success=False, error=msg) |