RAG完全実装ガイド【TypeScript】｜Embedding・pgvector・ハイブリッド検索・プロンプト設計まで実装コード付きで解説

# 必要なパッケージをインストール
npm install openai @ai-sdk/openai ai zod

# PostgreSQL + pgvector（ベクトルDB）
npm install pg drizzle-orm drizzle-kit
npm install -D @types/pg

# テキスト処理
npm install tiktoken          # トークンカウント
npm install pdf-parse          # PDF読み込み
npm install -D @types/pdf-parse

docker run -d \
  --name pgvector \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=ragdb \
  -p 5432:5432 \
  pgvector/pgvector:pg16

OPENAI_API_KEY=sk-xxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ragdb

-- pgvector拡張を有効化
CREATE EXTENSION IF NOT EXISTS vector;

-- ドキュメントチャンクのテーブル
CREATE TABLE IF NOT EXISTS document_chunks (
  id          BIGSERIAL PRIMARY KEY,
  content     TEXT NOT NULL,             -- チャンクのテキスト
  embedding   VECTOR(1536),              -- OpenAI text-embedding-3-small のベクトル次元
  metadata    JSONB DEFAULT '{}',        -- ソースファイル名・ページ番号等
  created_at  TIMESTAMPTZ DEFAULT NOW()
);

-- コサイン類似度検索用インデックス（IVFFlat）
-- リスト数はデータ量に応じて調整（目安: sqrt(行数)）
CREATE INDEX ON document_chunks
  USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);

-- 全文検索用インデックス（ハイブリッド検索で使用）
-- 日本語ドキュメントの場合は 'english' を 'simple' に変更するか pg_bigm/pgroonga を導入する
CREATE INDEX ON document_chunks
  USING gin(to_tsvector('simple', content));

import { pgTable, bigserial, text, jsonb, timestamp, customType } from "drizzle-orm/pg-core";

// pgvectorのVECTOR型をDrizzleのカスタム型として定義
const vector = customType<{ data: number[]; driverData: string }>({
  dataType(config) {
    return `vector(${(config as { dimensions?: number }).dimensions ?? 1536})`;
  },
  fromDriver(value: string): number[] {
    // "[0.1,0.2,...]" 形式の文字列を配列に変換
    return JSON.parse(value.replace(/^\[/, "[").replace(/\]$/, "]"));
  },
  toDriver(value: number[]): string {
    return `[${value.join(",")}]`;
  },
});

export const documentChunks = pgTable("document_chunks", {
  id:        bigserial("id", { mode: "number" }).primaryKey(),
  content:   text("content").notNull(),
  embedding: vector("embedding", { dimensions: 1536 }),
  metadata:  jsonb("metadata").$type<{
    source: string;
    page?: number;
    chunkIndex: number;
    title?: string;
  }>().default({}),
  createdAt: timestamp("created_at").defaultNow(),
});

export type DocumentChunk = typeof documentChunks.$inferSelect;
export type NewDocumentChunk = typeof documentChunks.$inferInsert;

import { encode } from "tiktoken";

interface ChunkOptions {
  chunkSize: number;    // トークン数（デフォルト: 512）
  chunkOverlap: number; // オーバーラップトークン数（デフォルト: 50）
}

interface Chunk {
  content: string;
  chunkIndex: number;
  tokenCount: number;
}

/**
 * テキストをトークン数に基づいて分割する
 * - 文の途中では切らずに段落・文単位で分割
 * - オーバーラップで文脈の連続性を保つ
 */
