大模型 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 实战）

下面是最小可运行示例：

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. 返回结构详解

典型返回结构（简化）：

{
  "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 相加得到整体分数：

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)

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

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

---

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

查看 top_logprobs：

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）

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 进行调试与研究。