金融特化型 RAG & 引用一致率監査エージェント システム詳細設計書

System Design Document (SDD) | 日本経済新聞社・法人向け金融情報サービス技術標準準拠

1. システム概要と設計思想

1.1 目的

本システム（financial-rag-agent）は、日本経済新聞社（Nikkei）等の大手経済メディアおよび金融機関における法人向け情報サービス（日経テレコン、日経Smart Work、Nikkei Compass 等）の次世代 AI コア基盤を想定して設計された、エンタープライズ品質の金融分析・引用監査エージェントである。

一般的な LLM アプリケーションが「プロンプトによる単発生成」にとどまるのに対し、本システムは以下のエンタープライズ要件を本番品質（Production Quality）で満たすことを設計思想としている：

2. 全体アーキテクチャ設計

2.1 システム構成図

システムは、クライアント利用層、FastAPI/Caddy ゲートウェイ層、LangGraph オーケストレーション層、検索・データ層、MCP ツール連携層、および Datadog APM 互換の可観測性層から構成される。

flowchart TD
    subgraph Client_Layer ["クライアント・利用層"]
        Browser["金融ターミナル風 Web UI\n(Dark / Light Theme, SSE Stream)"]
        BatchTrigger["深夜適時開示バッチ\n(Nightly Disclosure Batch)"]
        ExternalAPI["外部連携クライアント (REST / SSE)"]
    end

    subgraph Gateway_Layer ["ゲートウェイ・API層 (FastAPI / Caddy)"]
        Caddy["Caddy Reverse Proxy\n(f.0101.click / HTTPS / No-Buffer SSE)"]
        FastAPIApp["FastAPI Core App (ポート 8800)"]
        Routes["/api/v1/chat/stream (SSE)\n/api/v1/chat/sync (REST)\n/api/v1/settings (Hot-Reload)"]
    end

    subgraph Orchestration_Layer ["LangGraph オーケストレーション層"]
        StateGraph["StateGraph (AgentState)"]
        Checkpointer["MemorySaver / State Persistence"]
        
        Node_QR["1. Query Rewriter & Intent Classifier"]
        Node_HS["2. Hybrid Search Engine"]
        Node_MCP["3. MCP Tool Executor"]
        Node_SYN["4. Grounded Synthesizer"]
        Node_VER["5. Citation Verifier & Auditor"]
        
        Edge_Retry{"引用一致率 < 70%\nかつ 再試行 < 2回 ?"}
    end

    subgraph Retrieval_Layer ["検索・データ層"]
        CorpusDB[("日経新聞報道・JPX適時開示\nサンプルコーパス (data/)")]
        BM25Engine["BM25 Okapi (CJK Bi-gram + 数値Token)"]
        DenseEngine["Dense Vector Engine (384-dim 余弦類似度)"]
        RRF["Reciprocal Rank Fusion (k=60)"]
        ESAdapter["Elasticsearch 8.x Kuromoji\nマッピングアダプタ (拡張用)"]
        DiscoveryAdapter["GCP Discovery Engine\n(Vertex AI Search) アダプタ (拡張用)"]
    end

    subgraph LLM_Layer ["LLM Provider フォールバック層"]
        CLIProvider["Local AI CLI\n(claude / antigravity / opencode)\n既定・最優先・API Key不要"]
        CloudProvider["Azure OpenAI / Vertex AI\n(opt-in 兜底)"]
        TemplateFallback["テンプレート最終フォールバック"]
    end

    subgraph Tool_Layer ["MCP ツール連携層 (Model Context Protocol)"]
        MCPServer["MCP Financial Server (FastMCP)"]
        DualSource{"データソース切替\n(Snapshot vs Live API)"}
        SnapDB[("2025/2026 決算・財務DB\n(PER/PBR/ROE/TSR/Trap)")]
        LiveAPI["yfinance API クライアント\n(東証 .T 行情・金利・為替)"]
    end

    subgraph Observability_Layer ["可観測性・監査層"]
        Telemetry["W3C TraceContext & JSON Telemetry"]
        DatadogLogs["Datadog APM / OpenSearch 構造化ログ"]
        AuditReport["引用監査レポート\n(適合率・再現率・一致率)"]
    end

    Browser --> Caddy
    BatchTrigger --> FastAPIApp
    ExternalAPI --> Caddy
    Caddy --> FastAPIApp
    FastAPIApp --> Routes
    Routes --> StateGraph

    StateGraph --> Node_QR
    Node_QR --> Node_HS
    Node_HS --> Node_MCP
    Node_MCP --> Node_SYN
    Node_SYN --> Node_VER
    Node_VER --> Edge_Retry
    Edge_Retry -- "Yes (再試行)" --> Node_SYN
    Edge_Retry -- "No (PASS / 上限到達)" --> Checkpointer

    Node_HS <--> BM25Engine
    Node_HS <--> DenseEngine
    BM25Engine & DenseEngine --> RRF
    BM25Engine <--> CorpusDB
    DenseEngine <--> CorpusDB
    BM25Engine -.-> ESAdapter
    RRF -.-> DiscoveryAdapter

    Node_MCP <--> MCPServer
    MCPServer --> DualSource
    DualSource -- "snapshot" --> SnapDB
    DualSource -- "live_api" --> LiveAPI

    Node_SYN <--> CLIProvider
    CLIProvider -. "CLI失敗 かつ 設定時のみ" .-> CloudProvider
    CLIProvider -. "全Provider失敗時" .-> TemplateFallback
    CloudProvider -. "失敗時" .-> TemplateFallback

    Node_VER --> AuditReport
    StateGraph -.-> Telemetry
    Telemetry -.-> DatadogLogs
          

