ハルシネーションを本番で抑える: Claude API 多層防御アーキテクチャの設計図

const escapeHatchTools: Anthropic.Tool[] = [
  {
    name: "answer_with_citation",
    description:
      "ユーザーの質問に、提供されたドキュメントを根拠として回答する。" +
      "回答内容と、根拠となるドキュメントIDを必ず指定すること。",
    input_schema: {
      type: "object" as const,
      properties: {
        answer: { type: "string", description: "ユーザー向けの回答本文" },
        citations: {
          type: "array",
          items: { type: "string" },
          description: "根拠としたドキュメントIDのリスト（最低1件必須）",
        },
        confidence: {
          type: "string",
          enum: ["high", "medium", "low"],
          description: "回答の確信度",
        },
      },
      required: ["answer", "citations", "confidence"],
    },
  },
  {
    name: "decline_to_answer",
    description:
      "提供されたドキュメントから回答できない場合、または質問が範囲外の場合に使用する。" +
      "推測で答える代わりに必ずこのツールを呼び出すこと。",
    input_schema: {
      type: "object" as const,
      properties: {
        reason: {
          type: "string",
          enum: ["insufficient_information", "out_of_scope", "ambiguous_question"],
        },
        suggested_action: {
          type: "string",
          description: "ユーザーへの代替案（例: 担当部署の問い合わせ先、追加情報の依頼）",
        },
      },
      required: ["reason", "suggested_action"],
    },
  },
];
 
async function answerWithEscapeHatch(question: string, docs: RetrievedDoc[]) {
  const docsBlock = docs
    .map((d) => `<document id="${d.id}">${d.content}</document>`)
    .join("\n");
 
  const res = await client.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    tools: escapeHatchTools,
    tool_choice: { type: "any" }, // 必ずツールを使わせる
    system:
      "回答可能なら answer_with_citation を、不可能なら decline_to_answer を必ず呼び出してください。" +
      "通常のテキスト応答は禁止です。",
    messages: [
      { role: "user", content: `<documents>\n${docsBlock}\n</documents>\n\n${question}` },
    ],
  });
 
  const toolUse = res.content.find(
    (b): b is Anthropic.ToolUseBlock => b.type === "tool_use"
  );
  if (!toolUse) {
    throw new Error("Claude returned no tool call - check tool_choice config");
  }
  return { tool: toolUse.name, input: toolUse.input };
}

async function answerWithCitations(question: string, docs: RetrievedDoc[]) {
  const documentBlocks = docs.map((d) => ({
    type: "document" as const,
    source: {
      type: "text" as const,
      media_type: "text/plain" as const,
      data: d.content,
    },
    title: d.title,
    citations: { enabled: true },
  }));
 
  const res = await client.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [...documentBlocks, { type: "text", text: question }],
      },
    ],
  });
 
  // 各 text block に citations 配列が付く
  const annotated = res.content.flatMap((block) => {
    if (block.type !== "text") return [];
    return [
      {
        text: block.text,
        citations: block.citations ?? [],
      },
    ];
  });
 
  // citations が空のセグメントは「出典がない=ハルシネーションリスク高」として警告
  for (const seg of annotated) {
    if (seg.text.trim().length > 30 && seg.citations.length === 0) {
      console.warn(`⚠️ 出典なしセグメント検出: "${seg.text.slice(0, 50)}..."`);
    }
  }
 
  return annotated;
}

import crypto from "node:crypto";
 
interface SelfConsistencyResult {
  consensus_answer: string | null;
  agreement_rate: number;
  variations: string[];
}
 
