""" 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)