3. コアコンポーネント詳細設計

3.1 LangGraph マルチステップ状態遷移エンジン

配置: src/graph/workflow.py, src/graph/edges.py, src/graph/nodes/
データ契約 (AgentState): src/models/state.py

状態スキーマ (AgentState)

class AgentState(TypedDict):
    query: str                       # ユーザー元入力
    rewritten_query: str             # 検索最適化済みクエリ
    ticker: Optional[str]            # 銘柄コード (4桁数字、例: "7203")
    intent: str                      # クエリ意図 (company_analysis, macro, etc.)
    data_source_mode: str            # "snapshot" または "live_api"
    retrieved_chunks: List[Dict]     # RRF 統合検索結果 (上位K件)
    mcp_tools_output: Dict[str, Any] # MCP 財務ツール実行結果
    answer: str                      # 生成された回答（引用タグ含む）
    citation_report: Dict[str, Any]  # 引用一致率・適合率・再現率監査結果
    retry_count: int                 # 幻覚検知時の再試行カウンタ (最大2回)
    intermediate_steps: List[str]    # 実行ログ・トレース用

各ノード（Node）の責務と内部処理

条件付きエッジと自己修正ループ (src/graph/edges.py)

def should_retry(state: AgentState) -> str:
    report = state.get("citation_report", {})
    consistency_rate = report.get("consistency_rate", 1.0)
    retry_count = state.get("retry_count", 0)

    # 引用一致率が 70% 未満で、再試行回数が 2 回以内の場合は自己修正ループへ
    if consistency_rate < 0.70 and retry_count < 2:
        return "retry_synthesis"
    return "finalize"

3.2 Model Context Protocol (MCP) アーキテクチャ

配置: src/mcp_server/server.py, src/mcp_server/client.py, src/mcp_server/tools/
目的: LLM エージェントと外部財務データベース／リアルタイム市場 API の接続を標準化し、強結合を防止。

3.3 ハイブリッド検索 & RRF 融合エンジン

配置: src/retrieval/hybrid_retriever.py, src/retrieval/reranker.py
本番移行用アダプタ（同一インターフェース形状、ランタイム未接続の仕様定義層）: src/retrieval/es_adapter.py（Elasticsearch 8.x Kuromoji + KNN）, src/retrieval/discovery_engine_adapter.py（GCP Discovery Engine / Vertex AI Search のハイブリッド検索リクエスト構築・レスポンス正規化）。

日本語・金融数値特化型 BM25

