服务调用

接口测试

服务启动后，可先检查模型列表：

curl http://localhost:8000/v1/models

输出示例：

{
  "object": "list",
  "data": [
    {
      "id": "/home/dev/models/gptq-Qwen3-8B",
      "object": "model",
      "owned_by": "vllm",
      "root": "/home/dev/models/gptq-Qwen3-8B",
      "parent": null
    }
  ]
}

warning

以下调用示例中的 model 需要与服务端实际部署的模型路径或 --served-model-name 保持一致。

文本生成模型调用

适用于 Qwen、Qwen Instruct 等通过 /v1/chat/completions 接口调用的文本生成模型。以下以 gptq-Qwen3-8B 为例。

curl 调用

另开一个窗口调用：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "temperature": 0.7,
    "top_p": 0.8,
    "max_tokens": 100,
    "chat_template_kwargs":{"enable_thinking":false},
    "messages": [
      {
        "role": "user",
        "content": "北京有哪些名胜古迹？"
      }
    ]
  }'

参数说明

参数名	作用	输入范围（含建议值）
temperature	控制生成随机性，值越大越发散、越小越确定	浮点数 0.0 ~ 2.0（建议：0.1 ~ 1.5）
top_p	核采样，只从累积概率达到 top_p 的 token 中采样	浮点数 0.0 ~ 1.0（建议：0.7 ~ 0.9）
max_tokens	单次响应最大生成 token 数	正整数，且不超过模型最大上下文长度
chat_template_kwargs	传递给 chat template 的附加参数	{"enable_thinking":false} 表示关闭 thinking 输出
messages	对话消息列表	按 OpenAI Chat Completions 格式填写

多模态图片调用

多模态图片模型启动时需要增加 --limit-mm-per-prompt '{"image":1}'。Qwen3-VL 2B/4B 不需要 --hf-overrides；Qwen3-VL 8B 需要额外增加 --hf-overrides '{"text_config":{"tie_word_embeddings":false}}'。

使用在线图片 URL

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "/home/dev/models/gptq-Qwen3-VL-8B-Instruct-4bit-group",
    "max_tokens": 256,
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请描述这张图片。"},
          {
            "type": "image_url",
            "image_url": {
              "url": "https://modelscope.oss-cn-beijing.aliyuncs.com/resource/qwen.png"
            }
          }
        ]
      }
    ]
  }'

使用本地图片进行测试

下面示例会在内存中生成一张 32×32 的四色块 PNG 图片，并调用多模态模型识别图片颜色。该测试适合快速确认图片输入链路是否可用。

import base64
import io

from openai import OpenAI
from PIL import Image, ImageDraw

client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")
model = client.models.list().data[0].id

image = Image.new("RGB", (32, 32), "white")
draw = ImageDraw.Draw(image)
draw.rectangle([0, 0, 15, 15], fill="red")
draw.rectangle([16, 0, 31, 15], fill="green")
draw.rectangle([0, 16, 15, 31], fill="blue")
draw.rectangle([16, 16, 31, 31], fill="yellow")

buffer = io.BytesIO()
image.save(buffer, format="PNG")
image_base64 = base64.b64encode(buffer.getvalue()).decode("utf-8")
image_url = f"data:image/png;base64,{image_base64}"

response = client.chat.completions.create(
    model=model,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "This image is divided into four colored blocks. List the visible colors only."},
            {"type": "image_url", "image_url": {"url": image_url}},
        ],
    }],
    max_tokens=128,
)

print(response.choices[0].message.content)

tip

图片测试用于快速验证多模态服务链路。若模型能完成文本对话且能识别出部分图片信息，通常说明图片输入链路已连通；如果需要评估多模态质量，建议结合真实图片和更明确的问题进一步测试。

Embedding 模型调用

bge-m3 需要按 pooling/embedding 方式启动，并通过 /v1/embeddings 接口调用。启动服务时建议使用 --served-model-name testmodel，调用时 model 填写 testmodel。

curl 调用

curl -s http://127.0.0.1:8000/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "testmodel",
    "input": "你好，请用一句话介绍你自己。"
  }'

返回结果中会包含 embedding 向量，例如 bge-m3 的向量维度为 1024。

Python 调用

from openai import OpenAI

client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")

response = client.embeddings.create(
    model="testmodel",
    input="你好，请用一句话介绍你自己。",
)

embedding = response.data[0].embedding
print("embedding dim:", len(embedding))
print("first 5 values:", embedding[:5])

Reranker 模型调用

bge-reranker-v2-m3 需要按 pooling/classify 方式启动，并通过 /v1/score 接口调用。启动服务时建议使用 --served-model-name testmodel，调用时 model 填写 testmodel。

curl -s http://127.0.0.1:8000/v1/score \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "testmodel",
    "text_1": "What is the capital of France?",
    "text_2": [
      "Paris is the capital of France.",
      "Berlin is in Germany."
    ]
  }'

返回结果中会包含每个文本对的相关性分数。测试中，匹配样本分数约为 0.9998467565，非匹配样本分数约为 0.0004226465。

Python 调用

流式输出

from openai import OpenAI

openai_api_key = "EMPTY"
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

models = client.models.list()
model = models.data[0].id

chat_completion = client.chat.completions.create(
    messages=[{
        "role": "system",
        "content": "You are a helpful assistant."
    }, {
        "role": "user",
        "content": "北京有哪些名胜古迹？"
    }],
    model=model,
    temperature=0.7,
    top_p=0.8,
    extra_body={
        "top_k": 20,
        "repetition_penalty": 1.05,
    },
    max_tokens=512,
    stream=True,
)

print("Chat response (streaming):")
for chunk in chat_completion:
    if chunk.choices:
        delta = chunk.choices[0].delta
        content = delta.content
        if content:
            print(content, end="", flush=True)
print("\n - Chat response (end) -\n")

输出示例：

Chat response (streaming):
北京是中国历史文化名城之一，拥有众多名胜古迹。其中最著名的是故宫、长城、天安门广场、天坛、颐和园、圆明园、八达岭长城、德胜门等。这些景点都是了解中国历史和文化的重要途径。
 - Chat response (end) -

非流式输出

from openai import OpenAI

openai_api_key = "EMPTY"
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

models = client.models.list()
model = models.data[0].id

chat_completion = client.chat.completions.create(
    messages=[{
        "role": "system",
        "content": "You are a helpful assistant."
    }, {
        "role": "user",
        "content": "北京有哪些名胜古迹？"
    }],
    model=model,
    temperature=0.7,
    top_p=0.8,
    extra_body={
        "top_k": 20,
        "repetition_penalty": 1.05,
    },
    max_tokens=512,
    stream=False,
)

print("Chat completion results:")
print(chat_completion)