RAG（Retrieval-Augmented Generation）を活用したドキュメント検索システムのデモアプリケーションです。社内ドキュメントに対して自然言語で質問でき、根拠のある回答を得ることができます。

• ストリーミングレスポンス - ChatGPTのようなリアルタイム表示
• マルチターン会話 - セッション内で会話履歴を保持
• ドキュメント管理 - アップロード・プレビュー・削除
• 出典表示 - ファイル名・行番号付きで回答の根拠を明示
• オンボーディング - 初回訪問者向けのガイドツールチップ
• レート制限 - Gemini無料枠に対応
• モバイルレスポンシブ - スマートフォンでも快適に利用可能

[Vercel]              [HF Spaces]           [Chroma]
Next.js 16     <--->   FastAPI      <--->   Vector DB
フロントエンド          バックエンド            永続化
     ↑                     ↑
     └─────── SSE ─────────┘
          (ストリーミング)

simple-rag-app/
├── frontend/              # Next.js フロントエンド
│   ├── app/
│   │   ├── components/    # UIコンポーネント
│   │   ├── page.tsx
│   │   └── layout.tsx
│   ├── lib/               # API・定数・型定義
│   ├── hooks/             # カスタムフック
│   └── package.json
│
├── backend/               # Python バックエンド
│   ├── app/
│   │   ├── routers/       # APIエンドポイント
│   │   ├── services/      # ビジネスロジック
│   │   ├── models/        # データモデル
│   │   └── utils/         # ユーティリティ
│   ├── pyproject.toml
│   └── Dockerfile
│
├── dev-notes/             # 開発メモ
└── README.md

• Node.js 20+
• Python 3.12+
• uv (Pythonパッケージマネージャー)
• Google API Key (こちらから取得)

cd backend

# 依存関係をインストール
uv sync

# 環境変数を設定
cp .env.example .env
# .envファイルを編集してGOOGLE_API_KEYを設定

# 開発サーバーを起動
uv run uvicorn app.main:app --reload --port 7860

cd frontend

# 依存関係をインストール
pnpm install

# 環境変数を設定（任意）
# NEXT_PUBLIC_API_URL=http://localhost:7860

# 開発サーバーを起動
pnpm run dev

ブラウザで http://localhost:3000 を開いてください。

このプロジェクトはGitHub Actionsを使用した自動デプロイに対応しています。

GitHub (main branch)
    │
    ├─── frontend/** 変更 ──► GitHub Actions (CI) ──► Vercel (自動デプロイ)
    │
    └─── backend/** 変更 ──► GitHub Actions ──► Hugging Face Spaces

1. Hugging Faceでアカウントを作成
2. 新しいSpaceを作成
   • Space name: rag-demo（任意）
   • SDK: Docker
   • Visibility: Public または Private
3. SecretsにGOOGLE_API_KEYを設定

リポジトリの Settings > Secrets and variables > Actions で以下を設定:

Secrets:

Variables:

1. Vercelでアカウントを作成
2. GitHubリポジトリをインポート
3. 設定:
   • Root Directory: frontend
   • Framework Preset: Next.js（自動検出）
4. 環境変数にNEXT_PUBLIC_API_URLを設定

# バックエンドを手動でHF Spacesにデプロイ
cd backend
git init
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/rag-demo
git add .
git commit -m "Manual deploy"
git push --force space main

cd backend
uv run pytest

cd frontend
pnpm run build

このプロジェクトを通じて学んだ主なポイント:

1. チャンキング - chunk_overlapはchunk_sizeの10-20%が推奨。文脈の断絶を防ぐ
2. Embedding - 意味的類似性を捉えるベクトル表現の重要性
3. SSEストリーミング - ChatGPTのようなUXを実現するServer-Sent Events
4. Reactのステール・クロージャ - 非同期処理ではuseRefか関数型setStateを活用

詳細は dev-notes/ を参照してください。

MIT License

このプロジェクトはRAGの学習とデモ目的で作成されました。