export function splitText(
  text: string,
  options: Partial<ChunkOptions> = {}
): Chunk[] {
  const { chunkSize = 512, chunkOverlap = 50 } = options;
  const enc = encode(text);
  const totalTokens = enc.length;

  if (totalTokens <= chunkSize) {
    return [{ content: text.trim(), chunkIndex: 0, tokenCount: totalTokens }];
  }

  // 段落単位で分割してからチャンクに詰める
  const paragraphs = text
    .split(/\n{2,}/)
    .map((p) => p.trim())
    .filter((p) => p.length > 0);

  const chunks: Chunk[] = [];
  let currentChunk = "";
  let currentTokens = 0;
  let chunkIndex = 0;

  for (const paragraph of paragraphs) {
    const paraTokens = encode(paragraph).length;

    // チャンクサイズを超えたら新しいチャンクへ
    if (currentTokens + paraTokens > chunkSize && currentChunk) {
      chunks.push({
        content: currentChunk.trim(),
        chunkIndex: chunkIndex++,
        tokenCount: currentTokens,
      });

      // オーバーラップ分を次のチャンクの先頭に含める
      const overlapText = getLastNTokens(currentChunk, chunkOverlap);
      currentChunk = overlapText + "\n\n" + paragraph;
      currentTokens = encode(currentChunk).length;
    } else {
      currentChunk += (currentChunk ? "\n\n" : "") + paragraph;
      currentTokens += paraTokens;
    }
  }

  if (currentChunk.trim()) {
    chunks.push({
      content: currentChunk.trim(),
      chunkIndex: chunkIndex,
      tokenCount: currentTokens,
    });
  }

  return chunks;
}

function getLastNTokens(text: string, n: number): string {
  const words = text.split(/\s+/);
  // 簡易的な近似（正確にはtiktokenで計算）
  return words.slice(-n * 2).join(" ");
}

// マークダウン見出し単位で分割するヒューリスティック
export function splitMarkdown(markdown: string): Chunk[] {
  const sections = markdown.split(/(?=^#{1,3} )/m);
  return sections
    .filter((s) => s.trim())
    .flatMap((section, i) => {
      const tokens = encode(section).length;
      if (tokens <= 512) {
        return [{ content: section.trim(), chunkIndex: i, tokenCount: tokens }];
      }
      // セクションが大きい場合は再分割
      return splitText(section, { chunkSize: 512, chunkOverlap: 50 }).map(
        (c, j) => ({ ...c, chunkIndex: i * 100 + j })
      );
    });
}

import OpenAI from "openai";

const openai = new OpenAI();

/**
 * テキストのEmbeddingを生成する
 * バッチ処理対応（複数テキストを1回のAPIコールで処理）
 */
export async function generateEmbeddings(
  texts: string[]
): Promise<number[][]> {
  // OpenAI Embeddings APIは1回で最大2048テキストを処理可能
  const batchSize = 100;
  const allEmbeddings: number[][] = [];

  for (let i = 0; i < texts.length; i += batchSize) {
    const batch = texts.slice(i, i + batchSize);

    const response = await openai.embeddings.create({
      model: "text-embedding-3-small",
      input: batch,
      encoding_format: "float",
    });

    const batchEmbeddings = response.data
      .sort((a, b) => a.index - b.index) // 順序を保証
      .map((e) => e.embedding);

    allEmbeddings.push(...batchEmbeddings);

    // レート制限を避けるため少し待機
    if (i + batchSize < texts.length) {
      await new Promise((resolve) => setTimeout(resolve, 100));
    }
  }

  return allEmbeddings;
}

export async function generateEmbedding(text: string): Promise<number[]> {
  const [embedding] = await generateEmbeddings([text]);
  return embedding;
}

// クエリ用（短いテキストに最適化）
export async function generateQueryEmbedding(query: string): Promise<number[]> {
  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: query,
    encoding_format: "float",
  });
  return response.data[0].embedding;
}

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { documentChunks, type NewDocumentChunk } from "../db/schema";
import { splitText, splitMarkdown } from "./text-splitter";
import { generateEmbeddings } from "./embeddings";
import * as fs from "fs";
import * as path from "path";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const db = drizzle(pool);

interface IndexOptions {
  source: string;    // ソースファイル名（メタデータ用）
  title?: string;
  chunkSize?: number;
  chunkOverlap?: number;
}

