跳转到主要内容
本页说明 SimpleLLMFunc 的基础配置方式，重点包括 .env 环境变量和 provider.json 模型配置文件。

​
配置总览

.env 环境变量

管理日志目录、日志级别以及 Langfuse 等运行时配置。

provider.json

管理提供商、模型、API 密钥、重试和限流参数。

​
.env 文件

.env 用于存放环境变量。本框架主要读取日志配置和 Langfuse 配置。你可以在项目工作目录创建 .env，也可以直接通过系统环境变量覆盖。

​
日志相关环境变量

# 日志级别（默认 DEBUG）
# 可选值：DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_LEVEL=DEBUG

# 日志目录（默认 logs）
LOG_DIR=logs

​
支持的环境变量

环境变量说明可选值默认值
LOG_LEVEL控制台与文件日志级别DEBUG, INFO, WARNING, ERROR, CRITICALDEBUG
LOG_DIR日志输出目录任意路径logs
环境变量优先级从高到低依次为：运行时环境变量、.env 文件、框架默认值。

​
provider.json 文件

provider.json 用于配置模型提供商、API 密钥和限流参数。OpenAICompatible.load_from_json_file(...) 与 OpenAIResponsesCompatible.load_from_json_file(...) 都会读取此文件，并返回二维字典：providers[provider_id][model_name]。
provider.json 只描述 provider/model/key/base_url/retry/rate-limit 这些运行时接入信息，不决定你使用哪个装饰器。选择 OpenAICompatible 还是 OpenAIResponsesCompatible，取决于上游实际暴露的是 chat/completions 兼容端点还是 Responses API 端点。

​
配置文件结构

provider.json 采用“提供商 -> 模型配置列表”的结构。每个模型配置包含 model_name、密钥和重试 / 限流参数。 
{
  "openai": [
    {
      "model_name": "gpt-3.5-turbo",
      "api_keys": ["sk-test-key-1", "sk-test-key-2"],
      "base_url": "https://api.openai.com/v1",
      "max_retries": 5,
      "retry_delay": 1.0,
      "rate_limit_capacity": 20,
      "rate_limit_refill_rate": 3.0
    },
    {
      "model_name": "gpt-4",
      "api_keys": ["sk-test-key-3"],
      "base_url": "https://api.openai.com/v1",
      "max_retries": 5,
      "retry_delay": 1.0,
      "rate_limit_capacity": 10,
      "rate_limit_refill_rate": 1.0
    }
  ],
  "zhipu": [
    {
      "model_name": "glm-4",
      "api_keys": ["zhipu-test-key-1", "zhipu-test-key-2"],
      "base_url": "https://open.bigmodel.cn/api/paas/v4/",
      "max_retries": 3,
      "retry_delay": 0.5,
      "rate_limit_capacity": 15,
      "rate_limit_refill_rate": 2.0
    }
  ]
}

​
配置参数说明

参数类型说明示例
model_name字符串模型名称，作为索引 keygpt-3.5-turbo
api_keys数组API 密钥列表，支持负载均衡[”key1”, ”key2”]
base_url字符串API 服务地址https://api.openai.com/v1
max_retries数字最大重试次数5
retry_delay浮点数重试间隔，单位秒1.0
rate_limit_capacity数字令牌桶容量20
rate_limit_refill_rate浮点数令牌补充速率，单位 tokens/秒3.0

​
加载和使用

from SimpleLLMFunc import OpenAICompatible, OpenAIResponsesCompatible, llm_function

models = OpenAICompatible.load_from_json_file("provider.json")
gpt35 = models["openai"]["gpt-3.5-turbo"]
responses_models = OpenAIResponsesCompatible.load_from_json_file("provider.json")
gpt54 = responses_models["openrouter"]["gpt-5.4"]

@llm_function(llm_interface=gpt35)
async def my_task(text: str) -> str:
    """处理文本的任务"""
    pass

​
最佳实践

为同一模型配置多个 key，可以降低单 key 限流风险，并让 APIKeyPool 更好地分摊请求。
高成本或严格限速的模型应配置更保守的 rate_limit_capacity 和 rate_limit_refill_rate。
同一 provider 下的 model_name 会作为索引键，若重复，后者会覆盖前者。