結構化輸出:保證拿到合法 JSON

最基本的 Structured Outputs 呼叫

重點在於加入 output_config 參數,其他地方跟一般 messages.create() 完全一樣:

Python:

import anthropic
import json

client = anthropic.Anthropic()  # 自動讀取 ANTHROPIC_API_KEY

# 定義你要的輸出結構
schema = {
    "type": "object",
    "properties": {
        "company_name": {"type": "string"},
        "revenue_million_usd": {"type": "number"},
        "yoy_growth_pct": {"type": "number"},
        "is_profitable": {"type": "boolean"},
        "fiscal_quarter": {"type": "string"}
    },
    "required": [
        "company_name", "revenue_million_usd",
        "yoy_growth_pct", "is_profitable", "fiscal_quarter"
    ],
    "additionalProperties": False  # Python 用 False(大寫)
}

news_text = """
台積電今日公布 2026 年第一季財報,合併營收達 8,350 億新台幣(約 258 億美元),
較去年同期成長 41.6%。單季淨利為 3,615 億新台幣,創歷史新高。
"""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system="你是一位財務資料抽取 AI。從用戶提供的新聞稿中,抽取指定的結構化財務資訊。",
    messages=[
        {"role": "user", "content": f"請從以下新聞稿抽取財務資訊:\n\n{news_text}"}
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": schema
        }
    }
)

# 回應在 response.content[0].text,是一個 JSON 字串,直接解析即可
data = json.loads(response.content[0].text)
print(data)
# {"company_name": "台積電", "revenue_million_usd": 25800.0, "yoy_growth_pct": 41.6, "is_profitable": true, "fiscal_quarter": "2026 Q1"}

JavaScript/TypeScript:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const schema = {
  type: "object" as const,
  properties: {
    company_name: { type: "string" as const },
    revenue_million_usd: { type: "number" as const },
    yoy_growth_pct: { type: "number" as const },
    is_profitable: { type: "boolean" as const },
    fiscal_quarter: { type: "string" as const }
  },
  required: ["company_name", "revenue_million_usd", "yoy_growth_pct", "is_profitable", "fiscal_quarter"],
  additionalProperties: false
};

const newsText = `
台積電今日公布 2026 年第一季財報,合併營收達 8,350 億新台幣(約 258 億美元),
較去年同期成長 41.6%。單季淨利為 3,615 億新台幣,創歷史新高。
`;

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 512,
  system: "你是一位財務資料抽取 AI。從用戶提供的新聞稿中,抽取指定的結構化財務資訊。",
  messages: [
    { role: "user", content: `請從以下新聞稿抽取財務資訊:\n\n${newsText}` }
  ],
  output_config: {
    format: {
      type: "json_schema",
      schema
    }
  }
});

const data = JSON.parse(response.content[0].text);
console.log(data);

注意兩個細節:第一,回應拿到的是 response.content[0].text(字串),你還是要自己 json.loads() / JSON.parse() 一次——Structured Outputs 保證它一定合法,所以這步不會失敗;第二,schema 裡的 additionalProperties 在 Python 要寫 False(大寫),在 JSON 和 JS 裡寫 false。

Pydantic 型別整合(Python 推薦做法)

上面的方式每次都要手寫 schema dict,而且拿回來的是 dict,你後面存取欄位要用 data["company_name"] 而不是 data.company_name。用 Pydantic 可以解決這兩個問題:

from pydantic import BaseModel, Field
from anthropic import Anthropic

client = Anthropic()

class FinancialInfo(BaseModel):
    company_name: str = Field(description="公司名稱")
    revenue_million_usd: float = Field(description="季度營收,單位百萬美元")
    yoy_growth_pct: float = Field(description="年增率,百分比數字,不含 % 符號")
    is_profitable: bool = Field(description="本季是否獲利")
    fiscal_quarter: str = Field(description="財報季度,例如 2026 Q1")

news_text = """
台積電今日公布 2026 年第一季財報,合併營收達 8,350 億新台幣(約 258 億美元),
較去年同期成長 41.6%。單季淨利為 3,615 億新台幣,創歷史新高。
"""

# 用 .parse() 方法,傳入 Pydantic model class
response = client.messages.parse(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system="你是一位財務資料抽取 AI。從用戶提供的新聞稿中,抽取指定的結構化財務資訊。",
    messages=[
        {"role": "user", "content": f"請從以下新聞稿抽取財務資訊:\n\n{news_text}"}
    ],
    output_format=FinancialInfo  # 直接傳 class,SDK 自動轉成 schema
)

# response.parsed_output 就是一個 FinancialInfo 實例,有完整型別提示
info = response.parsed_output
print(info.company_name)        # "台積電"
print(info.revenue_million_usd) # 25800.0
print(info.is_profitable)       # True
print(type(info))               # <class '__main__.FinancialInfo'>

