API 参考

ReadyServer LLM API 由 vLLM 提供服务,并遵循 OpenAI API 格式,因此大多数 OpenAI 客户端只需更改 base URL 即可使用。

Base URL

http://api.readyserver.ai/v1

可从任意 ReadyServer VPS 通过我们的私有网络访问,公共互联网无法访问。下文中的路径均相对于该 URL。

身份验证

无需验证。访问权限由网络控制:只有 ReadyServer VPS 能够访问该 API。如果你的客户端一定要求填写 API 密钥,传入任意非空值即可,例如 not-needed。

模型

模型 ID上下文长度思考模式
qwen3.6-27b131,072 token关闭:直接作答
qwen3.8-27b262,144 token默认开启(可调整)
qwen3-embedding-8b32,768 token不适用:嵌入模型

两款对话模型均支持文本与图像输入,并支持工具调用与结构化输出。详见模型页面。

接口

方法路径用途状态
GET/models列出当前提供的模型支持
POST/chat/completions对话,支持流式、工具、结构化输出与图像支持
POST/completions文本补全(旧格式)支持
POST/messagesAnthropic Messages API 格式支持
POST/responsesOpenAI Responses API预览
POST/embeddings文本向量嵌入支持

Responses API 处于预览阶段。生产环境请使用 Chat Completions。

常用参数

适用于 POST /chat/completions:

参数说明
model必填。qwen3.6-27b 或 qwen3.8-27b。
messages必填。以 {"role", "content"} 对象列表表示的对话内容。
max_tokens生成的最大 token 数。若不设置,生成可能一直持续到模型的上下文长度上限,因此建议设置。
temperature, top_p采样控制。推荐取值见模型页面。
stream设为 true 可在生成过程中以 server-sent events 接收 token。加上 "stream_options": {"include_usage": true} 可在最后一个分块中获得 token 用量。
stop一个或多个用于结束生成的字符串。
tools, tool_choice工具调用。两款对话模型均支持。
response_format结构化输出:json_object 或 json_schema。
reasoning_effort仅适用于 qwen3.8-27b:"low" 或 "medium"。详见思考模式。
logprobs, top_logprobs返回所生成 token 的对数概率。

vLLM 还接受其他参数,例如 top_k 与 chat_template_kwargs,详见 vLLM 文档。使用 OpenAI SDK 时,请通过 extra_body 传入。

思考模式

qwen3.8-27b 在作答前会先进行推理。推理内容与答案分开返回,位于消息的 reasoning 字段中(流式传输时位于每个 delta 中),并计入 completion_tokens。

思考模式有助于处理多步骤问题,但耗时更长、消耗的 token 也更多。模型默认使用最高推理强度。对于较简单的任务,可降低强度或关闭思考:

请为推理留出额度

由于推理内容计入 completion_tokens,它可能在答案开始之前就用完全部额度。在默认强度下,一个简短的问题通常会消耗 1,500–2,600 个 completion_tokens,其中绝大部分是推理,因此当 max_tokens 为 1,000 时,返回结果可能是 finish_reason: "length"、全部额度都在 reasoning 中,而 content 完全为空。

在默认强度下请至少给出 4,000 的 max_tokens,或将 reasoning_effort 设为 "low"——后者通常只需几百个 token 即可作答。

Python

from openai import OpenAI

client = OpenAI()

# Less thinking: reasoning_effort can be "low" or "medium"
response = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "Is 221 a prime number?"}],
    reasoning_effort="low",
    max_tokens=1000,
)
print(response.choices[0].message.reasoning)
print(response.choices[0].message.content)

# No thinking: the model answers directly
response = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "Is 221 a prime number?"}],
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
    max_tokens=200,
)
print(response.choices[0].message.content)

curl

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [{"role": "user", "content": "Is 221 a prime number?"}],
    "chat_template_kwargs": {"enable_thinking": false},
    "max_tokens": 200
  }'

开启思考时,答案开头可能出现空行;如有需要请自行去除。qwen3.6-27b 直接作答,没有思考步骤。

