[G1-Sync] Manual knowledge update

10_Wiki/Topics/Coding/AI_Structured_Output_Zod.md

@@ -0,0 +1,168 @@
+---
+id: ai-structured-output-zod
+title: LLM Structured Output — Zod / Function Calling
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [ai, llm, structured, zod, vibe-coding]
+tech_stack: { language: "TS / Zod / OpenAI / Anthropic", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [structured output, JSON mode, function calling, tool use, response_format]
+---
+
+# LLM Structured Output
+
+> JSON 강제 prompt 만으로는 신뢰 X. **OpenAI `response_format: { type: 'json_schema' }` / Anthropic tool_use** 가 schema 보장. **Zod → JSON Schema** 가 표준 워크플로.
+
+## 📖 핵심 개념
+- JSON mode: 어떤 JSON 도 통과 (schema 미보장).
+- Structured output (OpenAI): JSON Schema 기반 **enforce**. parse 실패 0%.
+- Tool use (Anthropic): 함수 호출 형태 — input_schema 강제.
+- Zod → JSON Schema: `zod-to-json-schema` 라이브러리.
+
+## 💻 코드 패턴
+
+### OpenAI structured output
+```ts
+import OpenAI from 'openai';
+import { zodResponseFormat } from 'openai/helpers/zod';
+import { z } from 'zod';
+
+const Recipe = z.object({
+  title: z.string(),
+  servings: z.number().int().positive(),
+  ingredients: z.array(z.object({
+    name: z.string(),
+    qty: z.number(),
+    unit: z.enum(['g', 'ml', 'cup', 'tsp']),
+  })),
+  steps: z.array(z.string()).max(10),
+});
+
+const client = new OpenAI();
+const r = await client.beta.chat.completions.parse({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Spaghetti carbonara recipe' }],
+  response_format: zodResponseFormat(Recipe, 'recipe'),
+});
+
+const recipe = r.choices[0].message.parsed!; // 타입 = z.infer<typeof Recipe>
+```
+
+### Anthropic tool use (structured)
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+const client = new Anthropic();
+const r = await client.messages.create({
+  model: 'claude-opus-4-7',
+  max_tokens: 1024,
+  tools: [{
+    name: 'extract_recipe',
+    description: 'Extract recipe data',
+    input_schema: zodToJsonSchema(Recipe) as Anthropic.Messages.Tool.InputSchema,
+  }],
+  tool_choice: { type: 'tool', name: 'extract_recipe' }, // 강제
+  messages: [{ role: 'user', content: 'Spaghetti carbonara recipe' }],
+});
+
+const block = r.content.find(b => b.type === 'tool_use');
+const recipe = Recipe.parse(block!.input);
+```
+
+### 검증 + 재시도
+```ts
+async function getRecipe(query: string, attempts = 3): Promise<Recipe> {
+  let lastErr: unknown;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      const raw = await callLLM(query);
+      return Recipe.parse(raw); // throws ZodError on fail
+    } catch (e) {
+      lastErr = e;
+      // 재시도 시 에러 메시지를 LLM 에 피드백
+    }
+  }
+  throw lastErr;
+}
+```
+
+### 점진적 schema (간단 → 복잡)
+```ts
+// V1: 단순
+const SimpleRecipe = z.object({ title: z.string(), steps: z.array(z.string()) });
+// 동작 확인
+
+// V2: 더 정밀
+const Recipe = SimpleRecipe.extend({
+  servings: z.number().int().positive(),
+  ingredients: z.array(IngredientSchema),
+});
+```
+
+### Discriminated union (여러 종류)
+```ts
+const Action = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('search'), query: z.string() }),
+  z.object({ type: z.literal('calc'), expr: z.string() }),
+  z.object({ type: z.literal('done'), answer: z.string() }),
+]);
+```
+
+### Streaming + structured (OpenAI)
+```ts
+const stream = await client.beta.chat.completions.stream({
+  model: 'gpt-4o',
+  messages: [...],
+  response_format: zodResponseFormat(Recipe, 'recipe'),
+});
+
+for await (const ev of stream) {
+  if (ev.event === 'content.delta') console.log(ev.parsed); // 부분 객체
+}
+
+const final = (await stream.finalChatCompletion()).choices[0].message.parsed;
+```
+
+### Function calling (legacy)
+```ts
+const r = await client.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [...],
+  tools: [{ type: 'function', function: { name: 'extract', parameters: zodToJsonSchema(Recipe) } }],
+  tool_choice: { type: 'function', function: { name: 'extract' } },
+});
+```
+
+## 🤔 의사결정 기준
+| 상황 | 추천 |
+|---|---|
+| OpenAI 정확한 schema | Structured output |
+| Anthropic | Tool use + force tool |
+| 간단 JSON | JSON mode + Zod parse |
+| 여러 종류 액션 | Discriminated union |
+| Streaming partial | OpenAI stream + structured |
+| Schema 변동 | runtime parse + 재시도 |
+
+## ❌ 안티패턴
+- **JSON 그대로 신뢰**: 자유 형식이면 누락 / 추가 키.
+- **Schema 거대**: enum 100개 / 50 필드 — LLM 도 정확히 못 채움.
+- **Optional 모두**: 강제 없으면 LLM 이 빠뜨림.
+- **Description 없음**: schema 만 있으면 LLM 이 의미 모름.
+- **Re-try infinite**: 3번 후 fallback 또는 사용자에게.
+- **Tool name 동사 X 명사 O**: tool_use 는 동사 권장 (`extract_recipe`).
+- **PII strict 검증 없음**: 잘못된 형식 통과.
+
+## 🤖 LLM 활용 힌트
+- Zod schema → zodResponseFormat (OpenAI) / zodToJsonSchema (Anthropic).
+- 강제 tool_choice 또는 response_format 으로 보장.
+- Description 풍부하게.
+
+## 🔗 관련 문서
+- [[AI_Prompt_Engineering_Patterns]]
+- [[AI_Streaming_LLM_Response]]
+- [[Schema_Validation_Zod_Patterns]]