EP07. "扩展思考、图片、PDF 与引用溯源"

• Extended Thinking 是 Claude 的"草稿纸"——让它先把推理过程写出来再给答案，能提升复杂问题的准确度，但会拉高成本和延迟,官方建议先不开，等 prompt 已经优化到位、准确度还是不够时才考虑开
• 图片和 PDF 在 API 里的用法几乎一样,都是往 content 列表里加一个 block，差别只在 type 字段（"image" vs "document"）跟 media type
• Citations（引用溯源）能让 Claude 的每句话都能追溯回文档里具体是哪一段——只要在文档 block 里加两个字段就能开启，不用额外训练或写复杂逻辑
• 图片有硬性限制：单张最大 5MB、单张最长边 8000px（多图时降到 2000px）、一次最多 100 张,token 成本公式是「宽 px × 高 px ÷ 750」
• 前置知识：读过 [EP01](./EP01_claude-api基础入门.md) 的 messages.create() 基本用法；这篇笔记假设你已经会自己维护 messages 列表

重点内容

Extended Thinking：给 Claude 一张草稿纸

Extended Thinking 让 Claude 在给出最终答案前，先把推理过程写出来——回应里同时包含"怎么想的"和"最终答案"两部分，既提升透明度，复杂问题的答案品质通常也更好。

chat() 函数加两个新参数：

def chat(
    messages,
    system=None,
    temperature=1.0,
    stop_sequences=[],
    tools=None,
    thinking=False,
    thinking_budget=1024
):

开启时的 API 配置：

if thinking:
    params["max_tokens"] = thinking_budget + 1000
    params["thinking"] = {
        "type": "enabled",
        "budget_tokens": thinking_budget
    }

调用：

chat(messages, thinking=True)

代价与好处对比：

几个硬限制：

• 回应里会带一个加密 token，用来确保"思考过程的文字没有被你篡改过"
• budget_tokens 最低要设 1024
• max_tokens 必须大于 budget_tokens
• ⚠️ Extended Thinking 跟 assistant message prefill 不兼容（不能同时用），对 temperature 的使用也有额外限制

Image Support：给 Claude 看图

硬性限制：

往 user message 里加一个 image block，跟 text block 并列：

with open("image.png", "rb") as f:
    image_bytes = base64.standard_b64encode(f.read()).decode("utf-8")

add_user_message(messages, [
    # Image Block
    {
        "type": "image",
        "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": image_bytes,
        }
    },
    # Text Block
    {
        "type": "text",
        "text": "What do you see in this image?"
    }
])

• 拆步骤：把分析过程拆成编号步骤，一步步引导 Claude 看图
• One-shot 范例：给一张已知答案的参考图，示范该怎么判断
• 具体指引：不要只问一句笼统的问题，改成结构化的分析框架

实战案例：火灾风险评估：用卫星图片自动评估房产周边的火灾风险，指示 Claude 系统性地找出植被隐患、防火隔离带够不够、再按具体标准打出 1-4 级风险评分——这种「结构化分析框架」比一句「这张图有什么风险」有效得多。

PDF Support：直接丢 PDF 给 Claude

PDF 处理跟图片处理的写法几乎一样，只是几个字段名不同：

with open("earth.pdf", "rb") as f:
    file_bytes = base64.standard_b64encode(f.read()).decode("utf-8")

messages = []

add_user_message(
    messages,
    [
        {
            "type": "document",
            "source": {
                "type": "base64",
                "media_type": "application/pdf",
                "data": file_bytes,
            },
        },
        {"type": "text", "text": "Summarize the document in one sentence"},
    ],
)

chat(messages)

从图片代码改成 PDF 代码，四处要改：

Claude 能从 PDF 里提取：正文文字、内嵌的图片和图表、表格和数据关系、以及文档本身的结构/排版信息。官方示范用一篇存成 PDF 的维基百科「地球」条目做测试，效果良好。

Citations：让每句话都能溯源

Citations 解决的是「这句话到底是从文档哪里来的」这个透明度问题——建立一条从 Claude 的回答，直接追溯回原始文档的清楚路径。

开启方式：在 document block 上加两个字段：

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": file_bytes,
    },
    "title": "earth.pdf",
    "citations": { "enabled": True }
}

• title：给这份文档一个可读的名字
• citations: {"enabled": True}：开启引用追踪

开启后回应里会带的信息：

纯文字来源也能用 Citations：

{
    "type": "document",
    "source": {
        "type": "text",
        "media_type": "text/plain",
        "data": article_text,
    },
    "title": "earth_article",
    "citations": { "enabled": True }
}

什么时候值得开 Citations：用户需要自己核实内容、需要引用权威文档当依据、透明度本身很重要、或者用户可能想进一步查看更完整的上下文。

常见错误

• ❌ 一上来就默认开 Extended Thinking——先跑没开的版本、prompt 也优化过了，准确度还不够才考虑开，不然平白拉高成本和延迟
• ❌ Extended Thinking 跟 assistant message prefill 一起用——两者不兼容，会出错
• ❌ 多张图片一起传，还照单张图片的 8000px 上限算——多图场景每张的尺寸上限会降到 2000px，容易忘记这个区别
• ❌ 复制图片代码改 PDF 时漏改某个字段——type 忘记从 "image" 改成 "document"，或者 media type 还留着 image/png，会导致请求出错
• ❌ 需要用户核实来源的场景却没开 Citations——多花两行代码（title + citations.enabled）就能让回答可追溯，没理由跳过

Sources

官方文档：

1. Building with the Claude API（Claude Academy 课程）— https://academy.claude.com/courses/building-with-the-claude-api