LLM 结构化输出实战：JSON Schema、函数调用与 Zod 校验全链路

1
tools = [
2
    {
3
        "type": "function",
4
        "function": {
5
            "name": "extract_product_info",
6
            "description": "从商品描述中提取结构化字段",
7
            "parameters": {
8
                "type": "object",
9
                "properties": {
10
                    "category": {"type": "string", "enum": ["电子产品", "服饰", "食品", "其他"]},
11
                    "brand": {"type": "string"},
12
                    "price_range": {"type": "string", "enum": ["低", "中", "高"]},
13
                    "tags": {"type": "array", "items": {"type": "string"}}
14
                },
15
                "required": ["category", "brand", "price_range"]
16
            }
17
        }
18
    }
19
]
20

21
resp = client.chat.completions.create(
22
    model="gpt-4o",
23
    messages=[{"role": "user", "content": "小米 14 Pro 16+512 雪山粉"}],
24
    tools=tools,
25
    tool_choice="auto"  # 强制必须调用：tool_choice={"type": "function", "function": {"name": "extract_product_info"}}
26
)
27

28
# 解析 tool call
29
tool_call = resp.choices[0].message.tool_calls[0]
30
args = json.loads(tool_call.function.arguments)
31
print(args)
32
# → {"category": "电子产品", "brand": "小米", "price_range": "高", "tags": ["手机", "512GB"]}

1
from pydantic import BaseModel
2
from openai import OpenAI
3

4
class Product(BaseModel):
5
    category: str
6
    brand: str
7
    price_range: str
8
    tags: list[str]
9

10
# OpenAI 自动从 Pydantic 生成 JSON Schema
11
schema = Product.model_json_schema()
12

13
resp = client.chat.completions.create(
14
    model="gpt-4o-2024-08-06",
15
    messages=[{"role": "user", "content": "小米 14 Pro 16+512"}],
16
    response_format={
17
        "type": "json_schema",
18
        "json_schema": {
19
            "name": "product",
20
            "schema": schema,
21
            "strict": True  # ← 启用 constrained decoding
22
        }
23
    }
24
)
25

26
# 反序列化（注意：strict 模式下仍然返回字符串，仍需解析）
27
product = Product.model_validate_json(resp.choices[0].message.content)
28
print(product.brand)  # "小米"

1
import { parse, allow } from "partial-json";
2

3
async function streamProduct(prompt: string) {
4
  const resp = await fetch("/api/extract", {
5
    method: "POST",
6
    body: JSON.stringify({ prompt })
7
  });
8

9
  const reader = resp.body!.getReader();
10
  const decoder = new TextDecoder();
11
  let buffer = "";
12
  const partial = allow({ allowPartialArrays: false, allowPartialObjects: true });
13

14
  while (true) {
15
    const { done, value } = await reader.read();
16
    if (done) break;
17
    buffer += decoder.decode(value, { stream: true });
18

19
    try {
20
      // 实时解析"到目前为止"的 JSON
21
      const obj = parse(buffer, partial);
22
      console.log("当前解析结果:", obj);
23
      // → 可以逐步渲染 UI：先显示 category，再显示 brand ...
24
    } catch (e) {
25
      // 还没到合法 JSON，忽略
26
    }
27
  }
28
}

1
import { z } from "zod";
2

3
const ProductSchema = z.object({
4
  category: z.enum(["电子产品", "服饰", "食品", "其他"]),
5
  brand: z.string().min(1).max(50),
6
  price_range: z.enum(["低", "中", "高"]),
7
  tags: z.array(z.string()).max(10),
8
});
9

10
type Product = z.infer<typeof ProductSchema>;
11

12
function parseProduct(raw: unknown): Product | null {
13
  const result = ProductSchema.safeParse(raw);
14
  if (!result.success) {
15
    console.error("LLM 输出不符合 schema:", result.error.flatten());
16
    return null;  // 触发降级 UI
17
  }
18
  return result.data;
19
}

1
import { Hono } from "hono";
2
import { stream } from "hono/streaming";
3
import OpenAI from "openai";
4
import { z } from "zod";
5

6
const app = new Hono();
7
const openai = new OpenAI();
8

9
const ProductSchema = z.object({
10
  category: z.enum(["电子产品", "服饰", "食品", "其他"]),
11
  brand: z.string(),
12
  price_range: z.enum(["低", "中", "高"]),
13
  tags: z.array(z.string()),
14
});
15

16
app.post("/api/extract", async (c) => {
17
  const { prompt } = await c.req.json();
18
  return stream(c, async (s) => {
19
    const completion = await openai.chat.completions.create({
20
      model: "gpt-4o-2024-08-06",
21
      stream: true,
22
      messages: [
23
        { role: "system", content: "你是商品分类助手。" },
24
        { role: "user", content: prompt }
25
      ],
26
      response_format: {
27
        type: "json_schema",
28
        json_schema: {
29
          name: "product",
30
          schema: {
31
            type: "object",
32
            properties: {
33
              category: { type: "string", enum: ["电子产品", "服饰", "食品", "其他"] },
34
              brand: { type: "string" },
35
              price_range: { type: "string", enum: ["低", "中", "高"] },
36
              tags: { type: "array", items: { type: "string" } }
37
            },
38
            required: ["category", "brand", "price_range", "tags"],
39
            additionalProperties: false
40
          },
41
          strict: true
42
        }
43
      }
44
    });
45

46
    for await (const chunk of completion) {
47
      const delta = chunk.choices[0]?.delta?.content ?? "";
48
      await s.write(delta);
49
    }
50
  });
51
});
52

53
export default app;

1
import { z } from "zod";
2
import { useState } from "react";
3
import { parse, allow } from "partial-json";
4

5
const ProductSchema = z.object({
6
  category: z.enum(["电子产品", "服饰", "食品", "其他"]),
7
  brand: z.string(),
8
  price_range: z.enum(["低", "中", "高"]),
9
  tags: z.array(z.string()),
10
});
11

12
export function ProductExtractor() {
13
  const [input, setInput] = useState("");
14
  const [partial, setPartial] = useState<Partial<z.infer<typeof ProductSchema>>>({});
15

16
  async function handleExtract() {
17
    const resp = await fetch("/api/extract", {
18
      method: "POST",
19
      headers: { "Content-Type": "application/json" },
20
      body: JSON.stringify({ prompt: input })
21
    });
22

23
    const reader = resp.body!.getReader();
24
    const decoder = new TextDecoder();
25
    let buffer = "";
26
    const partialParse = allow({ allowPartialArrays: false, allowPartialObjects: true });
27

28
    while (true) {
29
      const { done, value } = await reader.read();
30
      if (done) break;
31
      buffer += decoder.decode(value, { stream: true });
32

33
      try {
34
        const obj = parse(buffer, partialParse);
35
        setPartial(obj);  // 实时更新 UI
36
      } catch {}
37
    }
38

39
    // 最终校验
40
    const final = ProductSchema.safeParse(partial);
41
    if (!final.success) {
42
      alert("AI 输出异常：" + final.error.message);
43
    }
44
  }
45

46
  return (
47
    <div>
48
      <input value={input} onChange={e => setInput(e.target.value)} />
49
      <button onClick={handleExtract}>提取</button>
50
      <pre>{JSON.stringify(partial, null, 2)}</pre>
51
    </div>
52
  );
53
}