# LLM 服务验证 CLI 工具需求文档
## 1. 文档信息
| 项⽬                | 内容                                                                 |
|---------------------|----------------------------------------------------------------------|
| 文档版本            | V1.0                                                                 |
| 需求提出人          | -                                                                    |
| 需求接收人          | -                                                                    |
| 最后更新时间        | 2026-03-12                                                           |
| 工具开发语言        | Rust                                                                 |
| 适用操作系统        | Windows/macOS/Linux                                                  |

## 2. 需求概述
### 2.1 背景
日常工作中需频繁验证不同大语言模型（LLM）服务的可用性，当前通过手动编写/修改 Python 代码的方式效率低下，需开发一款轻量、灵活的 CLI 工具替代，支持多服务商适配、配置文件/命令行参数双驱动，降低 LLM 服务验证成本。

### 2.2 核心目标
开发基于 Rust 的 CLI 工具，实现以下核心能力：
1. 灵活配置 LLM 服务参数（服务商、API 地址、密钥、模型等）；
2. 支持配置文件/命令行参数双驱动，命令行参数优先级更高；
3. 一键验证 LLM 服务可用性（支持流式/非流式返回）；
4. 辅助功能：初始化默认配置文件、配置文件格式互转、列出服务商支持的模型；
5. 适配多类 LLM 服务商，具备可扩展性。

## 3. 功能需求
### 3.1 核心功能
#### 3.1.1 LLM 服务调用
- 支持通过配置文件/命令行参数指定 LLM 服务商、API 地址、密钥、模型名称；
- 支持配置对话上下文，命令行消息可追加到上下文末尾；
- 支持流式/非流式两种返回模式，流式返回实时打印内容，非流式返回一次性输出完整结果；
- 输出内容包含模型名称、响应耗时、响应内容等关键信息，格式清晰易读。

#### 3.1.2 模型列表查询
- 支持查询指定服务商下所有可用的模型列表（模拟 `client.models.list()` 功能）；
- 查询参数可通过配置文件/命令行参数指定（服务商、API 地址、密钥）。

#### 3.1.3 配置文件管理
- **初始化配置文件**：一键生成带注释的默认配置文件，支持 YAML（默认）/JSON 格式，文件已存在时提示是否覆盖；
- **格式互转**：支持 YAML ↔ JSON 格式互转，自动识别输入文件格式，可自定义输出路径，转换时保留数据完整性和注释；
- 配置文件字段与命令行参数一一对应，支持嵌套结构（如对话上下文）。

### 3.2 命令行参数规范
| 短参数 | 长参数         | 功能描述                                                                 | 必传性 | 优先级 | 示例                          |
|--------|----------------|--------------------------------------------------------------------------|--------|--------|-------------------------------|
| `-c`   | `--config`     | 指定配置文件路径（支持 YAML/JSON 格式）| 否     | 中     | `-c ~/llm-test.yaml`          |
| `-m`   | `--model`      | 指定模型名称，覆盖配置文件中的模型设置                                  | 否     | 高     | `-m glm-5-think-fast`         |
| `-l`   | `--list`       | 列出当前服务商支持的所有模型                                            | 否     | -      | `-l`                          |
| `-msg` | `--message`    | 追加用户消息（可多次使用，追加到配置文件上下文末尾）| 否     | 高     | `-msg "50+5=？" -msg "计算"`  |
| `-p`   | `--provider`   | 指定模型服务商（支持 openai/gemini，可扩展）| 否     | 高     | `-p openai`                   |
| `-u`   | `--url`        | 指定 API base_url，覆盖配置文件中的地址设置                             | 否     | 高     | `-u https://api.example.com/v1` |
| `-s`   | `--secret`     | 指定 API Key，覆盖配置文件/环境变量中的密钥                             | 否     | 高     | `-s sk-xxx`                   |
| -      | `--stream`     | 启用流式返回（默认关闭）| 否     | 高     | `--stream`                    |
| `-i`   | `--init`       | 创建默认配置文件，可选格式 yaml/json（默认 yaml）| 否     | -      | `-i json`                     |
| -      | `--init-path`  | 自定义初始化配置文件的生成路径（配合 `-i` 使用）| 否     | -      | `-i --init-path ~/llm.json`   |
| `-t`   | `--convert`    | 配置文件格式互转，参数：<输入路径> [输出路径]                           | 是（输入路径） | -      | `-t llm-test.json ~/llm.yaml` |
| `-h`   | `--help`       | 查看所有参数说明和使用示例                                              | 否     | -      | `-h`                          |
| `-v`   | `--version`    | 查看工具版本                                                            | 否     | -      | `-v`                          |

**参数优先级规则**：命令行参数 > 环境变量 > 配置文件 > 默认值。

### 3.3 配置文件规范
#### 3.3.1 格式支持
支持 YAML/JSON 两种格式，字段与命令行参数一一对应，核心字段如下：
| 字段       | 类型      | 说明                                                                 |
|------------|-----------|----------------------------------------------------------------------|
| `provider` | 字符串    | 模型服务商（openai/gemini）|
| `base_url` | 字符串    | API 基础地址                                                         |
| `api_key`  | 字符串    | API 密钥（建议优先通过命令行/环境变量设置）|
| `model`    | 字符串    | 默认模型名称                                                         |
| `stream`   | 布尔值    | 是否启用流式返回（默认 false）|
| `context`  | 数组      | 对话上下文，每个元素包含 `role`（system/user/assistant）和 `content` |