兩個關鍵差異:第一,用 .parse() 而不是 .create();第二,用 output_format= 參數傳入 Pydantic class。SDK 會自動把 Pydantic model 轉成 JSON Schema 傳給 API,回應也會自動用 Pydantic 驗證並建構成物件。

Field(description="...") 是可選的,但強烈建議加——這段 description 會進入 schema 成為 API 的一部分,讓 Claude 更精確理解每個欄位的語意。

TypeScript Zod 整合

JavaScript 端對應的做法是用 Zod:

import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import { z } from "zod";

const client = new Anthropic();

const FinancialInfoSchema = z.object({
  company_name: z.string().describe("公司名稱"),
  revenue_million_usd: z.number().describe("季度營收,單位百萬美元"),
  yoy_growth_pct: z.number().describe("年增率,百分比數字,不含 % 符號"),
  is_profitable: z.boolean().describe("本季是否獲利"),
  fiscal_quarter: z.string().describe("財報季度,例如 2026 Q1")
});

type FinancialInfo = z.infer<typeof FinancialInfoSchema>;

const newsText = `
台積電今日公布 2026 年第一季財報,合併營收達 8,350 億新台幣(約 258 億美元),
較去年同期成長 41.6%。單季淨利為 3,615 億新台幣,創歷史新高。
`;

const response = await client.messages.parse({
  model: "claude-sonnet-4-6",
  max_tokens: 512,
  system: "你是一位財務資料抽取 AI。從用戶提供的新聞稿中,抽取指定的結構化財務資訊。",
  messages: [
    { role: "user", content: `請從以下新聞稿抽取財務資訊:\n\n${newsText}` }
  ],
  output_config: { format: zodOutputFormat(FinancialInfoSchema) }
});

// response.parsed_output 是完整型別的物件
const info: FinancialInfo = response.parsed_output;
console.log(info.company_name);         // "台積電"
console.log(info.revenue_million_usd);  // 25800

注意 JS 版用的是 output_config: { format: zodOutputFormat(...) } 而不是 output_format=——兩種語言的 API 略有不同,要看清楚。

實戰:處理巢狀結構與陣列欄位

真實場景往往需要更複雜的結構。假設你要從同一篇新聞稿同時抽取多個提到的公司,或是抽取帶有子物件的層次資料:

from pydantic import BaseModel, Field
from typing import Optional
from anthropic import Anthropic

client = Anthropic()

class Competitor(BaseModel):
    name: str = Field(description="競爭對手名稱")
    mentioned_revenue_billion_usd: Optional[float] = Field(
        default=None,
        description="如有提及營收,單位為十億美元;若未提及則為 null"
    )

class NewsAnalysis(BaseModel):
    primary_company: str = Field(description="新聞主角公司名稱")
    quarter: str = Field(description="財報季度")
    revenue_billion_usd: float = Field(description="主角公司營收,單位十億美元")
    yoy_growth_pct: float = Field(description="年增率,純數字")
    key_highlights: list[str] = Field(description="3 到 5 條重點摘要,每條一句話")
    competitors_mentioned: list[Competitor] = Field(
        default_factory=list,
        description="新聞中有被提及的競爭對手列表,若無則為空陣列"
    )

long_news = """
台積電今日公布 2026 年第一季財報,合併營收達 258 億美元,年增 41.6%。
單季淨利創歷史新高,毛利率維持在 58% 以上。
法說會上,台積電表示 AI 相關需求持續超出預期,先進製程訂單能見度已達年底。
三星電子同期財報出現虧損,英特爾晶圓代工部門營收約 45 億美元。
台積電預估次季營收將達 280-290 億美元,成長動能不減。
"""

response = client.messages.parse(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="你是一位財務新聞分析 AI。從新聞稿中抽取結構化分析資料。",
    messages=[
        {"role": "user", "content": f"請分析以下新聞稿:\n\n{long_news}"}
    ],
    output_format=NewsAnalysis
)

result = response.parsed_output
print(result.primary_company)
print(result.key_highlights)           # ['AI 需求超預期', '毛利率 58% 以上', ...]
print(result.competitors_mentioned)    # [Competitor(name='三星電子', ...), ...]

# 存進資料庫或序列化
import json
print(result.model_dump_json(indent=2))

幾個在複雜 schema 裡的技巧:

• 用 Optional[float] + default=None 讓欄位可以是 null,搭配 description 告訴 Claude 什麼時候填 null
• 用 list[str] 或 list[Competitor] 定義陣列欄位
• 用 default_factory=list 讓 Claude 在沒有相關資訊時回傳空陣列而不是省略欄位
• Pydantic 的 .model_dump_json() 可以直接序列化整個結果