Навязывание структурированного вывода через tool use и JSON-схемы

Суть

Tool use устраняет синтаксические ошибки JSON, но не семантические (неверные значения, несходящиеся суммы, не туда положенные данные). JSON-схема не выражает межполевую арифметику — нужна отдельная семантическая валидация.

tool_choice и nullable-поля

Три режима: auto (опционально), any (обязан вызвать), форс конкретного инструмента. Для гарантированного извлечения нужен any или форс, не auto. Nullable-поля предотвращают галлюцинации, когда информации в источнике нет. Паттерн «other + строка-деталь» даёт расширяемые enum для неизвестных категорий.

Извлечение через tool use с tool_choice и nullable-полями

extractInvoice := map[string]any{
	"name": "extract_invoice",
	"input_schema": map[string]any{
		"type": "object",
		"properties": map[string]any{
			"vendor":       map[string]any{"type": "string"},                  // обязательное
			"total":        map[string]any{"type": "number"},                  // обязательное
			"invoice_date": map[string]any{"type": []string{"string", "null"}}, // nullable: нет даты -> null
			"po_number":    map[string]any{"type": []string{"string", "null"}},
			"invoice_type": map[string]any{
				"type": "string",
				"enum": []string{"standard", "credit_note", "other"},
			},
			"invoice_type_detail": map[string]any{"type": []string{"string", "null"}},
		},
		"required": []string{"vendor", "total"},
	},
}

client.CreateMessage(MessageRequest{
	Model:      "claude-opus-4-8",
	Tools:      []map[string]any{extractInvoice},
	ToolChoice: map[string]any{"type": "any"}, // гарантированный вызов инструмента
	Messages:   []Message{{Role: "user", Content: document}},
})

Anti-patterns

Ловушка	Почему не работает	Верный паттерн
`tool_choice: "auto"`, когда нужен структурированный вывод	`auto` позволяет вернуть текст — извлечение не гарантировано	`any` или форс конкретного инструмента
Пометить все поля обязательными ради полноты	Обязательность на опциональном вынуждает галлюцинацию вместо null	Обязательны лишь реально нужные; опциональные — nullable
Считать, что валидация схемы убирает все ошибки извлечения	Схема убирает только синтаксис; семантика проходит валидацию	Добавить семантический слой: суммы, диапазоны дат, согласованность полей

Exam traps

Ловушка	Почему не работает	Верный паттерн
Считать `auto` гарантией извлечения	`auto` разрешает текст	`any`/форс для гарантии
Обязательные поля на опциональной информации	Вынуждает галлюцинацию	Nullable-типы
Схема как полное устранение ошибок	Она только синтаксическая	Добавить семантическую валидацию

Практическое задание (T3)

Определить инструмент извлечения счёта: обязательные (vendor, total), nullable (date, PO), enum с other для типа.
Тест с tool_choice: "auto" — увидеть, когда Claude возвращает текст; переключить на any и подтвердить 100% вызовов.
Намеренно создать документ, где позиции не сходятся в total; проверить, что схема принимает вывод; добавить пост-валидацию.
Тест с документом без даты — nullable-поле возвращает null, а не выдуманную дату.
Тест форса: tool_choice: {"type":"tool","name":"extract_metadata"} — исполняется только он.

Проверка знаний

Извлечение структурированных данных

После перехода на tool use со строгой JSON-схемой синтаксические ошибки JSON исчезли, но в счетах позиции по-прежнему не сходятся в итог. Причина?

A Схема недостаточно строга — добавить min/max в поле total_amount
B Описания инструмента неясны — переписать, объяснив, что позиции должны давать итог
C Tool use убирает синтаксис, но не семантику — нужен отдельный слой валидации
D Модели нужно большее окно, чтобы обработать позиции и итог за один проход

Извлечение структурированных данных

Конвейер обрабатывает три типа документов (счета, контракты, заказы) с разными схемами; тип заранее неизвестен. Нужно гарантированное извлечение. Какой tool_choice?

A tool_choice: "auto" — модель выберет подходящий инструмент
B tool_choice: "any" — обязана вызвать один из инструментов, не может вернуть текст, выбирает подходящий
C tool_choice: {"type":"tool","name":"extract_invoice"} — форсировать инструмент счёта на всех
D Без tool_choice; указать в system prompt

Извлечение структурированных данных

Извлечение контрактов со строгой схемой проходит 100% валидации, но 18% отклоняются юристами, потому что ключевые связи неверны (например, termination_date раньше start_date). Что сделать?

A Перейти с tool use на markdown-JSON с инструкциями по формату
B Добавить пост-валидацию, проверяющую семантические ограничения, например порядок дат
C Усилить строгость схемы, добавив больше обязательных полей
D Добавить few-shot примеры верных связей полей