金融特化型 RAG & 引用一致率監査エージェント 利用マニュアル・運用手順書

Operations & User Manual | 本番環境管理、Web コンソール、API インテグレーション、Eval 自動化

1. はじめに

本書は、金融特化型 RAG & 引用一致率監査エージェント（financial-rag-agent）のセットアップ、運用保守、Web コンソール操作、API 連携、およびバッチジョブ実行に関する包括的な手順書です。

2. 環境構築とセットアップ

2.1 必要要件

• OS: Linux (Ubuntu 22.04 LTS 以降推奨)
• Python: 3.11 または 3.12
• ネットワーク: yfinance 経由で市場データを取得する場合、外部 HTTPS 接続が必要

2.2 リポジトリと仮想環境の準備

# 1. プロジェクトディレクトリへ移動
cd /home/ubuntu/ws/financial-rag-agent

# 2. 仮想環境の作成
python3 -m venv .venv

# 3. 仮想環境の有効化
source .venv/bin/activate

# 4. 依存パッケージのインストール
pip install --upgrade pip
pip install -r requirements.txt

2.3 環境変数の設定 (.env)

# 基本動作設定
APP_NAME=financial-rag-agent
DEBUG=false
HOST=127.0.0.1
PORT=8800

# データソース初期モード: "snapshot" または "live_api"
DATA_SOURCE_MODE=snapshot

# 検索パラメータ
RETRIEVAL_TOP_K=5
RRF_K=60

# 引用監査閾値
CITATION_MIN_CONSISTENCY=0.70
MAX_SYNTHESIS_RETRIES=2

# LLM Provider: ローカル CLI が既定・最優先（API Key 不要）。
# 以下はすべて任意 — 未設定なら CLI → テンプレートの既存挙動のまま。
# CLI 失敗時のみ、かつ明示的に設定した場合だけクラウドへ opt-in 兜底する。
LLM_CLOUD_FALLBACK_ORDER=            # 例: "azure_openai,vertex_ai"（空なら無効）
LLM_CLOUD_TIMEOUT=60

# Azure OpenAI（LLM_CLOUD_FALLBACK_ORDER に azure_openai を含めた場合のみ使用）
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=2024-10-21

# Google Vertex AI（vertex_ai を含めた場合のみ使用。認証は API Key ではなく
# Application Default Credentials＝ gcloud auth application-default login）
VERTEX_PROJECT_ID=
VERTEX_LOCATION=asia-northeast1
VERTEX_MODEL=gemini-1.5-pro

3. 起動とプロセス管理

3.1 開発・検証環境での起動

source .venv/bin/activate
uvicorn src.api.app:app --host 127.0.0.1 --port 8800 --reload

ワンタイムのターミナル対話デモを実行する場合：

python demo.py

3.2 本番環境での常駐運用 (systemd)

ユニットファイル定義: /etc/systemd/system/financial-rag-agent.service

[Unit]
Description=Financial RAG & Citation Attribution Agent
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/ws/financial-rag-agent
ExecStart=/home/ubuntu/ws/financial-rag-agent/.venv/bin/uvicorn src.api.app:app --host 127.0.0.1 --port 8800 --workers 2
Restart=always
RestartSec=5
EnvironmentFile=-/home/ubuntu/ws/financial-rag-agent/.env

[Install]
WantedBy=multi-user.target

運用管理コマンド

# サービスの状態確認
sudo systemctl status financial-rag-agent

# サービスの再起動（コード変更反映時）
sudo systemctl restart financial-rag-agent

# サービスの停止 / 起動
sudo systemctl stop financial-rag-agent
sudo systemctl start financial-rag-agent

# リアルタイムログの閲覧
journalctl -u financial-rag-agent -f

3.3 Caddy リバースプロキシの設定

f.0101.click {
    reverse_proxy localhost:8800 {
        # SSE の打字機リアルタイムストリーミングを阻害しないようバッファリングを無効化
        flush_interval -1
    }
}

sudo caddy validate
sudo caddy reload

4. Web Showcase コンソールの利用ガイド

ブラウザで https://f.0101.click/ にアクセスします。

4.1 画面レイアウトと機能

5. API 仕様と呼び出し例

5.1 全ストリーミング推論 (POST /api/v1/chat/stream)

打字機風のトークンストリーミングと、中間ステートマシンの監査イベントを受信します。

curl -N -X POST https://f.0101.click/api/v1/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "query": "トヨタ自動車の営業利益と今後のBEV戦略について教えてください",
    "data_source_mode": "live_api"
  }'

5.2 同期推論 (POST /api/v1/chat/sync)

curl -X POST https://f.0101.click/api/v1/chat/sync \
  -H "Content-Type: application/json" \
  -d '{
    "query": "日銀の追加利上げ方針と為替への影響は？",
    "data_source_mode": "snapshot"
  }'

5.3 データソース動的変更 (POST /api/v1/settings)

# リアルタイムモードへ動的切替
curl -X POST https://f.0101.click/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"data_source_mode": "live_api"}'

# 設定状況の確認
curl -s https://f.0101.click/api/v1/settings

6. バッチ処理の実行手順

東証大引け（15:00）後の適時開示ラッシュを一括処理する深夜非同期バッチです。

cd /home/ubuntu/ws/financial-rag-agent
source .venv/bin/activate

# 夜間適時開示バッチの実行
python -m src.batch.nightly_disclosure_batch --concurrency 4 --mode live_api

cron 定期実行の登録例

30 17 * * 1-5 /home/ubuntu/ws/financial-rag-agent/.venv/bin/python -m src.batch.nightly_disclosure_batch >> /home/ubuntu/ws/financial-rag-agent/batch.log 2>&1

7. 評価（Eval）と自動回帰テストの実行方法

7.1 CI/CD 向け自動評価ベンチマーク

python eval/run_eval.py

7.2 ユニットおよび統合テストスイート

pytest -v
# 53 passed in 8.9s

test_cloud_provider.py（Azure OpenAI / Vertex AI Provider の成功・未設定・SDK未インストール・例外時フォールバックを SDK モックで検証）と、test_local_cli_synthesis.py に追加された CLI 優先順位の回帰テスト（CLI 成功時はクラウドが一切呼ばれないこと／CLI 失敗かつ未設定時はクラウドに触れないこと）を含む。

8. トラブルシューティング & FAQ