您是否曾希望了解 Gemini 模型为何选择某个词而非另一个词？对于构建复杂应用程序的开发者来说，理解模型的决策过程至关重要。现在，这一设想已成为现实。模型的推理过程不再是黑箱。Vertex AI 上的 Gemini API 正式引入了 logprobs 功能，让您能够更深入地了解模型的选择。
通过使用此功能，您可查看所选 token 及其最佳替代方案的概率得分，从而对模型的推理过程获得前所未有的认知。这不仅仅是一个调试工具，更是一种构建更智能、更可靠、更具情境感知能力的应用程序的方法。
这篇博文将逐步引导您完成“Logprobs 简介”笔记本，向您展示如何启用此功能并将其应用于强大的用例，如置信分类、动态自动补全和定量 RAG 评估。
首先，准备好环境以便顺利推进。
%pip install -U -q google-genai2. 配置您的项目：设置您的 Google Cloud 项目 ID 和位置。本教程使用这些凭据来验证您的环境。
PROJECT_ID = "[your-project-id]"3. 初始化客户端和模型：创建与 Vertex AI API 交互的客户端，并指定您想要使用的 Gemini 模型。
from google import genai
client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")
MODEL_ID = "gemini-2.5-flash"在启用此功能之前，让我们先明确一下什么是“对数概率”。对数概率是指模型对一个 token 所赋予的概率得分的自然对数值。
以下是关键概念：
因此，logprob 分数越接近 0，表明模型对其选择的置信度越高。
您可以通过在请求的 generation_config 中设置两个参数来启用对数概率。
response_logprobs=True：此选项指示模型返回其输出中所选 token 的对数概率。其默认值为 False。logprobs=[integer]：此选项要求模型在每一步还返回指定数量的最优替代 token 的对数概率。范围在 1 到 20 之间。
让我们通过一个简单的分类提示来演示一下。我们将要求模型将一个句子分类为“Positive”、“Negative”或“Neutral”。
from google.genai.types import GenerateContentConfig
prompt = "I am not sure if I really like this restaurant a lot."
response_schema = {"type": "STRING", "enum": ["Positive", "Negative", "Neutral"]}
response = client.models.generate_content(
model=MODEL_ID,
contents=prompt,
generation_config=GenerateContentConfig(
response_mime_type="application/json",
response_schema=response_schema,
response_logprobs=True,
logprobs=3,
),
)系统会在响应对象中返回 logprobs 数据。您可以使用辅助函数将这些对数概率以易于阅读的格式进行打印。以下函数详细介绍了模型对生成的响应中每个 token 的预测。
def print_logprobs(response):
"""
Print log probabilities for each token in the response
"""
if response.candidates and response.candidates[0].logprobs_result:
logprobs_result = response.candidates[0].logprobs_result
for i, chosen_candidate in enumerate(logprobs_result.chosen_candidates):
print(
f"Token: '{chosen_candidate.token}' ({chosen_candidate.log_probability:.4f})"
)
if i < len(logprobs_result.top_candidates):
top_alternatives = logprobs_result.top_candidates[i].candidates
alternatives = [
alt
for alt in top_alternatives
if alt.token != chosen_candidate.token
]
if alternatives:
print("Alternative Tokens:")
for alt_token_info in alternatives:
print(
f" - '{alt_token_info.token}': ({alt_token_info.log_probability:.4f})"
)
print("-" * 20)假设模型返回以下内容：
2. 备选 token：
该输出显示模型对其选择“Neutral”具有高度置信度，因为其对数概率 (-0.0214) 非常接近 0；而替代选项“Positive”和“Negative”的对数概率则显著更低（即负值更高），这表明模型认为它们出现的可能性要小得多。
logprobs 将分类过程从简单的答案转变成清晰的决策，使您能够构建更稳固的系统。
场景：您需要自动执行分类任务，但同时还需要标记模型不够确定的模糊情况。
为什么使用 Logprobs？：前两个对数概率值之间的微小差异表明存在模糊性。您可以将此差异与一个阈值进行比较，以决定是否需要人工审查。
笔记本中的 check_for_ambiguity 函数会计算首选选项和次选选项的对数值概率之间的绝对差值。如果此差值小于预设的 ambiguity_margin，则将结果标记为模糊。
场景：对于关键应用，您只希望在模型的置信度超过一定水平（例如 90%）时接受分类。
为什么使用 Logprobs？：Logprobs 可以直接衡量模型的置信度。您可以将所选 token 的对数概率转换回原始概率分数，以便应用阈值。
accept_if_confident 函数通过使用 math.exp() 将 logprob 转换为概率百分比，并随后检查其是否高于某个阈值，以此来说明这一点。
场景：您想要开发一个自动补全功能，当用户输入内容时，该功能能够针对最有可能的后续单词给出建议。
为什么使用 Logprobs？：通过用不断增长的文本对模型进行多次查询，并仔细分析最有可能的候选选项的对数概率，您便能够观察到模型预测的转变，并提供相关且实时的建议。
此笔记本模拟了用户逐字输入“The best thing about living in Toronto is the”这样的过程。随着上下文的扩展，对于下一个单词的建议会变得更加具体和准确：
分析：
这表明，logprobs 能帮助您深入了解模型的语境理解能力，从而让您能够构建出更具适应性和情境感知性的功能。
场景：您有一个 RAG 系统，需要评估其给出的答案在多大程度上得到了检索到的相关背景信息的支持。
为什么使用 Logprobs？：当 LLM 拥有相关上下文时，其生成事实一致性答案的置信度会提升，这种现象表现为更高的对数概率。您可通过计算生成答案的平均对数概率，获得“事实依据分”或“信任值分数”。
笔记本建立了一个虚构的知识库，并测试了三种场景：良好检索、不良检索和无检索。
分析：
结果显示出明显的相关性。“良好检索”场景得分最高（最接近 0），因为模型非常确信其答案得到了文本的支持。因此，logprobs 成为自动评估和改进 RAG 系统的强大指标。
现在，您已经学习了如何使用 logprobs 功能深入了解模型的决策过程。我们介绍了如何应用这些洞察来分析分类结果、构建动态自动补全功能以及评估 RAG 系统。
这些只是一些示例应用程序，通过此功能，开发者可以探索更多用例。
如要深入了解，请浏览完整的笔记本并查阅官方文档：