/**
 * テキストをインデックスに追加する
 */
export async function indexText(
  text: string,
  options: IndexOptions
): Promise<number> {
  const { source, title, chunkSize = 512, chunkOverlap = 50 } = options;

  // テキストを分割
  const chunks = splitText(text, { chunkSize, chunkOverlap });
  console.log(`${source}: ${chunks.length}チャンクに分割`);

  // バッチでEmbeddingを生成
  const contents = chunks.map((c) => c.content);
  const embeddings = await generateEmbeddings(contents);
  console.log(`Embedding生成完了: ${embeddings.length}件`);

  // DBに一括挿入
  const rows: NewDocumentChunk[] = chunks.map((chunk, i) => ({
    content: chunk.content,
    embedding: embeddings[i],
    metadata: {
      source,
      title,
      chunkIndex: chunk.chunkIndex,
    },
  }));

  await db.insert(documentChunks).values(rows);
  console.log(`インデックス追加完了: ${rows.length}件`);

  return rows.length;
}

/**
 * Markdownファイルをインデックスに追加する
 */
export async function indexMarkdownFile(filePath: string): Promise<number> {
  const content = fs.readFileSync(filePath, "utf-8");
  const source = path.basename(filePath);
  const title = content.match(/^#\s+(.+)/m)?.[1] ?? source;

  return indexText(content, { source, title });
}

/**
 * ディレクトリ内のMarkdownファイルをすべてインデックスする
 */
export async function indexDirectory(dirPath: string): Promise<void> {
  const files = fs.readdirSync(dirPath)
    .filter((f) => f.endsWith(".md") || f.endsWith(".txt"));

  let total = 0;
  for (const file of files) {
    const count = await indexMarkdownFile(path.join(dirPath, file));
    total += count;
    console.log(`${file}: ${count}チャンク追加 (合計: ${total})`);
  }

  console.log(`\nインデックス完了: ${files.length}ファイル, ${total}チャンク`);
}

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { sql } from "drizzle-orm";
import { documentChunks, type DocumentChunk } from "../db/schema";
import { generateQueryEmbedding } from "./embeddings";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const db = drizzle(pool);

export interface SearchResult {
  chunk: DocumentChunk;
  score: number; // 0〜1（1が最も類似）
}

/**
 * ベクトル類似検索（コサイン類似度）
 */
export async function vectorSearch(
  query: string,
  topK: number = 5,
  threshold: number = 0.7
): Promise<SearchResult[]> {
  const queryEmbedding = await generateQueryEmbedding(query);
  const embeddingStr = `[${queryEmbedding.join(",")}]`;

  // pgvectorの <=> 演算子はコサイン距離（0=完全一致、2=完全不一致）
  // 類似度 = 1 - コサイン距離
  const results = await db.execute(sql`
    SELECT
      id,
      content,
      metadata,
      created_at,
      1 - (embedding <=> ${embeddingStr}::vector) AS score
    FROM document_chunks
    WHERE 1 - (embedding <=> ${embeddingStr}::vector) >= ${threshold}
    ORDER BY embedding <=> ${embeddingStr}::vector
    LIMIT ${topK}
  `);

  return (results.rows as Array<DocumentChunk & { score: number }>).map(
    (row) => ({ chunk: row, score: row.score })
  );
}

/**
 * ハイブリッド検索（ベクトル検索 + BM25全文検索の組み合わせ）
 * Reciprocal Rank Fusion (RRF) でスコアを統合
 */
export async function hybridSearch(
  query: string,
  topK: number = 5
): Promise<SearchResult[]> {
  const queryEmbedding = await generateQueryEmbedding(query);
  const embeddingStr = `[${queryEmbedding.join(",")}]`;

  // RRF定数（通常60を使用）
  const rrfK = 60;

  const results = await db.execute(sql`
    WITH
    vector_ranked AS (
      SELECT
        id,
        ROW_NUMBER() OVER (
          ORDER BY embedding <=> ${embeddingStr}::vector
        ) AS rank
      FROM document_chunks
      ORDER BY embedding <=> ${embeddingStr}::vector
      LIMIT 20
    ),
    bm25_ranked AS (
      -- 注意: 日本語の場合は 'english' を 'simple' に変更するか pg_bigm/pgroonga を使用する
      SELECT
        id,
        ROW_NUMBER() OVER (
          ORDER BY ts_rank(
            to_tsvector('simple', content),
            plainto_tsquery('simple', ${query})
          ) DESC
        ) AS rank
      FROM document_chunks
      WHERE to_tsvector('simple', content) @@ plainto_tsquery('simple', ${query})
      LIMIT 20
    ),
    rrf_scores AS (
      SELECT
        COALESCE(v.id, b.id) AS id,
        COALESCE(1.0 / (${rrfK} + v.rank), 0) +
        COALESCE(1.0 / (${rrfK} + b.rank), 0) AS rrf_score
      FROM vector_ranked v
      FULL OUTER JOIN bm25_ranked b ON v.id = b.id
    )
    SELECT
      dc.id,
      dc.content,
      dc.metadata,
      dc.created_at,
      r.rrf_score AS score
    FROM rrf_scores r
    JOIN document_chunks dc ON r.id = dc.id
    ORDER BY r.rrf_score DESC
    LIMIT ${topK}
  `);

  return (results.rows as Array<DocumentChunk & { score: number }>).map(
    (row) => ({ chunk: row, score: row.score })
  );
}

import Anthropic from "@anthropic-ai/sdk";
import { hybridSearch, type SearchResult } from "./retriever";

const client = new Anthropic();

interface RagOptions {
  topK?: number;
  model?: string;
  maxTokens?: number;
}

export interface RagResponse {
  answer: string;
  sources: Array<{
    content: string;
    source: string;
    score: number;
  }>;
  hasRelevantDocs: boolean;
}

/**
 * RAGプロンプトの構築
 * - 検索結果をコンテキストとしてプロンプトに注入
 * - 「文書にない場合は答えない」制約で幻覚を抑制
 */
function buildRagPrompt(query: string, results: SearchResult[]): string {
  if (results.length === 0) {
    return query;
  }

  const context = results
    .map((r, i) => {
      const source = (r.chunk.metadata as { source?: string }).source ?? "不明";
      return `[文書${i + 1}] （出典: ${source}）\n${r.chunk.content}`;
    })
    .join("\n\n---\n\n");

  return `以下の参考文書をもとに、質問に回答してください。

【重要なルール】
- 参考文書に記載されている情報のみを使って回答する
- 文書にない情報は推測・補完しない
- 不確かな場合は「文書には記載がありません」と明記する
- 回答の根拠となる文書番号を [文書X] 形式で必ず示す

===参考文書===
${context}
=============

質問: ${query}`;
}

/**
 * RAGを使って質問に回答する
 */
export async function ragQuery(
  query: string,
  options: RagOptions = {}
): Promise<RagResponse> {
  const {
    topK = 5,
    model = "claude-opus-4-6",
    maxTokens = 1024,
  } = options;

  // 1. ハイブリッド検索で関連チャンクを取得
  const searchResults = await hybridSearch(query, topK);
  const hasRelevantDocs = searchResults.length > 0;

  // 2. プロンプトを構築
  const prompt = buildRagPrompt(query, searchResults);

  // 3. LLMに回答を生成させる
  const response = await client.messages.create({
    model,
    max_tokens: maxTokens,
    system: `あなたは正確な情報提供を最優先にするAIアシスタントです。
与えられた文書の範囲内で回答し、文書に記載のない情報は提供しないでください。
日本語で回答してください。`,
    messages: [{ role: "user", content: prompt }],
  });

  const answer = (response.content[0] as { text: string }).text;

  return {
    answer,
    sources: searchResults.map((r) => ({
      content: r.chunk.content.slice(0, 200) + "...",
      source: (r.chunk.metadata as { source?: string }).source ?? "不明",
      score: r.score,
    })),
    hasRelevantDocs,
  };
}

import { streamText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { hybridSearch } from "@/lib/retriever";

export const runtime = "nodejs"; // pgはEdge非対応のためNode.js

export async function POST(req: Request) {
  const { query, history } = await req.json() as {
    query: string;
    history?: { role: "user" | "assistant"; content: string }[];
  };

  if (!query?.trim()) {
    return new Response("queryが必要です", { status: 400 });
  }

  // 関連ドキュメントを検索
  const results = await hybridSearch(query, 4);
  const context = results
    .map((r, i) => {
      const src = (r.chunk.metadata as { source?: string }).source ?? "不明";
      return `[文書${i + 1}] ${src}\n${r.chunk.content}`;
    })
    .join("\n\n---\n\n");

  const systemPrompt = results.length > 0
    ? `あなたはドキュメントQAアシスタントです。以下の文書のみを根拠に回答してください。
文書にない情報は「文書には記載がありません」と答えてください。

===参考文書===
${context}
=============`
    : "あなたはAIアシスタントです。関連する文書が見つかりませんでした。一般的な知識で回答してください。";

  const result = streamText({
    model: anthropic("claude-opus-4-6"),
    system: systemPrompt,
    messages: [
      ...(history ?? []),
      { role: "user", content: query },
    ],
    maxTokens: 1024,
  });

  return result.toDataStreamResponse();
}

"use client";
import { useChat } from "@ai-sdk/react"; // npm install @ai-sdk/react
import { useState } from "react";

interface Source {
  content: string;
  source: string;
  score: number;
}

export default function RagChat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } =
    useChat({ api: "/api/rag" });

  return (
    <div className="rag-chat">
      <div className="messages">
        {messages.map((m) => (
          <div key={m.id} className={`message ${m.role}`}>
            <div className="message-role">
              {m.role === "user" ? "あなた" : "AI"}
            </div>
            <div className="message-content">{m.content}</div>
          </div>
        ))}
        {isLoading && (
          <div className="message assistant">
            <div className="message-role">AI</div>
            <div className="message-content loading">回答を生成中...</div>
          </div>
        )}
      </div>

      <form onSubmit={handleSubmit} className="input-form">
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="ドキュメントについて質問してください..."
          disabled={isLoading}
        />
        <button type="submit" disabled={isLoading || !input.trim()}>
          送信
        </button>
      </form>
    </div>
  );
}

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

