> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 生成参数与 Logprobs

> 了解采样、重复惩罚、seed 和 token 概率的模型及渠道限制。

## 参数选择

| Chat 字段 | 用途 | 注意事项 |
| - | - | - |
| `temperature` / `top_p` | 调整采样 | 先调一个；范围与可用性由模型决定，温度为零也不保证重复结果相同 |
| `seed` | 请求尽力复现 | 固定 seed 不能固定模型版本、路由或后端实现 |
| `frequency_penalty` / `presence_penalty` | 调整重复倾向 | 不同模型支持不同；零值不应当作省略 |
| `logit_bias` | 调整指定 token 的采样倾向 | token ID 依赖目标 tokenizer，不是通用词表 |
| `logprobs` / `top_logprobs` | 请求生成 token 及候选的对数概率 | 需要模型支持；候选数量不保证正好等于请求值 |
| `max_tokens` / `max_completion_tokens` | 限制生成 | 不要同时盲设；参见 [推理模型](/zh/guides/reasoning-models) |

项目 DTO 用指针表达多数可选采样字段，区分省略与 `0` / `false`；但 OpenAI 适配器仍会按模型能力移除不支持的 `temperature`、`top_p`、`logprobs` 和 `top_logprobs`。不要把成功的 HTTP 回执理解成每个参数都生效。`seed`、惩罚、logprobs 的 Chat 示例不能直接套用到 Responses。

## 读取 Logprobs

非流式 Chat 返回位置是 `choices[].logprobs.content`，每项有 `token`、`logprob`、可选 `bytes` 及 `top_logprobs`。这是 token 的采样信息，不是答案正确率，不能用于判断事实真假；极小概率占位值也不适合直接当精确概率。流式元数据出现在每个 choice 的 `logprobs`，不是 `delta.content` 内，消费者需要按 choice 和顺序累计。

普通 OpenAI 响应转发保留原始字段；启用渠道 `ForceFormat` 重建响应或做协议转换时，不能保证保留额外 logprobs 元数据。若缺失，检查模型是否支持、请求字段是否被过滤，以及实际返回路径。

示例显式发送零值、请求两个候选，要求完整文本和非空 token 元数据。它允许空候选数组，不要求固定候选数量；校验有限非正数、字节范围和拒答/工具/截断状态后，输出文本与 token 概率，不输出原始响应或推理字段。一次请求，无自动重试；本地测试不证明上游复现性或概率质量。

实现依据：`relaykit/dto/openai_request.go`、`relay/channel/openai/adaptor.go`、`relay/channel/openai/relay-openai.go`。参见 [Chat API](/zh/api-reference/chat-completions)、[参数过滤](/zh/guides/data-controls)。

## 运行示例

在文档目录运行，使用已获准发送的输入和支持该能力的模型；先阅读 [REST 运行时](/zh/guides/http-runtime)。脚本与 `http-client.mjs` 放在同一目录。

```sh theme={null}
export API_ROOT_URL='https://gateway.example.com'
export API_KEY='YOUR_API_KEY'
export API_MODEL='YOUR_LOGPROBS_MODEL_ID'
node examples/logprobs.mjs
```

```javascript theme={null}
import { requestJSON } from './http-client.mjs';

try {
  const model = process.env.API_MODEL;
  if (!model?.trim()) throw new Error('Set model.');
  const result = await requestJSON('/v1/chat/completions', {
    model, messages: [{ role: 'user', content: 'Reply with the word hello.' }],
    temperature: 0, seed: 0, frequency_penalty: 0, presence_penalty: 0,
    logprobs: true, top_logprobs: 2,
  });
  const choice = result.choices?.[0];
  const message = choice?.message;
  if (!Array.isArray(result.choices) || result.choices.length !== 1 || choice?.index !== 0
    || choice.finish_reason !== 'stop' || message?.role !== 'assistant'
    || message.refusal != null || message.tool_calls != null || message.function_call != null
    || typeof message.content !== 'string' || !message.content.trim()) throw new Error('Incomplete text.');
  const tokens = choice.logprobs?.content;
  if (!Array.isArray(tokens) || !tokens.length) throw new Error('Missing logprobs.');
  const observations = [];
  for (const token of tokens) {
    if (!Array.isArray(token?.top_logprobs)) throw new Error('Missing alternatives.');
    for (const value of [token, ...token.top_logprobs]) {
      if (typeof value?.token !== 'string' || typeof value.logprob !== 'number'
        || !Number.isFinite(value.logprob) || value.logprob > 0
        || (value.bytes != null && (!Array.isArray(value.bytes)
          || value.bytes.some((byte) => !Number.isInteger(byte) || byte < 0 || byte > 255)))) {
        throw new Error('Invalid token metadata.');
      }
    }
    observations.push({ token: token.token, logprob: token.logprob,
      top_logprobs: token.top_logprobs.map(({ token, logprob }) => ({ token, logprob })) });
  }
  console.log(JSON.stringify({ text: message.content, tokens: observations }));
} catch {
  console.error('Logprobs example failed. Check model support, retained metadata, and completion status. No automatic retry.');
  process.exitCode = 1;
}
```

[Read in English](/en/guides/generation-parameters)

[相关指南：预测输出](/zh/guides/predicted-outputs)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.