async function selfConsistencyAnswer(
  question: string,
  docs: RetrievedDoc[],
  samples = 5
): Promise<SelfConsistencyResult> {
  const docsBlock = docs.map((d) => `<doc id="${d.id}">${d.content}</doc>`).join("\n");
 
  // temperature を上げて意図的に多様性を出し、それでも一致するかを見る
  const responses = await Promise.all(
    Array.from({ length: samples }, () =>
      client.messages.create({
        model: "claude-sonnet-4-5",
        max_tokens: 256,
        temperature: 0.7,
        system:
          "提供されたドキュメントから事実を1文で抽出してください。説明や前置きは不要です。",
        messages: [
          { role: "user", content: `<docs>${docsBlock}</docs>\n\n質問: ${question}` },
        ],
      })
    )
  );
 
  const variations = responses.map((r) =>
    r.content
      .filter((b): b is Anthropic.TextBlock => b.type === "text")
      .map((b) => b.text.trim())
      .join("")
  );
 
  // 完全一致でグループ化（より高度には embedding でクラスタリング）
  const counts = new Map<string, number>();
  for (const v of variations) {
    const key = normalize(v); // 表記揺れを正規化
    counts.set(key, (counts.get(key) ?? 0) + 1);
  }
 
  const sorted = Array.from(counts.entries()).sort((a, b) => b[1] - a[1]);
  const top = sorted[0];
 
  return {
    consensus_answer: top && top[1] >= Math.ceil(samples / 2) ? top[0] : null,
    agreement_rate: top ? top[1] / samples : 0,
    variations,
  };
}
 
function normalize(s: string): string {
  return s
    .replace(/\s+/g, " ")
    .replace(/[「」『』。、,.\s]/g, "")
    .toLowerCase();
}

interface JudgeVerdict {
  verdict: "supported" | "unsupported" | "partially_supported";
  reasoning: string;
  problematic_claims: string[];
}
 
async function judgeAnswer(
  question: string,
  answer: string,
  source_docs: RetrievedDoc[]
): Promise<JudgeVerdict> {
  const docsBlock = source_docs.map((d) => `[${d.id}] ${d.content}`).join("\n\n");
 
  // ❗ judge モデルには「厳しく評価する」役割を明示
  // 甘い judge は意味がないため、敵対的な視点を強要する
  const judgeSystem = `あなたは事実検証の監査官です。生成AIの回答が、提供された参照ドキュメントから本当に支持されているかを厳格に判定します。
 
判定基準:
- 回答中の固有名詞・数値・日付・URL は、参照ドキュメントに「逐字レベル」で存在する場合のみ supported
- 「常識的に正しい」「推測でこうだろう」は全て unsupported
- 部分的に正しいが、一部にドキュメントに無い情報が混入している場合は partially_supported
- 回答が問題ない場合でも、潜在的な不正確さがあれば必ず指摘すること
 
問題のある主張は problematic_claims に「主張: 問題点」の形式で1件ずつ列挙してください。`;
 
  const res = await client.messages.create({
    model: "claude-opus-4-6", // judge は強いモデルを使う
    max_tokens: 1024,
    system: judgeSystem,
    tools: [
      {
        name: "submit_verdict",
        description: "事実検証の結果を提出する",
        input_schema: {
          type: "object" as const,
          properties: {
            verdict: {
              type: "string",
              enum: ["supported", "unsupported", "partially_supported"],
            },
            reasoning: { type: "string" },
            problematic_claims: { type: "array", items: { type: "string" } },
          },
          required: ["verdict", "reasoning", "problematic_claims"],
        },
      },
    ],
    tool_choice: { type: "tool", name: "submit_verdict" },
    messages: [
      {
        role: "user",
        content:
          `参照ドキュメント:\n${docsBlock}\n\n` +
          `ユーザーの質問: ${question}\n\n` +
          `AI の回答: ${answer}\n\n` +
          `この回答は参照ドキュメントから支持されているか判定してください。`,
      },
    ],
  });
 
  const tool = res.content.find(
    (b): b is Anthropic.ToolUseBlock => b.type === "tool_use"
  );
  if (!tool) throw new Error("Judge did not return verdict");
  return tool.input as unknown as JudgeVerdict;
}
 
