> ## 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、环境变量和日志设置

# 配置

## provider.json

主要的模型配置文件。定义可用的提供商和模型：

```json theme={null}
{
  "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_name`             | string    | 是  | 提供商的模型标识符                                                      |
| `api_keys`               | string\[] | 是  | 一个或多个 API 密钥（轮换使用）                                             |
| `base_url`               | string    | 是  | API 端点基础 URL                                                   |
| `api_params`             | object    | 否  | 该模型的默认 API 透传参数（例如 `reasoning_effort`）。调用时传入的 kwargs 会覆盖这些默认值。 |
| `max_retries`            | int       | 否  | 瞬时故障的重试次数。默认值：5                                                |
| `retry_delay`            | float     | 否  | 重试间隔秒数。默认值：1.0                                                 |
| `rate_limit_capacity`    | int       | 否  | 令牌桶容量。默认值：10                                                   |
| `rate_limit_refill_rate` | float     | 否  | 每秒令牌补充速率。默认值：1.0                                               |

### 加载

```python theme={null}
from SimpleLLMFunc import OpenAICompatible

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

或者使用 Responses API：

```python theme={null}
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` 文件读取日志和可观测性配置：

```bash theme={null}
# 日志
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：

```python theme={null}
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 脚本、演示和快速实验。