跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt

Use this file to discover all available pages before exploring further.

​
配置

​
provider.json

主要的模型配置文件。定义可用的提供商和模型： 
{
  "openrouter": [
    {
      "model_name": "openai/gpt-4o",
      "api_keys": ["sk-key-1", "sk-key-2"],
      "base_url": "https://openrouter.ai/api/v1",
      "api_params": {"reasoning_effort": "high"},
      "max_retries": 5,
      "retry_delay": 1.0,
      "rate_limit_capacity": 20,
      "rate_limit_refill_rate": 3.0
    },
    {
      "model_name": "anthropic/claude-3.5-sonnet",
      "api_keys": ["sk-key-1"],
      "base_url": "https://openrouter.ai/api/v1",
      "max_retries": 3,
      "retry_delay": 2.0,
      "rate_limit_capacity": 10,
      "rate_limit_refill_rate": 2.0
    }
  ],
  "local": [
    {
      "model_name": "llama-3.1-70b",
      "api_keys": ["not-needed"],
      "base_url": "http://localhost:8000/v1",
      "max_retries": 2,
      "retry_delay": 0.5,
      "rate_limit_capacity": 50,
      "rate_limit_refill_rate": 10.0
    }
  ]
}

​
结构

  • 顶层 = 提供商 ID → 模型配置数组
  • 查找 = providers[provider_id][model_name]
  • 多密钥 = 在 api_keys 中的密钥之间进行负载均衡

​
字段说明

字段类型必填说明
model_namestring是提供商的模型标识符
api_keysstring[]是一个或多个 API 密钥（轮换使用）
base_urlstring是API 端点基础 URL
api_paramsobject否该模型的默认 API 透传参数（例如 reasoning_effort）。调用时传入的 kwargs 会覆盖这些默认值。
max_retriesint否瞬时故障的重试次数。默认值：5
retry_delayfloat否重试间隔秒数。默认值：1.0
rate_limit_capacityint否令牌桶容量。默认值：10
rate_limit_refill_ratefloat否每秒令牌补充速率。默认值：1.0

​
加载

from SimpleLLMFunc import OpenAICompatible

models = OpenAICompatible.load_from_json_file("provider.json")
llm = models["openrouter"]["openai/gpt-4o"]
或者使用 Responses API： 
from SimpleLLMFunc import OpenAIResponsesCompatible

models = OpenAIResponsesCompatible.load_from_json_file("provider.json")
llm = models["openrouter"]["openai/gpt-4o"]

​
最佳实践

  • 每个项目维护一个 provider.json（纳入版本控制，但去掉密钥）
  • 为热门模型在 api_keys 中配置多个密钥（自动轮换）
  • 使用 api_params 配置稳定的每模型默认参数，例如 reasoning_effort；一次性覆盖请在调用时传 kwargs
  • 根据你的服务等级调整 rate_limit_capacity 和 rate_limit_refill_rate
  • 本地模型使用 max_retries=2（快速失败），云端模型使用 max_retries=5（应对瞬时错误）

​
环境变量（.env）

框架从 .env 文件读取日志和可观测性配置： 
# 日志
LOG_LEVEL=WARNING          # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_DIR=logs               # 日志文件目录

# Langfuse（可选）
LANGFUSE_PUBLIC_KEY=your_public_key
LANGFUSE_SECRET_KEY=your_secret_key
LANGFUSE_BASE_URL=https://cloud.langfuse.com
LANGFUSE_EXPORT_ALL_SPANS=true
LANGFUSE_ENABLED=true

​
优先级

运行时环境变量 → .env 文件 → 框架默认值

​
推荐默认值

  • LOG_LEVEL=WARNING —— 在正常使用时减少框架的输出噪音
  • LOG_DIR=logs —— 将日志文件放在项目根目录之外
  • Langfuse 默认禁用 —— 仅在需要收集 trace 时启用

​
直接构造（无需文件）

对于脚本和一次性使用场景，可以完全跳过 provider.json： 
from SimpleLLMFunc import APIKeyPool, OpenAICompatible

llm = OpenAICompatible(
    api_key_pool=APIKeyPool(
        api_keys=["sk-your-key"],
        provider_id="openai",
    ),
    model_name="gpt-4o",
    base_url="https://api.openai.com/v1",
)
这种方式非常适合 shell 脚本、演示和快速实验。