推理/对话补全

对话补全

/v1/chat/completions 是 wylon 新云 Token 工厂的主推理接口，与 OpenAI 协议完全兼容。它接收一组消息并返回模型生成的助手回复——流式输出、函数调用与结构化输出都通过请求参数控制。整体能力概览见推理概览。

端点

POSThttps://api.wylon.cn/v1/chat/completions

请求参数

参数	类型	说明
`model` 必填	string	模型 ID，例如 `moonshotai/Kimi-K2`。可用列表见模型目录或调用 `GET /v1/models`。
`messages` 必填	array	有序的对话轮次。角色支持 `system`、`user`、`assistant`、`tool`。
`temperature`	number	采样温度，范围 `0`–`2`。值越高随机性越强。
`top_p`	number	核采样阈值，范围 `0`–`1`。与 `temperature` 二选一调节。
`top_k`	integer	每步从概率最高的 K 个候选中采样；`0` 表示不限制。
`max_tokens`	integer	本次生成的最大 Token 数；不可超过模型上下文窗口。
`n`	integer	为同一组消息返回 N 个候选回复，默认 `1`。
`stream`	boolean	以 SSE 流返回增量。默认 `false`。详见下文流式输出。
`stop`	string / array	最多 4 个停止序列；命中后立即截断。
`presence_penalty`	number	`-2.0` 至 `2.0`。对已出现的 Token 施加惩罚，鼓励引入新内容。
`frequency_penalty`	number	`-2.0` 至 `2.0`。按出现频次惩罚 Token，抑制重复。
`seed`	integer	尽力而为的确定性采样种子；相同输入可复现相同输出。
`tools`	array	模型可调用的函数定义。详见函数调用。
`tool_choice`	string / object	控制是否调用工具：`"auto"`（默认）/ `"none"` / `"required"` / 指定函数。
`response_format`	object	强制 JSON 或指定结构。详见结构化输出。
`logprobs`	boolean	是否返回每个采样 Token 的对数概率。
`top_logprobs`	integer	当 `logprobs` 为 `true` 时，返回每步前 N 个候选的概率，`0`–`20`。
`user`	string	终端用户的稳定标识，用于滥用监控与组织层级审计。

info

上表中没有列出 temperature、top_p 等的默认值。各模型的默认采样参数可能不同，调用前请查阅模型目录中对应模型的说明。

消息结构

messages 中每一项都是带角色与内容的对象。内容可以是字符串，或对视觉语言模型而言，是一个内容块数组。

{
  "role": "user",
  "content": "什么是检索增强生成（RAG）？"
}

{
  "role": "user",
  "content": [
    {"type": "text", "text": "描述这张图片中的内容。"},
    {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
  ]
}

多轮对话

继续对话时，请将上一轮助手回复与下一轮用户消息追加到 messages。模型是无状态的 — 历史由你自行管理。

from openai import OpenAI
client = OpenAI(base_url="https://api.wylon.cn/v1", api_key=os.environ["WYLON_API_KEY"])

history = [
    {"role": "system", "content": "你是一位言简意赅的资深工程师。"},
    {"role": "user",   "content": "为内部服务在 REST 与 gRPC 之间做选择。"},
]

while True:
    resp = client.chat.completions.create(model="moonshotai/kimi-k2.5", messages=history)
    reply = resp.choices[0].message.content
    print("助手：", reply)
    history.append({"role": "assistant", "content": reply})
    user = input("你：")
    if not user: break
    history.append({"role": "user", "content": user})

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.wylon.cn/v1", apiKey: process.env.WYLON_API_KEY });

const history = [
  { role: "system", content: "你是一位言简意赅的资深工程师。" },
  { role: "user",   content: "为内部服务在 REST 与 gRPC 之间做选择。" },
];

const resp = await client.chat.completions.create({
  model: "moonshotai/kimi-k2.5", messages: history,
});
history.push(resp.choices[0].message);

流式输出

设置 stream: true 即可通过 SSE 接收 Token 级增量。末尾块为 [DONE]。

stream = client.chat.completions.create(
    model="moonshotai/kimi-k2.5",
    messages=[{"role": "user", "content": "写一首关于 GPU 的俳句。"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta: print(delta, end="", flush=True)

curl -N https://api.wylon.cn/v1/chat/completions \
  -H "Authorization: Bearer $WYLON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"moonshotai/kimi-k2.5","messages":[{"role":"user","content":"Write a haiku about GPUs."}],"stream":true}'

响应结构

非流式响应与 OpenAI 协议一一对应。

{
  "id": "cmpl-9f1c7b2e8a41",
  "object": "chat.completion",
  "created": 1744828800,
  "model": "moonshotai/Kimi-K2",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 128,
    "total_tokens": 152,
    "cache_hit_ratio": 0.71      // wylon 扩展字段
  }
}

cache_hit_ratio 是 wylon 在 OpenAI 协议之上的扩展字段，标识本次请求命中系统级上下文缓存的比例：重复前缀（系统提示、长文档）越多，命中率越高，计费也越优。

结束原因

值	含义
`stop`	模型自然结束或命中 `stop` 序列。
`length`	达到 `max_tokens` 或模型上下文上限。
`tool_calls`	模型请求一次或多次工具调用。
`content_filter`	输出被内容安全策略拦截。

错误码

请求失败时返回 OpenAI 兼容的错误体：{"error": {"type": "...", "message": "..."}}。常见 HTTP 状态如下。

状态	含义
`400`	参数错误：缺失必填字段、取值越界、模型 ID 不存在等。
`401`	鉴权失败：API 密钥无效、被吊销，或未携带 `Authorization` 头。
`403`	权限不足：账户未开通该模型或区域。
`429`	触发速率限制；响应头会携带 `retry-after`。
`500 / 503`	服务端临时故障；建议指数退避重试。