使用 cURL 测试 vLLM API

通过几个简单的 curl 命令，你就能测试 vLLM 服务的各种功能，从基础的内容生成到复杂的参数配置。

1. 基础测试命令

首先，确保你的 vLLM 服务已经在本地的 8000 端口（默认端口）上运行起来。你可以使用以下命令进行基础测试1。

1.1 Completions API（文本补全）

bash 复制代码

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "prompt": "请介绍一下人工智能的历史",
    "max_tokens": 100,
    "temperature": 0.7
  }'

温度设置的经验法则

任务类型	推荐温度	说明
事实性问答	0.1-0.3	确保准确性和一致性
技术文档	0.2-0.4	保持专业性和准确性
对话系统	0.5-0.7	平衡自然性和连贯性
内容创作	0.7-0.9	适当的创造性
诗歌故事	0.8-1.2	高度创造性
头脑风暴	1.0-1.5	最大化创意发散

1.2 Chat Completions API（聊天补全）

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "messages": [
      {
        "role": "system",
        "content": "你是一个乐于助人的助手。"
      },
      {
        "role": "user",
        "content": "请用简单的语言解释什么是机器学习？"
      }
    ],
    "max_tokens": 150,
    "temperature": 0
  }'

2. 关键参数详解

vLLM 的 API 支持多种参数来控制生成过程，下面是一些常用参数及其说明

参数	类型	默认值	描述
`model`	字符串	无	必填。需要使用的模型名称，必须与启动服务时的模型路径或名称保持一致。
`prompt` / `messages`	字符串/数组	无	必填。输入的问题或对话消息列表。
`max_tokens`	整数	16	每个输出序列要生成的最大 tokens 数量。
`temperature`	浮点数	1.0	控制采样随机性。值越低输出越确定性，越高越随机。0 表示贪婪采样。
`top_p`	浮点数	1.0	核采样参数，控制要考虑的 token 的累积概率范围。(0, 1]
`top_k`	整数	-1	控制要考虑的前几个 token 的数量。-1 表示考虑所有 token。
`stop`	字符串/数组	None	用于停止生成的字符串列表。遇到这些字符串时会停止生成。
`stream`	布尔值	False	是否开启流式输出（逐 token 返回）。
`n`	整数	1	返回多条结果的数量。通常建议 1-10 之间，值过大会影响性能。
`presence_penalty`	浮点数	0.0	根据生成文本中新出现词语进行奖惩。范围 [-2.0, 2.0]。
`frequency_penalty`	浮点数	0.0	根据生成文本中词语出现频率进行奖惩。范围 [-2.0, 2.0]。

3. 高级用法示例

3.1 流式输出 (Streaming)

使用流式输出可以实时获取生成结果，适合长文本生成场景1：

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "messages": [{"role": "user", "content": "写一个关于人工智能的短故事"}],
    "max_tokens": 200,
    "stream": true,
    "temperature": 0.8
  }'

3.2 多结果生成

一次性获取多个生成结果进行比较：

bash 复制代码

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "prompt": "未来十年最具潜力的技术是",
    "max_tokens": 50,
    "n": 3,
    "temperature": 0.9
  }'

3.3 使用停止条件

设置停止词来控制生成长度和内容：

bash 复制代码

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "prompt": "描述一下春天的特征：",
    "max_tokens": 100,
    "stop": ["。", "\n", "总结"],
    "temperature": 0.7
  }'

3.4 带惩罚参数的生成

使用惩罚参数来控制重复内容：

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "messages": [{"role": "user", "content": "用三种不同的方式表达同一个观点：学习很重要"}],
    "max_tokens": 120,
    "frequency_penalty": 0.5,
    "presence_penalty": 0.3,
    "temperature": 0.8
  }'

4. 实际应用示例

4.1 代码生成

bash 复制代码

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "prompt": "#!/bin/bash\n# 自动备份脚本\n# 功能：备份指定目录到远程服务器\n",
    "max_tokens": 100,
    "stop": ["# END", "```"],
    "temperature": 0.3
  }'

4.2 多轮对话

bash 复制代码

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "messages": [
      {"role": "system", "content": "你是一个专业的技术顾问，回答要准确且易懂。"},
      {"role": "user", "content": "什么是容器化技术？"},
      {"role": "assistant", "content": "容器化技术是一种将应用程序及其依赖环境打包在一起的方法，使得应用可以在任何环境中一致运行。Docker是其中最著名的平台。"},
      {"role": "user", "content": "它与虚拟机有什么区别？"}
    ],
    "max_tokens": 200,
    "temperature": 0.5
  }'

5. 处理认证和特殊配置

如果你的 vLLM 服务配置了认证或使用了特殊参数

bash 复制代码

# 如果服务需要 API 密钥（通常 vLLM 不需要，但某些部署可能配置）
curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "prompt": "需要认证的请求",
    "max_tokens": 50
  }'

# 使用 ignore_eos 参数强制生成直到达到 max_tokens
curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "prompt": "连续生成文本直到达到限制",
    "max_tokens": 200,
    "ignore_eos": true,
    "temperature": 0.7
  }'

6. 性能测试命令

如果你想要测试服务的性能，可以使用一些压力测试参数：

bash 复制代码

# 简单的性能测试（生成多个请求）
for i in {1..10}; do
  curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-oss-20b",
      "prompt": "测试请求 '$i'",
      "max_tokens": 50,
      "temperature": 0.1
    }' &
done
wait

💡 实用技巧

格式化 JSON 输出 ：如果返回的 JSON 难以阅读，可以使用 python -m json.tool 格式化：
bash 复制代码
```
curl http://localhost:8000/v1/completions ... | jq
```

保存输出到文件：

bash 复制代码

curl http://localhost:8000/v1/completions ... -o response.json

查看请求耗时 ：添加 -w 参数查看详细时间信息：

bash 复制代码

curl -w "\n时间统计:\n总时间: %{time_total}秒\nDNS解析: %{time_namelookup}秒\n连接时间: %{time_connect}秒\n预传输: %{time_pretransfer}秒\n重定向: %{time_redirect}秒\n开始传输: %{time_starttransfer}秒\n" \
  http://localhost:8000/v1/completions ...