前言

上一篇主要讲了项目背景和整体构思。这一章废话少说撸起袖子就是干。

.env 配置痛点

常见痛点：API Key、模型列表等信息硬编码进代码导致泄露风险，或忘记在环境变量里配置导致启动失败。

和以往一样。我们把所有 LLM 相关的 api_key模型列表、限流参数等放在 .env 文件中，运行时统一读取。

# LLM API Configuration
LLM_APP_KEY = "你的LLM API Key"
LLM_BASE_URL = "你的LLM服务URL"
# MCP Tool Configuration
MCP_APP_ID = "你的MCP工具ID"
# LangSmith Configuration
# LANGSMITH_API_KEY = "你的LangSmith API"
# Available Models Configuration
# Format:
AILABLE_MODELS=
# Web Search Rate Limiting Configuration
WEB_SEARCH_MAX_QPS =
# Research Configuration
NUMBER_OF_INITIAL_QUERIES =
MAX_RESEARCH_LOOPS = 

LLM 封装

痛点：不同厂商的调用方式差异大。模型 ID 写错或环境变量缺失会直接报错，调试成本高。

ModelConfig

定义模型相关配置，在 LLM 调用中唯一确认使用的是哪家的哪个模型。

class ModelConfig:
"""LLM模型配置"""
再看id，str = Field
从name来看，str = Field
icon的观点是。str = Field")
icon_color: str = Field

加载可用模型

从环境变量读取 AILABLE_MODELS。 若未配置或解析出错，需要提供兜底模型防止启动阻塞。

def load_available_models_from_env:
"""从环境变量加载可用模型"""
model_json = os.getenv
if not model_json:
# 兜底模型
return
说到try。models_data = json.loads
return
except Exception as e:
print
return 

默认模型获取

默认取列表最终一项，若列表为空返回硬编码兜底值。

def get_default_model_id:
"""获取默认模型ID"""
models = load_available_models_from_env
if models:
return models.id
return "qwen3.-max" # 兜底默认值

Agent 基础结构 & 痛点剖析

使用者痛点：

• L​LM 调用频繁出现超时或限流错误，却没有统一的重试/熔断机制。
• Prompt 渲染时占位符漏写导致生成的 Prompt 错误难以定位。
• 返回结果格式不一致，手动解析代码冗长且易出错。
• 缺乏对异常分类的细粒度处理，导致“永久错误”被盲目重试消耗资源。

Agent 主要类

class Agent:
step_prompt = """{prompt}"""
def __init__):
self.llm = OpenAICompatibleLLM
def __call__:
response = self.llm.generate_response
return response
def set_step_prompt:
self.step_prompt = prompt
def step:
step_prompt = self.prompt_format
response = ""
for _ in range: # 重试次数可调
再看try，response = self
response = self.post_process
break
except Exception as e:
logger.error}")
continue
return response
def post_process:
return response
def prompt_format:
"""高效进行 Prompt 模板渲染"""
prompt_ = copy.deepcopy
for k in kwargs.keys:
rep = "{" + k + "}"
prompt_ = prompt_.replace)
return prompt_

Pain Point – Prompt 渲染不完整导致 LLM 报错

If a placeholder is missing in {prompt}。generated request will be malformed. The above prompt_format method performs a deep‑copy and safe replacement to avoid side effects.

class JsonAgent:
"""将 LLM 返回数据转换为 JSON 格式"""
def __init__,keys=None):
super.__init__
self.keys = keys
def post_process:
"""把提取出的 JSON 转为 Pydantic 实例"""
result = json.loads)
if not self.keys:
return result
# 使用 Pydantic 自动校验字段与类型
return self.keys

限流器 & 痛点剖析

User Pain Point：

• L​LM 服务经常返回 429 限流错误，却没有本地令牌桶控制，导致指数级重试炸钱。
• 并发请求下锁竞争导致吞吐下降，没有把等待时间放在锁外。
• SLA 要求突发流量仍能保持低延迟，需要“突发+平滑”两种控制策略。