# 簡易ナレッジベース (Simple Knowledge Base) - システム設計ドキュメント

## 1. プロジェクト概要

本プロジェクトは、React + NestJS をベースに開発されたフルスタックのナレッジベースQ&Aシステム（RAG - Retrieval-Augmented Generation）です。
ユーザーは多様な形式のドキュメントをアップロードし、チャンク分割やインデックス設定をカスタマイズした上で、大規模言語モデル（LLM）を利用してナレッジベースに基づいた質問応答を行うことができます。

---

## 2. コアアーキテクチャ設計

### 2.1 技術スタック

- **フロントエンド**: React 19 + TypeScript + Vite + Tailwind CSS
- **バックエンド**: NestJS + LangChain + TypeORM
- **データベース**: SQLite (ユーザー、モデル設定、ナレッジベースのメタデータ)
- **ベクトルストレージ**: Elasticsearch
- **ファイル処理**: Apache Tika (高速モード) + Vision Pipeline (高精度モード)
- **認証**: JWT
- **ドキュメント変換**: LibreOffice + ImageMagick

### 2.2 システムアーキテクチャ

```
ユーザー -> Reactフロントエンド -> NestJSバックエンド -> SQLite/Elasticsearch
                        |
                        v
                   LangChain Agent
                        |
                        v
                   大言語モデル (LLM)

高精度モードのプロセス:
PDF/Word/PPT -> LibreOffice -> PDF -> ImageMagick -> Vision Model -> 構造化コンテンツ
```

---

## 3. コア機能モジュール

### 3.1 ユーザー認証システム

- **JWT 認証**: ユーザー名/パスワードに基づくログインシステム
- **ユーザー管理**: ユーザー登録、パスワード変更をサポート
- **権限制御**: ユーザーデータの隔離。各ユーザーに独立したナレッジベースを提供
- **管理画面**: 統合された設定モーダルによるユーザー管理（作成/リスト表示）

### 3.2 モデル設定管理

- **マルチプロバイダー対応**:
  - **OpenAI 互換**: OpenAI API および互換インターフェース（DeepSeek, Claude など）に対応
  - **Google Gemini**: ネイティブ SDK によるサポート
- **モデルタイプ**:
  - **LLM**: 対話生成モデル
  - **Embedding**: ベクトル化モデル  
  - **Rerank**: 再ランキングモデル
- **ユーザーカスタマイズ**: ユーザーが独自の API キーとモデルパラメータを設定可能
- **ビジョンサポート**: モデルが画像処理に対応しているかどうかのフラグ管理
- **統合管理**: 設定モーダルの「モデル管理」タブで一括管理

### 3.3 ナレッジベース管理

- **ファイルアップロード**: PDF、ドキュメント、画像など多様な形式に対応
- **デュアルモード処理**:
  - **高速モード**: Apache Tika を使用したテキスト抽出
  - **高精度モード**: Vision Pipeline を使用した画像・テキスト混合処理
- **インテリジェント・チャンキング**: チャンクサイズとオーバーラップを調整可能
- **ベクトルインデックス**: ユーザーが選択した Embedding モデルによるベクトル化
- **ステータス管理**: ファイル処理状況の追跡（待機中、インデックス中、完了、失敗）

### 3.4 RAG 質問応答システム

- **インテリジェント検索**:
  - キーワード抽出とクエリの最適化
  - ハイブリッド検索（ベクトル検索 + 全文検索）
  - 類似度しきい値によるフィルタリング
- **ストリーミング生成**:
  - Server-Sent Events (SSE) によるストリーミング出力
  - 処理の進捗をリアルタイムに表示
  - 生成コンテンツを1文字ずつ表示
- **引用追跡**:
  - 回答の出典ファイルを表示
  - 関連するドキュメントセグメントを表示
  - 類似度スコアの表示

### 3.5 多言語サポート

- **インターフェースの国際化**: 日本語、中国語、英語に対応
- **インテリジェント回答**: ユーザーの言語設定に基づいた AI による回答
- **言語設定の永続化**: ユーザーの選択した言語を自動保存