工具调用

在 tools 中描述你的函数。当模型需要调用其中之一时,响应的 finish_reason 会是 "tool_calls",调用内容位于 message.tool_calls:

import json
from openai import OpenAI

client = OpenAI()

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="qwen3.6-27b",
    messages=[{"role": "user", "content": "What's the weather in Singapore?"}],
    tools=tools,
    max_tokens=300,
)
for call in response.choices[0].message.tool_calls or []:
    print(call.function.name, json.loads(call.function.arguments))

由你自己执行该函数,然后将结果作为一条 "role": "tool" 的消息发回,并带上对应的 tool_call_id,模型便可据此写出答案。

结构化输出

使用 response_format 可获得符合某个 schema 的 JSON:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="qwen3.6-27b",
    messages=[{"role": "user", "content": "Give the capital of Japan."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "capital",
            "schema": {
                "type": "object",
                "properties": {
                    "country": {"type": "string"},
                    "capital": {"type": "string"},
                },
                "required": ["country", "capital"],
            },
        },
    },
    max_tokens=100,
)
print(response.choices[0].message.content)  # a JSON object with country and capital

若不需要固定 schema,可使用 {"type": "json_object"},并在提示词中描述你期望的结构。

图像输入

两款对话模型均支持图像。请将图像以 base64 data URL 的形式与文本一同发送:

import base64
from openai import OpenAI

client = OpenAI()

with open("image.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="qwen3.6-27b",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image in one sentence."},
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image}"}},
        ],
    }],
    max_tokens=200,
)
print(response.choices[0].message.content)

图像会计入提示词的 token 数与上下文长度。

向量嵌入

qwen3-embedding-8b 将文本转换为向量,用于搜索、检索与聚类。它只是一个嵌入模型:不回答对话请求,而对话模型也不接受 /v1/embeddings。

from openai import OpenAI

client = OpenAI()

response = client.embeddings.create(
    model="qwen3-embedding-8b",
    input=["How do I deploy a VPS?", "What is a virtual private server?"],
)
for item in response.data:
    print(len(item.embedding))

传入列表即可在一次请求中嵌入多段文本。向量长度为 4,096,且已进行 L2 归一化,因此两个向量之间的余弦相似度就是它们的点积。

如果需要更小的向量,可使用 dimensions 指定,取值范围为 1 到 4096。截短后的向量会重新归一化,比较方式不变:

response = client.embeddings.create(
    model="qwen3-embedding-8b",
    input="A shorter vector, for a smaller index",
    dimensions=256,
)

每条输入受模型 32,768 token 的上下文限制。如果你不想解析浮点数,也支持 encoding_format="base64"。

Anthropic Messages API

为 Anthropic Messages API 开发的工具与 SDK 同样可以使用这些模型。请将 base URL 设为 http://api.readyserver.ai(不含 /v1),并使用任意占位 API 密钥:

# pip install anthropic
import anthropic

client = anthropic.Anthropic(base_url="http://api.readyserver.ai", api_key="not-needed")

message = client.messages.create(
    model="qwen3.6-27b",
    max_tokens=200,
    messages=[{"role": "user", "content": "Explain what a VPS is in one sentence."}],
)
print(message.content[0].text)

限制

限制项取值
上下文长度(提示词 + 输出)131,072 token(qwen3.6-27b)
262,144 token(qwen3.8-27b)
32,768 token(qwen3-embedding-8b)
每次请求的输出 token 数最多为上下文长度减去提示词部分

服务繁忙时,请求会排队,使用 token 较少的客户将被优先处理。详见公平使用政策。

错误

状态含义处理方式
400请求无效,例如 max_tokens 或提示词超出上下文长度修正请求;错误信息会说明问题所在
404找不到模型或接口请使用 GET /models 返回的 id,并检查路径
500, 502, 503服务器错误,或服务暂时不可用采用退避策略重试

错误响应采用 OpenAI 格式:{"error": {"message": "...", "type": "...", "code": 400}}。

重试与超时

延伸阅读