---
name: invoking-llm
description: 通用大模型调用工具。当需要调用任何大模型来完成文字和图片生成、图片理解、多模态任务时使用。支持 OpenAI 兼容接口（默认）、Gemini 原生接口、Claude 原生接口。其他 Skill 需要调用大模型时也可以使用本 Skill。
---

# invoking-llm

通过 Python 脚本调用各大供应商的 LLM，仅依赖 Python 标准库。

## 核心脚本

脚本路径：`.ai/skills/invoking-llm/scripts/call_llm.py`

必须使用 `python` 命令执行，不要读取脚本内容后自行实现调用逻辑。

---

## 执行流程

### 第一步：读取供应商配置

从 `.ai/skills/invoking-llm/.config/provider.txt` 读取当前供应商配置。

配置文件格式（每行一个字段，`#` 开头为注释）：

```
provider=apiyi
base_url=https://vip.apiyi.com/v1
style=openai
```

- `provider`：供应商名称，用于定位 API Key 文件（`.config/<provider>_api_key.txt`）
- `base_url`：接口地址，支持任意自定义地址
- `style`：API 风格，`openai` / `gemini` / `claude`，默认 `openai`

若配置文件不存在，使用默认值：`provider=apiyi`，`base_url=https://vip.apiyi.com/v1`，`style=openai`。

若用户在对话中明确指定了供应商或 base_url，以用户指定为准，忽略配置文件。

### 第二步：读取 API Key

从 `.ai/skills/invoking-llm/.config/<provider>_api_key.txt` 读取 Key（文件内容为一行 Key 值）。

若文件不存在或为空，告知用户：
1. 在 `.ai/skills/invoking-llm/.config/` 目录下创建 `<provider>_api_key.txt`，填入 Key
2. 若用户是 C 哥 AI 成长圈圈友，可在视频课中获取 API 易的专属 Key

`.config/` 目录已被 `.gitignore` 忽略，Key 不会被提交到 Git。

### 第三步：确定模型

用户明确指定模型时，直接使用。未指定时，根据下方"模型选择指南"自主判断。

**注意：不同供应商对同一模型的 model ID 格式可能不同**，见下方"各供应商 Model ID 格式"。

### 第四步：执行脚本

将上述参数传入脚本执行，从 stdout 获取输出：

```bash
python ".ai/skills/invoking-llm/scripts/call_llm.py" \
  --base-url "<base_url>" \
  --api-key "<key>" \
  --style "<style>" \
  --model "<model_id>" \
  --prompt "<prompt>"
```

---

## 各供应商 Model ID 格式

不同供应商对同一模型的 ID 格式不同，调用前需确认当前供应商的格式规则：

| 供应商 | Model ID 格式规则 | 示例 |
|---|---|---|
| `apiyi` | 直接使用模型原始 ID，无前缀 | `gpt-4o`、`claude-sonnet-4-5` |
| `siliconflow` | 直接使用模型原始 ID，无前缀 | `deepseek-ai/DeepSeek-V3` |
| `openrouter` | `开发商/模型名` 格式 | `anthropic/claude-3.5-sonnet`、`openai/gpt-4o` |
| `deepseek` | 仅支持自家模型，直接用原始 ID | `deepseek-chat`、`deepseek-reasoner` |
| `qwen` | 仅支持自家模型，直接用原始 ID | `qwen-max`、`qwen-plus` |
| `openai` | 直接使用模型原始 ID | `gpt-4o`、`o3` |
| `anthropic` | 直接使用模型原始 ID | `claude-opus-4-5` |
| `gemini` | 直接使用模型原始 ID | `gemini-2.5-pro` |

若不确定当前供应商的 model ID，可查阅该供应商的官方文档或模型列表页面。

---

## 模型选择指南

用户未指定模型时，根据任务类型自主选择：

- **生成图片** → `gpt-image-1`
- **理解图片内容** → `gemini-3-pro-preview` 或 `gemini-3-flash-preview`
- **文案写作、编程代码、智能体任务** → `claude-opus-4-6`
- **其他通用文本任务** → `gemini-3-flash-preview`

以下 model ID 均为 `apiyi` 供应商格式（默认供应商）。若使用其他供应商，参照上方格式规则转换。

