Gemini の構造化出力を本番で信用するために — スキーマ設計・二重検証・抑制つきリトライの実装メモ

// invoice-schema.ts
import { Type } from "@google/genai";
 
export const invoiceSchema = {
  type: Type.OBJECT,
  properties: {
    invoiceNumber: { type: Type.STRING, description: "請求書番号" },
    issueDate: {
      type: Type.STRING,
      description: "発行日。必ず YYYY-MM-DD 形式の実在する日付",
    },
    vendor: {
      type: Type.OBJECT,
      properties: {
        name: { type: Type.STRING },
        taxId: { type: Type.STRING, description: "登録番号。無ければ省略" },
      },
      required: ["name"],
    },
    lineItems: {
      type: Type.ARRAY,
      items: {
        type: Type.OBJECT,
        properties: {
          description: { type: Type.STRING },
          quantity: { type: Type.NUMBER },
          unitPrice: { type: Type.NUMBER, description: "税抜単価" },
          amount: { type: Type.NUMBER, description: "数量 × 単価（税抜）" },
        },
        propertyOrdering: ["description", "quantity", "unitPrice", "amount"],
        required: ["description", "quantity", "unitPrice", "amount"],
      },
    },
    grandTotal: { type: Type.NUMBER, description: "税込総額" },
    paymentStatus: {
      type: Type.STRING,
      enum: ["paid", "pending", "overdue"],
    },
    currency: { type: Type.STRING, enum: ["JPY", "USD", "EUR"] },
  },
  propertyOrdering: [
    "invoiceNumber", "issueDate", "vendor",
    "lineItems", "grandTotal", "paymentStatus", "currency",
  ],
  required: ["invoiceNumber", "issueDate", "lineItems", "grandTotal", "paymentStatus", "currency"],
};

// invoice-validate.ts
import { z } from "zod";
 
const InvoiceZ = z.object({
  invoiceNumber: z.string().min(1),
  issueDate: z.string().refine(
    (s) => !Number.isNaN(Date.parse(s)) && /^\d{4}-\d{2}-\d{2}$/.test(s),
    { message: "実在する YYYY-MM-DD ではありません" },
  ),
  vendor: z.object({ name: z.string().min(1), taxId: z.string().optional() }),
  lineItems: z.array(z.object({
    description: z.string(),
    quantity: z.number().positive(),
    unitPrice: z.number().min(0),
    amount: z.number().min(0),
  })).min(1),
  grandTotal: z.number().min(0),
  paymentStatus: z.enum(["paid", "pending", "overdue"]),
  currency: z.enum(["JPY", "USD", "EUR"]),
});
 
export type Invoice = z.infer<typeof InvoiceZ>;
 
// スキーマでは表現できない「複数フィールドにまたがる整合性」を検証する
export function checkConsistency(inv: Invoice): string[] {
  const issues: string[] = [];
 
  const lineSum = inv.lineItems.reduce((s, it) => s + it.amount, 0);
  // JPY は最小単位が 1 円なので丸め誤差はほぼ出ない。多通貨なら許容幅を通貨別に持つ
  const tolerance = inv.currency === "JPY" ? 1 : 0.01;
  if (Math.abs(lineSum - inv.grandTotal) > tolerance) {
    issues.push(`明細合計 ${lineSum} と総額 ${inv.grandTotal} が一致しません`);
  }
 
  for (const it of inv.lineItems) {
    const expected = it.quantity * it.unitPrice;
    if (Math.abs(expected - it.amount) > tolerance) {
      issues.push(`「${it.description}」の小計が数量×単価と合いません`);
    }
  }
  return issues;
}
 
export function validateInvoice(raw: unknown):
  | { ok: true; data: Invoice; warnings: string[] }
  | { ok: false; error: string } {
  const parsed = InvoiceZ.safeParse(raw);
  if (!parsed.success) {
    return { ok: false, error: parsed.error.issues.map((i) => i.message).join("; ") };
  }
  return { ok: true, data: parsed.data, warnings: checkConsistency(parsed.data) };
}

// safe-generate.ts
import { GoogleGenAI } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
 
type GenResult<T> =
  | { ok: true; data: T }
  | { ok: false; reason: "truncated" | "blocked" | "parse" | "empty"; detail: string };
 
export async function safeGenerate<T>(
  prompt: string,
  schema: object,
  validate: (raw: unknown) => T,
): Promise<GenResult<T>> {
  const res = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: prompt,
    config: {
      responseMimeType: "application/json",
      responseSchema: schema,
      maxOutputTokens: 8192,
    },
  });
 
  const finish = res.candidates?.[0]?.finishReason;
  // MAX_TOKENS は「もっと枠が要る」のサイン。同じ枠でリトライしても無駄
  if (finish === "MAX_TOKENS") {
    return { ok: false, reason: "truncated", detail: "maxOutputTokens に達しました" };
  }
  if (finish === "SAFETY" || finish === "PROHIBITED_CONTENT") {
    return { ok: false, reason: "blocked", detail: `安全フィルタ: ${finish}` };
  }
 
  const text = res.text;
  if (!text) return { ok: false, reason: "empty", detail: "本文が空です" };
 
  try {
    return { ok: true, data: validate(JSON.parse(text)) };
  } catch (e) {
    return { ok: false, reason: "parse", detail: e instanceof Error ? e.message : String(e) };
  }
}

// pipeline.ts
import { safeGenerate } from "./safe-generate";
 
async function processOne<T>(
  doc: { id: string; content: string },
  schema: object,
  validate: (raw: unknown) => T,
  maxRetries = 2,
): Promise<{ id: string; status: "ok" | "review" | "failed"; data?: T; note?: string }> {
  let attempt = 0;
  while (attempt <= maxRetries) {
    const r = await safeGenerate(`抽出対象:\n\n${doc.content}`, schema, validate);
    if (r.ok) return { id: doc.id, status: "ok", data: r.data };
 
    // truncated と blocked はリトライしても直らない。即座に人間へ
    if (r.reason === "truncated" || r.reason === "blocked") {
      return { id: doc.id, status: "review", note: r.detail };
    }
    // parse / empty は指数バックオフで投げ直す
    await new Promise((res) => setTimeout(res, 800 * 2 ** attempt));
    attempt++;
  }
  return { id: doc.id, status: "failed", note: "リトライ上限に到達" };
}
 
// 同時実行数を絞るシンプルなワーカープール
export async function runPipeline<T>(
  docs: { id: string; content: string }[],
  schema: object,
  validate: (raw: unknown) => T,
  concurrency = 3,
) {
  const results: Awaited<ReturnType<typeof processOne<T>>>[] = [];
  const queue = [...docs];
  const workers = Array.from({ length: concurrency }, async () => {
    let doc;
    while ((doc = queue.shift())) {
      results.push(await processOne(doc, schema, validate));
    }
  });
  await Promise.all(workers);
  return results;
}