一般的な形態素解析器では分断されやすい「5兆3529億円」「0.25%」「350万台」といった英数字・単位の複合トークンを正規表現で最優先抽出し、漢字・カタカナ部分を CJK Bi-gram（2文字スライディングウィンドウ）でインデックス化。

Reciprocal Rank Fusion (RRF) 数理モデル

3.4 引用一致率（Citation Attribution）監査エンジン

配置: src/citation/extractor.py, src/citation/verifier.py
生成文を形態素・文境界単位で分解し、引用タグに対応する参照先 Chunk 内に主張内容の数値・固有名詞が存在するか検証。

flowchart TD
    RawAnswer["生成された回答テキスト"] --> SentenceSplit["句点（。）・改行による文分割"]
    SentenceSplit --> ForEach["各文のループ処理"]
    ForEach --> ExtractTag["文中の引用タグ ([doc_X], [mcp_val_Y]) を抽出"]
    ExtractTag --> HasTag{"引用タグが存在するか？"}
    
    HasTag -- No --> CheckFacts{"文中に重要な金融数値・事実主張が含まれるか？"}
    CheckFacts -- Yes --> UncitedPenalty["未引用事実として Recall ペナルティ加算"]
    CheckFacts -- No --> Neutral["一般的な接続詞・要約文として除外"]
    
    HasTag -- Yes --> FetchDoc["対応する Chunk ID または MCP データを取得"]
    FetchDoc --> TokenMatch["文中の数値・重要トークンが引用先テキストに包含されているか検証"]
    TokenMatch --> IsConsistent{"数値・事実が完全一致するか？"}
    
    IsConsistent -- Yes --> PassSentence["一致文 (Consistent) としてカウント"]
    IsConsistent -- No --> FailSentence["不一致文 (Inconsistent / 幻覚) としてマーク"]
    
    PassSentence & FailSentence & UncitedPenalty --> CalcReport["CitationAuditReport (一致率・適合率・再現率) を算出"]
          

3.5 配信層・ストリーミング設計 (FastAPI + SSE)

配置: src/api/app.py, src/api/routes.py

3.6 夜間非同期バッチパイプライン

配置: src/batch/nightly_disclosure_batch.py
東証大引け（15:00）後の適時開示ラッシュを想定し、asyncio.Semaphore(max_concurrency=4) による並行度制御を行い、全銘柄の決算短信を一括分析して引用監査付きレポートを出力。

3.7 可観測性 (Observability) & 構造化ログ

配置: src/monitoring/telemetry.py
W3C TraceContext (traceparent) および Datadog APM / OpenSearch 構造化 JSON ログ規格に準拠。

{
  "timestamp": "2026-09-15T14:00:00.000Z",
  "level": "INFO",
  "service": "financial-rag-agent",
  "trace_id": "8f3b2a1c...",
  "span_id": "4d9e0f...",
  "event": "workflow_completed",
  "duration_ms": 24.2,
  "metrics": {
    "retrieved_count": 5,
    "mcp_tools_invoked": 1,
    "consistency_rate": 0.933,
    "audit_status": "PASS"
  }
}

3.8 LLM Provider フォールバック戦略

配置: src/llm/cli_provider.py（既定・最優先）, src/llm/cloud_provider.py（opt-in 兜底）, src/graph/nodes/synthesizer.py（呼び出し順序の統括）

回答生成（Synthesizer ノード）の LLM 呼び出しは、コスト・レイテンシ・API Key 依存を最小化するため以下の 3 段フォールバック順で実行される。ローカル CLI が常に最優先であり、クラウド Provider は明示的に設定した場合にのみ 2 段目として関与する。

4. データモデル・スキーマ定義

• StockValuation (src/models/finance.py): 銘柄コード、会社名、株価、時価総額、PER、PBR、ROE、配当利回り、TSR、データソース種別。
• RetrievedChunk (src/models/document.py): Chunk ID (doc_xxx)、タイトル、本文、BM25/Dense/RRF スコア、出所。
• CitationAuditReport (src/models/document.py): 引用一致率、適合率、再現率、総合判定 (PASS/WARN/FAIL)、文単位検証ログ。

5. 非機能要件設計