Phase 13: Tools & Protocols

Kết quả cấu trúc JSON Schema, Pydantic, Zod, Khóa mã bị hạn chế

Type: Build

Languages: Python (stdlib, JSON Schema 2020-12 subset)

Prerequisites: Phase 13 · 02 (function calling deep dive)

Time: ~75 minutes

Mục tiêu học tập

• Viết một JSON Schema 2020-12 cho mục tiêu khai thác bằng cách sử dụng các hạn chế đúng (enum, min/max, yêu cầu, mô hình).
• Giải thích tại sao chế độ nghiêm ngặt và mã hóa hạn chế cung cấp các đảm bảo khác với "sự xác thực sau thế hệ".
• Hóa ra ba chế độ thất bại: lỗi phân tích, vi phạm sơ đồ, từ chối mô hình.
• Chuyển một đường ống khai thác với sửa chữa kiểu và xử lý từ chối kiểu.

Vấn đề

Một đại lý đọc email đặt hàng mua cần biến văn bản miễn phí thành {customer, line_items, total_usd}Ba cách tiếp cận.

Approach one: prompt for JSON."Câu trả lời trong JSON với các trường khách hàng, line_items, total_usd. " Làm việc 85 đến 95% thời gian trên các mô hình biên giới. thất bại theo sáu cách: không có dấu chấm, dấu ngoặc sau, loại sai, các trường ảo giác, bị cắt ngắn ở giới hạn token, rò rỉ văn bản như "Đây là JSON của bạn:".

Approach two: validate after generation.Tạo tự do, phân tích, xác nhận chống lại schema, thử lại khi thất bại. đáng tin cậy nhưng đắt tiền bạn trả tiền cho mỗi lần thử lại, và lỗi cắt giảm chi phí thêm một lượt mỗi lần xảy ra.

Approach three: constrained decoding.Nhà cung cấp thực thi kế hoạch tại thời điểm giải mã. Các token không hợp lệ được che giấu khỏi phân phối lấy mẫu. Kết quả được đảm bảo phân tích và đảm bảo xác nhận. Sự thất bại sụp đổ thành một chế độ: từ chối (chương trình quyết định đầu vào không phù hợp với kế hoạch).

Mỗi nhà cung cấp biên giới năm 2026 sẽ đưa ra một số cách tiếp cận thứ ba.

• OpenAI. response_format: {type: "json_schema", strict: true}+refusaltrong phản ứng nếu mô hình giảm.
• Anthropic.Việc thực thi quy định trên tool_useđầu vào; stop_reason: "refusal"không phải là một thứ, nhưng end_turnKhông có công cụ gọi là tín hiệu.
• Gemini. responseSchematheo yêu cầu; vào năm 2026 Gemini sẽ đưa ra các hạn chế ngữ pháp cấp token cho các loại đã chọn.
• Pydantic AI. output_type=InvoiceModelphát ra một cấu trúc RunResultđược đánh dấu theo InvoiceModel- Tôi không biết.
• Zod (TypeScript).Chân tích thời gian chạy xác nhận đầu ra của nhà cung cấp với một chương trình Zod; kết hợp với OpenAI beta.chat.completions.parse- Tôi không biết.

Điểm chung: tuyên bố sơ đồ một lần, thực thi nó cuối đến cuối.

Khái niệm

JSON Schema 2020-12 ngôn ngữ ngoại ngữ

Mỗi nhà cung cấp chấp nhận JSON Schema 2020-12. Các cấu trúc bạn sử dụng nhiều nhất:

• type: một trong số object- array- string- number- integer- boolean- null- Tôi không biết.
• properties: bản đồ tên trường đến phụ đề.
• required: danh sách tên trường phải xuất hiện.
• enum: tập hợp các giá trị được phép đóng.
• minimum- maximum(tương tự số),minLength- maxLength- pattern(câu)
• items: các phụ quy trình áp dụng cho mọi yếu tố array.
• additionalPropertiesfalsecấm các trường bổ sung (tầm định thay đổi theo chế độ).

