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-27b | 131,072 token | 关闭:直接作答 |
qwen3.8-27b | 262,144 token | 默认开启(可调整) |
qwen3-embedding-8b | 32,768 token | 不适用:嵌入模型 |
两款对话模型均支持文本与图像输入,并支持工具调用与结构化输出。详见模型页面。
接口
| 方法 | 路径 | 用途 | 状态 |
|---|---|---|---|
| GET | /models | 列出当前提供的模型 | 支持 |
| POST | /chat/completions | 对话,支持流式、工具、结构化输出与图像 | 支持 |
| POST | /completions | 文本补全(旧格式) | 支持 |
| POST | /messages | Anthropic Messages API 格式 | 支持 |
| POST | /responses | OpenAI 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}}。
重试与超时
- 对
5xx响应使用指数退避加抖动重试(例如 1 秒、2 秒、4 秒,并设置上限)。如果响应包含Retry-After头,请至少等待该时长。 - 官方 OpenAI SDK 默认已对这类错误重试数次。可通过客户端的
max_retries选项调整。 - 不要原样重发
400请求,它仍会失败。 - 服务繁忙时,请求会先在队列中等待再开始生成。请设置宽松的客户端超时并使用流式响应,而不要对仅仅是响应较慢的请求进行重试:重试只会让队列更长。
延伸阅读
- OpenAI API 参考:请求与响应格式。
- vLLM 文档:该 API 背后的推理引擎。