interface EvalResult {
  faithfulness: number;   // 0〜1: 回答が文書に忠実か
  relevance: number;      // 0〜1: 回答が質問に関連しているか
  reasoning: string;
}

/**
 * LLMを使ってRAG回答の品質を自動評価する
 * いわゆる "LLM-as-a-judge" パターン
 */
export async function evaluateRagAnswer(
  query: string,
  answer: string,
  contexts: string[]
): Promise<EvalResult> {
  const contextText = contexts
    .map((c, i) => `[文書${i + 1}] ${c}`)
    .join("\n\n");

  const response = await client.messages.create({
    model: "claude-opus-4-6",
    max_tokens: 512,
    messages: [
      {
        role: "user",
        content: `以下のRAG回答を評価してください。JSONのみで返してください。

質問: ${query}

参考文書:
${contextText}

回答: ${answer}

評価基準:
1. faithfulness（0〜1）: 回答が参考文書の内容に忠実かどうか（文書にない情報を追加していないか）
2. relevance（0〜1）: 回答が質問に適切に答えているかどうか

JSON形式:
{"faithfulness": 0.9, "relevance": 0.85, "reasoning": "評価の理由"}`,
      },
    ],
  });

  const text = (response.content[0] as { text: string }).text;
  const match = text.match(/\{[\s\S]*\}/);
  if (!match) throw new Error("評価結果のパースに失敗");
  return JSON.parse(match[0]) as EvalResult;
}