llm

LLM 実装ガイドライン

ディレクトリ構成

LLM 関連のコードは、用途に応じた特定のディレクトリに整理されています。

• apps/web/utils/ai/ - 主な LLM 実装
• apps/web/utils/llms/ - LLM のコアユーティリティと設定
• apps/web/__tests__/ - LLM 専用のテスト

主なファイル

• utils/llms/index.ts - LLM のコア機能
• utils/llms/model.ts - モデル定義と設定
• utils/usage.ts - 使用状況の追跡と監視

実装パターン

LLM 関連の関数には、次の標準的な構成に従ってください。

import { z } from "zod";
import { createScopedLogger } from "@/utils/logger";
import { chatCompletionObject } from "@/utils/llms";
import type { EmailAccountWithAI } from "@/utils/llms/types";
import { createGenerateObject } from "@/utils/llms";

export async function featureFunction(options: {
  inputData: InputType;
  emailAccount: EmailAccountWithAI;
}) {
  const { inputData, user } = options;

  if (!inputData || [other validation conditions]) {
    logger.warn("Invalid input for feature function");
    return null;
  }

  const system = `[Detailed system prompt that defines the LLM's role and task]`;

  const prompt = `[User prompt with context and specific instructions]

<data>
...
</data>

${emailAccount.about ? `<user_info>${emailAccount.about}</user_info>` : ""}`;

  const modelOptions = getModel(emailAccount.user);

  const generateObject = createGenerateObject({
    userEmail: emailAccount.email,
    label: "Feature Name",
    modelOptions,
  });


  const result = await generateObject({
    ...modelOptions,
    system,
    prompt,
    schema: z.object({
      field1: z.string(),
      field2: z.number(),
      nested: z.object({
        subfield: z.string(),
      }),
      array_field: z.array(z.string()),
    }),
  });

  return result.object;
}

ベストプラクティス

1. システムプロンプトとユーザープロンプト：

   • システムプロンプトとユーザープロンプトは分けてください
   • システムプロンプトでは、LLM の役割とタスクの仕様を定義してください
   • ユーザープロンプトには、実際のデータとコンテキストを含めてください

2. スキーマ検証：

   • レスポンスを検証するため、必ず Zod スキーマを定義してください
   • LLM の出力を適切に導けるよう、スキーマは可能な限り具体的にしてください

3. ロギング：

   • 各機能に説明的なスコープ付きロガーを使用してください
   • 適切なログレベルで入力と出力を記録してください
   • ログメッセージには関連するコンテキストを含めてください

4. エラー処理：

   • 無効な入力に対して早期リターンを実装してください
   • 適切なエラー型とロギングを使用してください
   • AI の失敗に備えてフォールバックを実装してください
   • 一時的な障害に対して、withRetry を使用したリトライロジックを追加してください

5. 入力のフォーマット：

   • プロンプト内のデータ構造化には、XML 風のタグを使用してください
   • 過剰な空白を削除し、長い入力は切り詰めてください
   • 類似する関数間でデータ形式を統一してください

6. 型安全性：

   • すべてのパラメーターと戻り値に TypeScript の型を使用してください
   • 複雑な入出力構造には、明確なインターフェースを定義してください

7. コードの整理：

   • 関連する AI 関数は、同じファイルまたはディレクトリにまとめてください
   • 共通パターンはユーティリティ関数に切り出してください
   • 複雑な AI ロジックには、わかりやすいコメントを付けてください

8. AI を優先する動作：

   • モデルの推論を模倣する脆弱な語彙的ヒューリスティクスよりも、汎用的なプロンプト指示、構造化された出力、モデルの選択を優先してください
   • モデルの外部に厳格なルールが本当に必要な場合に限り、決定論的なフィルターを追加してください
   • テストに合格させるためだけに、評価用フィクスチャに酷似したプロンプトの例を追加しないでください

9. 下書きのアトリビューションのバージョン管理：

   • 下書き生成のプロンプト入力、検索コンテキスト、ルーティング、または後処理を変更する場合は、apps/web/utils/ai/reply/draft-attribution.ts の DRAFT_PIPELINE_VERSION を更新してください
   • このバージョンは、返信下書きの品質を比較するための分析上のアトリビューションとして扱ってください

テスト

llm-test.mdc を参照してください