Add Comments

ReportEngine/llms/base.py

@@ -1,5 +1,5 @@
 """
-Unified OpenAI-compatible LLM client for the Report Engine, with retry support.
+Report Engine 默认的OpenAI兼容LLM客户端封装，内置重试/流式能力。
 """
 
 import os
@@ -19,7 +19,9 @@ try:
     from retry_helper import with_retry, LLM_RETRY_CONFIG
 except ImportError:
     def with_retry(config=None):
+        """简化版with_retry占位，实现与真实装饰器一致的调用签名"""
         def decorator(func):
+            """直接返回原函数，确保无retry依赖时代码仍可运行"""
             return func
         return decorator
 
@@ -27,9 +29,17 @@ except ImportError:
 
 
 class LLMClient:
-    """Minimal wrapper around the OpenAI-compatible chat completion API."""
+    """针对OpenAI Chat Completion API的轻量封装，统一Report Engine调用入口。"""
 
     def __init__(self, api_key: str, model_name: str, base_url: Optional[str] = None):
+        """
+        初始化LLM客户端并保存基础连接信息。
+
+        Args:
+            api_key: 用于鉴权的API Token
+            model_name: 具体模型ID，用于定位供应商能力
+            base_url: 自定义兼容接口地址，默认为OpenAI官方
+        """
         if not api_key:
             raise ValueError("Report Engine LLM API key is required.")
         if not model_name:
@@ -55,6 +65,17 @@ class LLMClient:
 
     @with_retry(LLM_RETRY_CONFIG)
     def invoke(self, system_prompt: str, user_prompt: str, **kwargs) -> str:
+        """
+        以非流式方式调用LLM，并返回一次性完成的完整响应。
+
+        Args:
+            system_prompt: 系统角色提示
+            user_prompt: 用户高优先级指令
+            **kwargs: 允许透传temperature/top_p等采样参数
+
+        Returns:
+            去除首尾空白后的LLM响应文本
+        """
         messages = [
             {"role": "system", "content": system_prompt},
             {"role": "user", "content": user_prompt},
@@ -142,11 +163,13 @@ class LLMClient:
 
     @staticmethod
     def validate_response(response: Optional[str]) -> str:
+        """兜底处理None/空白字符串，防止上层逻辑崩溃"""
         if response is None:
             return ""
         return response.strip()
 
     def get_model_info(self) -> Dict[str, Any]:
+        """以字典形式返回当前客户端的模型/提供方/基础URL信息"""
         return {
             "provider": self.provider,
             "model": self.model_name,