# AI / LLM 配置说明

供应商、模型列表、默认通道写在 **`ai-service/etc/llm.yaml`**，**不要写在 Python 代码里**。

密钥仍放项目根 **`.env`**（`DEEPSEEK_API_KEY` 等），配置文件只引用环境变量名（`api_key_env`）。

## 文件

| 路径 | 作用 |
|------|------|
| `ai-service/etc/llm.yaml` | 供应商、模型、视觉默认、别名 |
| 项目根 `.env` | API Key、可选 `LLM_PROVIDER` / `VISION_*` 覆盖 |
| `AI_CONFIG_PATH` / `LLM_CONFIG_PATH` | 自定义配置文件绝对路径 |

Docker：`docker-compose.yml` 将 `llm.yaml` 挂载到 `/app/etc/llm.yaml`。

## 改配置后

```bash
./reload-config.sh ai
# 或
docker compose up -d --force-recreate ai
```

进程内配置有缓存；重启 `ai` 容器后生效。

## 增删供应商

在 `providers:` 下增加一段即可，例如：

```yaml
providers:
  openai:
    label: OpenAI
    base_url: https://api.openai.com/v1
    api_key_env: OPENAI_API_KEY
    default_model: gpt-4o-mini
    models:
      - id: gpt-4o-mini
        label: gpt-4o-mini
    supports_vision: true
    json_mode: true
```

并在 `.env` 增加 `OPENAI_API_KEY=...`，控制台「模型」列表会从 `/ai/api/v1/llm/providers` 自动带出。