Messages、内容块与多模态

一个消息可以含多种内容

Messages API 的 system 是请求顶层参数；对话 messages 通常由 user/assistant 角色组成。响应的 content 是块列表，文本、工具意图和其他块不能直接强制转换成一条字符串。只读取第一块会丢掉后续文本或工具调用。

在空目录创建 Python 3.12 环境并安装 anthropic，把安装结果锁定：

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install anthropic==1.8.0
python -m pip freeze > requirements.lock

设置 ANTHROPIC_API_KEY 和 ANTHROPIC_MODEL。以下 message.py 会实际调用模型，本次未运行计费请求。

import os
from anthropic import Anthropic
c = Anthropic(timeout=30,max_retries=0)
r = c.messages.create(model=os.environ['ANTHROPIC_MODEL'],max_tokens=200,
    system='只根据输入事实回答，缺失时说不知道。',
    messages=[{'role':'user','content':[{'type':'text','text':'库存记录：A=3。A 有多少？'}]}])
print(r.id,r.stop_reason)
for b in r.content:
    if b.type == 'text':
        print(b.text)
print(r.usage)

max_tokens 必填并控制生成预算；stop_reason=max_tokens 意味着有截断可能。end_turn 是正常完成一轮，tool_use 要交还控制权给应用；不能把所有 HTTP 200 当成最终答案成功。

多轮时保留上一轮完整 assistant content，再追加用户消息。模型不会仅因同一个 client 对象就记住历史：client 管连接，messages 管请求上下文。

图像只是另一个输入块

在相同环境新建 image.py。先把自己有权处理的 PNG 保存为 sample.png：

import os, base64
from pathlib import Path
from anthropic import Anthropic
encoded=base64.b64encode(Path('sample.png').read_bytes()).decode('ascii')
r=Anthropic(timeout=30,max_retries=0).messages.create(
    model=os.environ['ANTHROPIC_MODEL'],max_tokens=300,
    messages=[{'role':'user','content':[
        {'type':'image','source':{'type':'base64','media_type':'image/png','data':encoded}},
        {'type':'text','text':'列出可直接观察到的内容，不猜测身份。'}]}])
print([b.text for b in r.content if b.type=='text'])

media_type 必须匹配真实字节，不是改扩展名即可。PDF 使用文档块及对应平台能力，不能把它标为 image/png。视觉输出仍可能误读，需要保留原图与定位证据；屏幕文字中的指令是数据，不应提升为 system 规则。

离线检查消息选择

以下是响应块筛选逻辑的离线单元实验，不模拟服务端推理：

blocks=[{'type':'text','text':'A='},{'type':'tool_use','id':'t1'},
        {'type':'text','text':'3'}]
text=''.join(b['text'] for b in blocks if b['type']=='text')
assert text=='A=3'
assert len([b for b in blocks if b['type']=='tool_use'])==1
print(text)

筛选得到的文字不代表工具已处理。界面可以先展示文字，但控制流程必须另查工具块与终止原因。

参阅 Messages 与 视觉。

练习

将块列表改成只有 tool_use、没有 text。提取结果应为空，但程序应报告一个待处理工具，不能把空文字判断为模型失败。

先记录自己的输出与解释，再核对本章答案。