#### 3.3.2 示例文件
##### YAML 示例（llm-test.yaml）
```yaml
# LLM 测试工具配置文件
# 字段说明：
# - provider: 模型服务商（支持 openai/gemini，可扩展）
# - base_url: API 基础地址（如 OpenAI 兼容接口：https://api.example.com/v1）
# - api_key: API 密钥（建议优先通过命令行 -s/--secret 或环境变量 LLM_API_KEY 设置）
# - model: 模型名称（如 glm-5-think-fast/gemini-pro）
# - stream: 是否启用流式返回（true/false）
# - context: 对话上下文（role 支持 system/user/assistant）

provider: "openai"
base_url: ""
api_key: ""
model: "glm-5-think-fast"
stream: false
context:
  - role: "system"
    content: "You are a helpful assistant."
  - role: "user"
    content: "50+5=？"
  - role: "user"
    content: "调用工具计算"
```

##### JSON 示例（llm-test.json）
```json
{
  "provider": "openai",
  "base_url": "",
  "api_key": "",
  "model": "glm-5-think-fast",
  "stream": false,
  "context": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "50+5=？"
    },
    {
      "role": "user",
      "content": "调用工具计算"
    }
  ],
  "// 注释": "API 密钥建议通过命令行 -s/--secret 或环境变量 LLM_API_KEY 设置"
}
```

### 3.4 多服务商适配
#### 3.4.1 基础支持
至少支持以下两类服务商，后续可扩展：
1. **OpenAI 兼容接口**：如 GLM、DeepSeek、OpenAI 官方等遵循 OpenAI API 规范的服务商；
2. **Gemini**：Google Gemini 服务商。

#### 3.4.2 扩展规则
新增服务商时仅需实现统一的接口（模型列表查询、对话调用），无需修改核心逻辑。

### 3.5 交互示例
#### 3.5.1 基础调用（配置文件）
```bash
# 使用配置文件，启用流式返回（覆盖配置文件的 stream: false）
llm-test -c llm-test.yaml --stream
```

#### 3.5.2 纯命令行参数调用
```bash
# 指定服务商、地址、密钥、模型，追加用户消息
llm-test -p openai -u "https://api.example.com/v1" -s "sk-xxx" -m "glm-5-think-fast" -msg "100-20=？" --stream
```

#### 3.5.3 列出模型列表
```bash
# 通过配置文件指定参数，列出模型
llm-test -c llm-test.yaml -l

# 纯命令行参数列出模型
llm-test -p openai -u "https://api.example.com/v1" -s "sk-xxx" -l
```

#### 3.5.4 初始化配置文件
```bash
# 生成默认 YAML 配置文件
llm-test -i

# 生成 JSON 格式配置文件到指定路径
llm-test -i json --init-path ~/configs/llm.json
```

#### 3.5.5 配置文件格式转换
```bash
# JSON 转 YAML（默认输出路径）
llm-test -t llm-test.json

# YAML 转 JSON（自定义输出路径）
llm-test --convert llm-test.yaml ./new-llm-config.json
```

## 4. 非功能需求
### 4.1 易用性
- 参数命名符合行业惯例，错误提示清晰易懂（如「API Key 无效」「base_url 无法访问」）；
- 所有参数支持 `--help` 查看说明，配置文件包含详细注释；
- 流式返回无明显延迟，非流式返回响应速度与原生 API 一致。

### 4.2 安全性
- 支持从环境变量读取 API Key（如 `LLM_API_KEY`），避免明文传递/存储；
- 敏感信息（如 API Key）不在日志/输出中明文展示。

### 4.3 鲁棒性
- 捕获常见异常（API 调用失败、网络问题、文件不存在、格式错误等），给出友好提示，避免工具崩溃；
- 配置文件格式转换时，若输出文件已存在，提示用户是否覆盖。

### 4.4 可扩展性
- 服务商适配层设计为可扩展接口，新增服务商仅需实现接口；
- 配置文件字段预留扩展空间，兼容未来新增参数。

### 4.5 兼容性
- 支持 Windows/macOS/Linux 主流操作系统；
- 兼容主流 LLM 服务商的 API 规范。

## 5. 异常处理
| 异常场景                 | 处理方式                                                                 |
|--------------------------|--------------------------------------------------------------------------|
| API Key 无效/过期        | 提示「API 密钥无效，请检查密钥是否正确或是否过期」|
| base_url 无法访问        | 提示「API 地址无法访问，请检查网络或地址是否正确」|
| 模型名称不存在           | 提示「模型名称不存在，可通过 -l 参数查看当前服务商支持的模型列表」|
| 配置文件格式错误         | 提示「配置文件格式错误，请检查 YAML/JSON 语法是否正确」|
| 输入文件不存在（转换时） | 提示「输入文件不存在，请检查路径是否正确」|
| 输出文件已存在           | 提示「文件已存在，是否覆盖？[y/N]」，用户确认后再执行操作                |

## 6. 总结
1. 核心目标是开发 Rust 版 CLI 工具，替代手动编写 Python 代码验证 LLM 服务，支持多服务商适配、灵活配置；
2. 核心功能包括 LLM 服务调用、模型列表查询、配置文件初始化/格式转换，命令行参数优先级高于配置文件；
3. 非功能需求聚焦易用性、安全性、鲁棒性，确保工具稳定、易扩展、用户友好。