Khóa chế độ khắt khe OpenAI bổ sung ba yêu cầu: mọi tài sản phải được liệt kê trong required- additionalProperties: falsekhắp nơi, và không có bất cứ điều gì chưa được giải quyết $refNếu bạn phá vỡ những thứ này, API sẽ trả lại 400 vào thời điểm yêu cầu.

Pydantic, liên kết Python

Pydantic v2 tạo ra JSON Schema từ các mô hình hình dạng lớp dữ liệu thông qua model_json_schema()Pydantic AI gói lại cái này để bạn viết:

pythonCopyclass Invoice(BaseModel):
    customer: str
    line_items: list[LineItem]
    total_usd: Decimal

và khung đại lý dịch các kế hoạch vào OpenAI chế độ nghiêm ngặt, Anthropic input_schema, hoặc Gemini responseSchemaTạo ra mô hình trở lại như một kiểu chữ Invoiceví dụ. lỗi xác thực tăng ValidationErrorvới các đường lối lỗi nhập.

Zod, TypeScript liên kết

Zod (z.object({customer: z.string(), ...})(tương đương với TS).zodResponseFormat(Invoice)Điều này chuyển thành tải trọng JSON Schema của API.

Việc từ chối

Chế độ nghiêm ngặt không thể buộc mô hình trả lời. Nếu đầu vào không phù hợp với sơ đồ ("các email là một bài thơ, không phải một hóa đơn"), mô hình phát ra một refusalmã của bạn phải xử lý điều này như một kết quả hạng nhất, không phải là một thất bại. Việc từ chối cũng hữu ích như một tín hiệu an toàn: một mô hình yêu cầu lấy số thẻ tín dụng từ một email có nội dung được bảo vệ trả lại một từ chối với lý do an toàn kèm theo.

Việc giải mã hạn chế trong công cộng

Các triển khai trọng lượng mở sử dụng ba kỹ thuật.

1. Grammar-based decoding(outlines- guidance- lm-format-enforcer): xây dựng một tự động xác định hữu hạn từ sơ đồ; ở mỗi bước, che giấu các logit của các token sẽ vi phạm FSM.
2. Logit masking with a JSON parser: chạy trình phân tích JSON trực tuyến theo bước khóa với mô hình; tại mỗi bước, tính toán bộ mã thông báo hợp lệ-nhiều tiếp theo.
3. Speculative decoding with a verifier: mô hình dự thảo rẻ tiền đề xuất token, xác minh thực hiện kế hoạch.

Các nhà cung cấp thương mại chọn một trong những điều này sau hậu trường.

Ba chế độ thất bại

1. Parse error.Khả năng xuất không hợp lệ JSON. Không thể xảy ra trong chế độ nghiêm ngặt. vẫn có thể xảy ra trên các nhà cung cấp không nghiêm ngặt.
2. Schema violation.Các đầu ra phân tích nhưng vi phạm sơ đồ. Không thể xảy ra trong chế độ nghiêm ngặt. phổ biến bên ngoài nó.
3. Refusal.Mô hình bị giảm, phải được xử lý như một kết quả được đánh dấu.

Chiến lược thử lại

Khi bạn đang ở ngoài chế độ nghiêm ngặt (phương tiện sử dụng nhân đạo, không nghiêm ngặt OpenAI, Gemini cũ), mô hình phục hồi là:

Copygenerate -> parse -> validate -> if fail, inject error and retry, max 3x

Một lần thử lại thường đủ. Ba lần thử lại bắt được các mảnh mô hình yếu. Hơn ba là dấu hiệu của một kế hoạch xấu: mô hình không thể thỏa mãn nó cho một số đầu vào, và lời nhắc hoặc kế hoạch cần phải sửa chữa.

Hỗ trợ cho mô hình nhỏ

Việc giải mã hạn chế hoạt động trên các mô hình nhỏ. Một mô hình mở 3B tham số với việc thực thi ngữ pháp vượt trội hơn mô hình 70B tham số với sự thúc đẩy nguyên liệu trong các nhiệm vụ có cấu trúc. Đây là lý do chính khiến các sản phẩm có cấu trúc trở nên quan trọng cho sản xuất: nó tách rời độ tin cậy từ kích thước mô hình.

Sử dụng nó

code/main.pygửi một xác thực viên JSON Schema 2020-12 tối thiểu trong stdlib (loại, yêu cầu, enum, min/max, mẫu, mục, tính năng bổ sung). Nó gói Invoiceschema và chạy một sản xuất LLM giả thông qua xác thực, chứng minh lỗi phân tích, vi phạm schema và đường từ chối. Thay đổi sản xuất giả cho phản ứng thực sự của bất kỳ nhà cung cấp nào trong sản xuất.

Những gì cần xem:

• Các xác nhận trả lại một gõ [ValidationError]danh sách với đường dẫn và tin nhắn. Đó là hình dạng bạn muốn xuất hiện trên yêu cầu thử lại.
• Chiếc nhánh từ chối không thử lại. Nó ghi lại và trả lại một từ chối đã nhập.
• - additionalProperties: falsekiểm tra lửa trên đầu vào thử nghiệm đối kháng, cho thấy tại sao chế độ nghiêm ngặt đóng cửa cho các trường ảo giác.

Chuyển nó

Bài học này sẽ mang lại kết quả outputs/skill-structured-output-designer.mdVới mục tiêu khai thác văn bản tự do (phần hóa đơn, vé hỗ trợ, sơ yếu lý lịch, v.v.), kỹ năng tạo ra một JSON Schema 2020-12 tương thích chặt chẽ với chế độ và mô hình Pydantic phản ánh nó, với việc đánh dấu từ chối và xử lý thử lại bị đập vào.

Các bài tập

1. Đi chạycode/main.pyThêm một trường hợp thử nghiệm thứ tư màtotal_usdlà một số âm. xác nhận xác nhận từ chối nó với minimumđường dẫn hạn chế.

1. Tăng độ xác nhận để hỗ trợ oneOfMột trường hợp phổ biến:line_itemlà một sản phẩm hoặc dịch vụ, được dán nhãn bởi kind. chế độ nghiêm ngặt có các quy tắc tinh tế ở đây; kiểm tra hướng dẫn đầu ra có cấu trúc của OpenAI.

1. Viết cùng một sơ đồ hóa đơn như một Pydantic BaseModel và so sánh model_json_schema()phát vào sơ đồ xoay tay của bạn. xác định một trường Pydantic đặt theo mặc định mà phiên bản xoay tay bỏ qua.

1. Đánh giá tỷ lệ từ chối. Xây dựng mười đầu vào không nên được trích xuất (một bài hát, một bằng chứng toán học, một email trống) và chạy chúng thông qua một nhà cung cấp thực tế với chế độ nghiêm ngặt. Đếm từ chối so với các kết quả ảo giác. Đây là sự thật cơ bản của bạn cho các thử nghiệm từ chối.

1. Đọc hướng dẫn đầu ra cấu trúc của OpenAI từ trên xuống. Xác định cấu trúc mà nó cấm rõ ràng trong chế độ nghiêm ngặt mà JSON Schema đơn giản cho phép. Sau đó thiết kế một sơ đồ sử dụng cấu trúc cấm không thiết yếu và tái tạo nó để tương thích chặt chẽ.

Các điều khoản chính

Đọc thêm

• OpenAI — Structured outputs chế độ nghiêm ngặt, từ chối và yêu cầu về kế hoạch
• OpenAI — Introducing structured outputs Tháng 8 năm 2024: thời gian khởi động giải thích bảo đảm giải mã
• Pydantic AI — Output các liên kết output_type được gõ mà liên kết với mỗi nhà cung cấp
• JSON Schema — 2020-12 release notes quy định quy định
• Microsoft — Structured outputs in Azure OpenAI Thông báo triển khai doanh nghiệp và cảnh báo chế độ nghiêm ngặt

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.