大模型 API 中的 Token Log Probabilities（logprobs）

文章目录

[**1. 什么是 logprobs**](#1. 什么是 logprobs)
[**2. 数学基础：logprob 的意义**](#2. 数学基础：logprob 的意义)
[**3. 为什么使用对数概率而不是直接概率？**](#3. 为什么使用对数概率而不是直接概率？)
- - [**(1) 防止浮点下溢（underflow）**](#(1) 防止浮点下溢（underflow）)
  - [**(2) 数值稳定，更易比较**](#(2) 数值稳定，更易比较)
  - [**(3) 便于累计句子的总概率**](#(3) 便于累计句子的总概率)
[**4. 如何使用 API 获取 logprobs（Python 实战）**](#4. 如何使用 API 获取 logprobs（Python 实战）)
[**5. 返回结构详解**](#5. 返回结构详解)
[**6. logprobs 的四大典型场景**](#6. logprobs 的四大典型场景)
- - [**① 评估模型输出的置信度**](#① 评估模型输出的置信度)
  - [**② 做评分与候选答案比较**](#② 做评分与候选答案比较)
  - [**③ 审核系统（辨别幻觉）**](#③ 审核系统（辨别幻觉）)
  - [**④ 查看模型下一步"想说什么"**](#④ 查看模型下一步“想说什么”)
[**7. 计算整句的总体置信度（Python 示例）**](#7. 计算整句的总体置信度（Python 示例）)
[**8. 用 logprobs 分析模型"下一步想说什么"**](#8. 用 logprobs 分析模型“下一步想说什么”)
[**9. 可视化 token 概率（Python + Matplotlib）**](#9. 可视化 token 概率（Python + Matplotlib）)
[**10. 常见陷阱与工程建议**](#10. 常见陷阱与工程建议)
- - [**(1) logprobs 越高越好吗？**](#(1) logprobs 越高越好吗？)
  - [**(2) 注意 tokenization 差异**](#(2) 注意 tokenization 差异)
  - [**(3) 不能直接跨模型比较 logprob**](#(3) 不能直接跨模型比较 logprob)
  - [**(4) logprobs 会增加 API 返回的数据量**](#(4) logprobs 会增加 API 返回的数据量)
**总结**

1. 什么是 logprobs

大模型在生成内容时不是一次性输出整句话，而是：

按 token（子词单元）逐个预测。

例如模型生成 "Hello" 时，实质上是在位置 1、2、3... 每个位置都进行一次"下一 token 预测"。

每个位置，模型都会给出一个概率分布（softmax）：

复制代码

Token:   "Hello"  "Hi"  "Hey" ...
Prob:     0.30    0.15   0.05 ...

logprob = log(probability)

例如 log(0.3) ≈ -1.204。

开启 logprobs 参数后，API 会返回：

模型最终选中的 token
每个 token 的 logprob
top-N 候选 token 及其 logprobs

这是理解模型内部决策过程的高级能力。

2. 数学基础：logprob 的意义

给定 token 的概率为：
p(token | context)

logprob 定义为：

logprob(token) = log(p(token))

由于 p ≤ 1，则 log§ ≤ 0。

典型值范围：

0 到 -0.2 → 非常高概率
-1 到 -3 → 中等概率
-5 以下 → 非常低概率

3. 为什么使用对数概率而不是直接概率？

三个原因：

(1) 防止浮点下溢（underflow）

生成 50 个 token 的句子，概率可能是：

复制代码

0.3 * 0.2 * 0.1 * 0.05 * ...

几十个小数连续相乘会变成 0。

log 形式可以通过相加避免溢出：

复制代码

log(0.3) + log(0.2) + ...

(2) 数值稳定，更易比较

log space 更线性，梯度优化更稳定。

(3) 便于累计句子的总概率

log 概率可以直接相加。

4. 如何使用 API 获取 logprobs（Python 实战）

下面是最小可运行示例：

python 复制代码

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello, how are you?"}],
    logprobs=5  # 获取 top-5 候选 token 的 logprobs
)

print(response)

5. 返回结构详解

典型返回结构（简化）：

json 复制代码

{
  "choices": [
    {
      "message": {
        "content": "I'm good, thanks!"
      },
      "logprobs": {
        "content": [
          {
            "token": "I",
            "logprob": -0.01,
            "top_logprobs": [
              {"token": "I", "logprob": -0.01},
              {"token": "We", "logprob": -2.31},
              {"token": "It", "logprob": -3.92}
            ]
          },
          ...
        ]
      }
    }
  ]
}

字段说明：

字段	说明
`token`	模型最终选择的 token
`logprob`	该 token 的对数概率
`top_logprobs`	top-N 候选 token 及其 logprob

6. logprobs 的四大典型场景

① 评估模型输出的置信度

低 logprob 表示模型"不确定"。

② 做评分与候选答案比较

可以用 logprob 对不同回答排序。

③ 审核系统（辨别幻觉）

低概率 token 往往是模型"瞎说"的信号。

④ 查看模型下一步"想说什么"

可以观察 top-N 候选 token，了解模型语言习惯。

7. 计算整句的总体置信度（Python 示例）

模型输出多个 token，我们可以将它们的 logprob 相加得到整体分数：

python 复制代码

import math

def total_logprob(logprob_list):
    return sum(logprob_list)

# 假设模型输出 tokens 的 logprob
logprobs = [-0.01, -0.12, -0.03, -1.2]

score = total_logprob(logprobs)
print("Total log probability:", score)

如果需要获得"句子概率"：

python 复制代码

prob = math.exp(score)
print("Sentence probability:", prob)

8. 用 logprobs 分析模型"下一步想说什么"

查看 top_logprobs：

python 复制代码

for item in response.choices[0].logprobs.content:
    print("Token:", item["token"])
    for alt in item["top_logprobs"]:
        print("  Candidate:", alt["token"], "logprob:", alt["logprob"])

用途：

调试 prompt
理解语言模式
推断模型是否走错方向

9. 可视化 token 概率（Python + Matplotlib）

python 复制代码

import matplotlib.pyplot as plt
import numpy as np

token_data = response.choices[0].logprobs.content[0]["top_logprobs"]

tokens = [t["token"] for t in token_data]
logps = [t["logprob"] for t in token_data]
probs = np.exp(logps)

plt.bar(tokens, probs)
plt.title("Token Probability Distribution")
plt.ylabel("Probability")
plt.show()

10. 常见陷阱与工程建议

(1) logprobs 越高越好吗？

不是。不同上下文的对比意义不同。

(2) 注意 tokenization 差异

"logprobs" 总是面向 token 不是字符。

(3) 不能直接跨模型比较 logprob

例如 GPT-4 与 GPT-4o 的 logprob 空间不一致。

(4) logprobs 会增加 API 返回的数据量

需要做好序列化、存储、日志压缩等措施。

总结

logprobs 能让我们从"黑盒输出"进入"可解释生成"的深层能力，适用于：

研究模型决策行为
解析模型置信度
构建安全审查系统
NLP 研究（perplexity、得分候选）
提升 prompt 质量

结合本文的数学原理、API 调用、代码实战与可视化示例，你已经可以系统性使用 logprobs 进行调试与研究。