// パイプライン全体の合成例
async function safeAnswer(question: string, docs: RetrievedDoc[]) {
  const draft = await answerWithGrounding(question, docs);
  const verdict = await judgeAnswer(question, draft, docs);
 
  if (verdict.verdict === "unsupported") {
    return {
      shown_to_user: "申し訳ありません、確実に回答できる情報がありませんでした。",
      internal_log: { draft, verdict },
    };
  }
  if (verdict.verdict === "partially_supported") {
    // 問題のある主張を Opus に修正させる二段階生成
    const refined = await refineWithFeedback(draft, verdict.problematic_claims, docs);
    return { shown_to_user: refined, internal_log: { draft, verdict, refined } };
  }
  return { shown_to_user: draft, internal_log: { draft, verdict } };
}
 
async function refineWithFeedback(
  draft: string,
  issues: string[],
  docs: RetrievedDoc[]
): Promise<string> {
  const docsBlock = docs.map((d) => `[${d.id}] ${d.content}`).join("\n");
  const res = await client.messages.create({
    model: "claude-opus-4-6",
    max_tokens: 1024,
    system: "事前ドラフトと指摘された問題点を踏まえ、参照ドキュメントから支持される表現に書き直してください。書き直した本文のみを返してください。",
    messages: [
      {
        role: "user",
        content:
          `参照: ${docsBlock}\n\nドラフト: ${draft}\n\n問題点:\n${issues.join("\n")}`,
      },
    ],
  });
  return res.content
    .filter((b): b is Anthropic.TextBlock => b.type === "text")
    .map((b) => b.text)
    .join("");
}

import { z } from "zod";
 
const InvoiceExtractionSchema = z.object({
  invoice_number: z.string().regex(/^[A-Z0-9-]+$/),
  total_amount: z.number().positive(),
  currency: z.enum(["JPY", "USD", "EUR"]),
  issued_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  line_items: z
    .array(
      z.object({
        description: z.string().min(1),
        quantity: z.number().int().positive(),
        unit_price: z.number().nonnegative(),
      })
    )
    .min(1),
});
 
type Invoice = z.infer<typeof InvoiceExtractionSchema>;
 
async function extractInvoice(rawText: string, maxRetries = 2): Promise<Invoice> {
  let attempts = 0;
  let lastError: string | undefined;
 
  while (attempts <= maxRetries) {
    const res = await client.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 2048,
      tools: [
        {
          name: "submit_invoice",
          description: "請求書から構造化データを抽出する",
          input_schema: {
            type: "object" as const,
            properties: {
              invoice_number: { type: "string" },
              total_amount: { type: "number" },
              currency: { type: "string", enum: ["JPY", "USD", "EUR"] },
              issued_date: { type: "string" },
              line_items: {
                type: "array",
                items: {
                  type: "object",
                  properties: {
                    description: { type: "string" },
                    quantity: { type: "number" },
                    unit_price: { type: "number" },
                  },
                  required: ["description", "quantity", "unit_price"],
                },
              },
            },
            required: [
              "invoice_number",
              "total_amount",
              "currency",
              "issued_date",
              "line_items",
            ],
          },
        },
      ],
      tool_choice: { type: "tool", name: "submit_invoice" },
      messages: [
        {
          role: "user",
          content:
            (lastError
              ? `前回のエラー: ${lastError}\n修正して再送してください。\n\n`
              : "") + `請求書テキスト:\n${rawText}`,
        },
      ],
    });
 
    const tool = res.content.find(
      (b): b is Anthropic.ToolUseBlock => b.type === "tool_use"
    );
    if (!tool) {
      lastError = "ツール呼び出しがありませんでした";
      attempts++;
      continue;
    }
 
    const parsed = InvoiceExtractionSchema.safeParse(tool.input);
    if (parsed.success) return parsed.data;
 
    lastError = parsed.error.issues
      .map((i) => `${i.path.join(".")}: ${i.message}`)
      .join("; ");
    attempts++;
  }
 
  throw new Error(`Schema validation failed after ${maxRetries + 1} attempts: ${lastError}`);
}