---

## 4. データモデル設計

### 4.1 SQLite テーブル

**ユーザー表 (users)**

- id, username, password_hash, is_admin, created_at

**モデル設定表 (model_configs)**  

- id, user_id, name, provider, model_id, base_url, api_key, type, supports_vision

**ナレッジベースファイル表 (knowledge_bases)**

- id, user_id, name, original_name, storage_path, size, mimetype, status, created_at

**ユーザー設定表 (user_settings)**

- user_id, selected_llm_id, selected_embedding_id, temperature, max_tokens, top_k, similarity_threshold, language

### 4.2 Elasticsearch インデックス

**ナレッジベース・チャンクインデックス (knowledge_base_chunks)**

```json
{
  "chunk_id": "string",
  "knowledge_base_id": "string", 
  "user_id": "string",
  "file_name": "string",
  "content": "text",
  "embedding": "dense_vector[1536]",
  "chunk_index": "integer",
  "metadata": "object"
}
```

---

## 5. API エンドポイント設計

### 5.1 認証

- `POST /auth/login` - ログイン
- `POST /auth/register` - ユーザー登録  
- `POST /auth/change-password` - パスワード変更

### 5.2 モデル管理

- `GET /model-configs` - モデル設定の取得
- `POST /model-configs` - モデル設定の作成
- `PUT /model-configs/:id` - モデル設定の更新
- `DELETE /model-configs/:id` - モデル設定の削除

### 5.3 ナレッジベース

- `POST /upload` - ファイルアップロード
- `GET /knowledge-bases` - ファイル一覧の取得
- `DELETE /knowledge-bases/:id` - ファイルの削除
- `DELETE /knowledge-bases/clear` - ナレッジベースの全削除

### 5.4 チャット

- `POST /chat/stream` - ストリーミングチャット（SSE）

### 5.5 ユーザー設定

- `GET /user-settings` - 設定の取得
- `PUT /user-settings` - 設定の更新

---

## 6. コアフロー

### 6.1 ファイル処理フロー

**高速モード**:

```
アップロード → メタデータ保存 → Tikaテキスト抽出 → チャンク分割 → ベクトル化 → ESインデックス → ステータス更新
```

**高精度モード**:

```
アップロード → LibreOffice変換 → PDF画像化 → Vision分析 → 構造化コンテンツ → ベクトル化 → ESインデックス
```

### 6.2 RAG 質問応答フロー  

```
ユーザーの質問 → キーワード抽出 → ハイブリッド検索 → 類似度フィルタリング → プロンプト構築 → LLM生成 → ストリーミング出力 → 引用表示
```

---

## 7. デプロイ構成

### 7.1 開発環境

- フロントエンド: Vite 開発サーバー (ポート 5173)
- バックエンド: NestJS 開発サーバー (ポート 3000)  
- Elasticsearch: Docker コンテナ (ポート 9200)
- Apache Tika: Docker コンテナ (ポート 9998)

### 7.2 本番環境

- Docker Compose を使用したコンテナ化デプロイ
- Nginx によるリバースプロキシと負荷分散
- SSL 証明書の設定

---

## 8. 特徴的な機能

- ✅ **ユーザー分離**: ユーザーごとに独立したモデル設定とナレッジベースを保持
- ✅ **ストリーミング体験**: 処理状況と生成内容をリアルタイム表示  
- ✅ **インテリジェント検索**: キーワード抽出 + ハイブリッド検索 + 類似度フィルタリング
- ✅ **引用追跡**: 回答の根拠となるソースと関連セグメントを明確に表示
- ✅ **マルチモデル対応**: OpenAI 互換インターフェース + Gemini ネイティブサポート
- ✅ **柔軟な設定**: ユーザー独自の API キーと推論パラメータのカスタマイズ
- ✅ **多言語対応**: UI と AI 回答の完全な国際化サポート
- ✅ **ビジョン機能**: 画像処理に対応したマルチモーダルモデルのサポート
- ✅ **デュアルモード処理**: 高速モード (テキストのみ) + 高精度モード (画像・テキスト混合)