### 文本输入 → 文本输出

| 模型 ID | 输入 | 输出 | 适用场景 | 特点 |
|---|---|---|---|---|
| `claude-sonnet-4-5` | 文本 | 文本 | 通用写作、分析、对话 | 综合能力强，速度与质量均衡，通用首选 |
| `claude-opus-4-5` | 文本 | 文本 | 复杂推理、长文档处理 | 最强 Claude，成本较高 |
| `gpt-4o` | 文本+图片 | 文本 | 通用任务、图片理解 | OpenAI 旗舰，多模态能力强 |
| `gpt-4o-mini` | 文本+图片 | 文本 | 简单问答、批量处理 | 速度快、成本低 |
| `o3` | 文本 | 文本 | 数学、代码、深度推理 | 推理最强，响应慢、成本高 |
| `o4-mini` | 文本+图片 | 文本 | 推理任务且预算有限 | 推理能力强，成本低于 o3 |
| `deepseek-chat` | 文本 | 文本 | 中文任务、日常对话、代码 | 国产顶级，成本极低，中文优秀 |
| `deepseek-reasoner` | 文本 | 文本 | 推理、数学、逻辑分析 | DeepSeek R1，推理链可见 |
| `gemini-2.5-pro` | 文本+图片 | 文本 | 超长上下文、复杂多模态 | 上下文窗口最大（100万token） |
| `gemini-2.0-flash` | 文本+图片 | 文本 | 速度优先的日常任务 | 极快，成本低 |

### 文本/图片输入 → 图片输出（生图）

| 模型 ID | 输入 | 输出 | 适用场景 | 特点 |
|---|---|---|---|---|
| `gemini-3-pro-image-preview` | 文本+图片 | 图片 | 高质量图片生成、图片编辑 | 支持多图片参考输入，生图首选，提示词支持任何语言包括中文，且支持生成的图片中包含文字 |

---

## 脚本参数说明

| 参数 | 说明 |
|---|---|
| `--base-url` | 接口地址（从配置文件读取后传入） |
| `--api-key` | API Key（从 Key 文件读取后传入） |
| `--style` | API 风格：`openai` / `gemini` / `claude` |
| `--model` | 模型 ID |
| `--system` | 系统提示词 |
| `--prompt` | 用户提示词（与 `--prompt-file` 二选一） |
| `--prompt-file` | 从文件读取提示词 |
| `--image` | 图片路径或 URL（可多次使用，支持多图） |
| `--output-file` | 文字回复写入文件（不指定则输出到 stdout） |
| `--image-out` | 生图结果保存路径 |
| `--max-tokens` | 最大输出 token 数，默认 4096 |
| `--temperature` | 温度，默认 0.7 |
| `--timeout` | 请求超时秒数，默认 120 |

---

## 输出说明

- 文字输出：stdout（可用 `--output-file` 写入文件）
- 图片输出：需指定 `--image-out` 保存路径
- 日志/错误：stderr，不影响 stdout 的纯净输出
- 退出码：`0` 成功，`1` 失败

---

## 其他 Skill 调用本 Skill

在其他 Skill 的工作流中，同样先读取配置文件获取 base_url 和 Key，再执行脚本：

```bash
python ".ai/skills/invoking-llm/scripts/call_llm.py" \
  --base-url "<base_url>" \
  --api-key "<key>" \
  --model "claude-sonnet-4-5" \
  --prompt "你的提示词" \
  --output-file "temp/result.txt"
```

---

## 错误处理

| 错误 | 处理方式 |
|---|---|
| 未找到 API Key 文件 | 告知用户创建 `.config/<provider>_api_key.txt` 并填入 Key |
| HTTP 401 / 403 | API Key 无效或已过期，告知用户检查 Key |
| HTTP 429 | 请求频率过高或余额不足 |
| 网络请求失败 | 检查 base_url 是否正确，或改用中转供应商 |
| 超时 | 增大 `--timeout` 参数值后重试 |
| Python 未安装 | 告知用户从 https://www.python.org/downloads/ 下载，安装时勾选"Add to PATH" |
| 模块缺失 | 本脚本仅用 Python 标准库，无需安装任何包 |
