配置文件说明

.env 文件

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

日志相关环境变量

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

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

支持的环境变量

环境变量	说明	可选值	默认值
LOG_LEVEL	控制台与文件日志级别	DEBUG, INFO, WARNING, ERROR, CRITICAL	DEBUG
LOG_DIR	日志输出目录	任意路径	logs

环境变量优先级

优先级顺序（从高到低）：

1. 运行时环境变量（如 export LOG_LEVEL=INFO）

2. .env 文件中的配置

3. 框架默认值

provider.json 文件

provider.json 用于配置模型提供商、API 密钥与限流参数。OpenAICompatible.load_from_json_file(...) 读取此文件并返回一个二维字典：providers[provider_id][model_name]。

配置文件结构

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	字符串	模型名称（作为索引 key）	gpt-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, llm_function

models = OpenAICompatible.load_from_json_file("provider.json")
gpt35 = models["openai"]["gpt-3.5-turbo"]

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

最佳实践

1. 多密钥负载均衡：同一模型配置多个 key，避免单 key 限流。

2. 按模型调整限流：高成本模型设置更保守的 rate_limit_capacity 与 rate_limit_refill_rate。

3. 避免重复 model_name：同一 provider 内的 model_name 将作为索引键，重复会覆盖。