From b21899055d4f8fa0b25b679a5b6692bb69011588 Mon Sep 17 00:00:00 2001 From: Developer Date: Tue, 16 Jun 2026 14:31:44 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B8=85=E7=90=86=20docs=20=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E5=86=97=E4=BD=99=E6=96=87=E6=A1=A3=EF=BC=8855?= =?UTF-8?q?=E4=B8=AA=E2=86=929=E4=B8=AA=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删除: - docs/1.0/ 全部22个（旧Simple KB文档，已被替代） - docs/2.0/ 全部2个（空文件/过时） - docs/design/ 全部4个（旧功能设计） - docs/plans/ 旧版5个（保留v2.0设计文档） - docs/superpowers/ 全部4个（飞书集成文档） - docs/根目录杂项 8个（开发规范/快速参考/调试/飞书/Git设置） - docs/3.0/knowledge_graph_analysis.md（不相关） 保留: - docs/3.0/ 考核工作流设计 2个 - docs/plans/ v2.0设计文档 1个 - docs/tests/ 测试文档 6个 合计: 55个 → 9个 Co-Authored-By: Claude Opus 4.8 --- docs/1.0/API.md | 444 ------ docs/1.0/CHUNK_SIZE_LIMITS.md | 361 ----- docs/1.0/CURRENT_IMPLEMENTATION.md | 165 -- docs/1.0/DEPLOYMENT.md | 444 ------ docs/1.0/DESIGN.md | 217 --- docs/1.0/DEVELOPMENT_STANDARDS.md | 71 - docs/1.0/EMBEDDING_MODEL_ID_FIX.md | 219 --- docs/1.0/FEATURE_SUMMARY.md | 29 - docs/1.0/INTERNAL_DEPLOYMENT_GUIDE.md | 94 -- docs/1.0/INTERNAL_DEPLOYMENT_SUMMARY.md | 40 - docs/1.0/KNOWLEDGE_BASE_ENHANCEMENTS.md | 464 ------ docs/1.0/LARGE_FILE_HANDLING.md | 139 -- docs/1.0/MEMORY_OPTIMIZATION_FIX.md | 348 ----- docs/1.0/PDF_PREVIEW_FIX.md | 90 -- docs/1.0/PROJECT_EXPLANATION_JA.md | 225 --- docs/1.0/PROJECT_EXPLANATION_JA.pdf | Bin 269566 -> 0 bytes docs/1.0/RAG_COMPLETE_IMPLEMENTATION.md | 87 -- docs/1.0/README.md | 47 - docs/1.0/SIMILARITY_SCORE_BUGFIX.md | 249 --- docs/1.0/SUPPORTED_FILE_TYPES.md | 158 -- docs/1.0/VECTOR_DB_COMPARISON_JA.md | 55 - docs/1.0/VECTOR_DB_COMPARISON_JA.pdf | Bin 189814 -> 0 bytes docs/1.0/VISION_PIPELINE_COMPLETE.md | 265 ---- docs/1.0/test_admin_features.md | 32 - docs/2.0/google_workspace_style_ui_mockup.png | Bin 436741 -> 0 bytes docs/2.0/implementation_plan.md | 117 -- docs/2.0/refacting.md | 0 docs/3.0/knowledge_graph_analysis.md | 66 - docs/DEVELOPMENT_STANDARDS.md | 96 -- docs/QUICK-REFERENCE.md | 130 -- docs/admin-credentials.md | 10 - docs/debugging-checklist.md | 531 ------- docs/design/feat-auto-title-generation.md | 68 - docs/design/feat-cross-doc-comparison.md | 59 - docs/design/feat-highlight-jump.md | 37 - docs/design/feat-query-expansion-hyde.md | 52 - docs/docker-hybrid-guide.md | 213 --- ...eishu-assessment-implementation-summary.md | 297 ---- docs/feishu-assessment-integration-design.md | 1341 ----------------- docs/feishu-assessment-integration-summary.md | 208 --- docs/git-setup.md | 58 - .../2026-04-18-l1-talent-assessment-design.md | 405 ----- ...1-talent-assessment-implementation-plan.md | 490 ------ ...6-04-20-assessment-system-complete-plan.md | 593 -------- .../2026-04-23-assessment-system-full-plan.md | 517 ------- .../2026-05-14-code-integration-review.md | 366 ----- .../2026-03-16-feishu-bot-integration.md | 955 ------------ ...2026-03-17-feishu-websocket-integration.md | 727 --------- .../2026-03-17-i18n-japanese-fallback-fix.md | 345 ----- ...-16-talent-assessment-management-design.md | 505 ------- ...-17-feishu-websocket-integration-design.md | 456 ------ 51 files changed, 12885 deletions(-) delete mode 100644 docs/1.0/API.md delete mode 100644 docs/1.0/CHUNK_SIZE_LIMITS.md delete mode 100644 docs/1.0/CURRENT_IMPLEMENTATION.md delete mode 100644 docs/1.0/DEPLOYMENT.md delete mode 100644 docs/1.0/DESIGN.md delete mode 100644 docs/1.0/DEVELOPMENT_STANDARDS.md delete mode 100644 docs/1.0/EMBEDDING_MODEL_ID_FIX.md delete mode 100644 docs/1.0/FEATURE_SUMMARY.md delete mode 100644 docs/1.0/INTERNAL_DEPLOYMENT_GUIDE.md delete mode 100644 docs/1.0/INTERNAL_DEPLOYMENT_SUMMARY.md delete mode 100644 docs/1.0/KNOWLEDGE_BASE_ENHANCEMENTS.md delete mode 100644 docs/1.0/LARGE_FILE_HANDLING.md delete mode 100644 docs/1.0/MEMORY_OPTIMIZATION_FIX.md delete mode 100644 docs/1.0/PDF_PREVIEW_FIX.md delete mode 100644 docs/1.0/PROJECT_EXPLANATION_JA.md delete mode 100644 docs/1.0/PROJECT_EXPLANATION_JA.pdf delete mode 100644 docs/1.0/RAG_COMPLETE_IMPLEMENTATION.md delete mode 100644 docs/1.0/README.md delete mode 100644 docs/1.0/SIMILARITY_SCORE_BUGFIX.md delete mode 100644 docs/1.0/SUPPORTED_FILE_TYPES.md delete mode 100644 docs/1.0/VECTOR_DB_COMPARISON_JA.md delete mode 100644 docs/1.0/VECTOR_DB_COMPARISON_JA.pdf delete mode 100644 docs/1.0/VISION_PIPELINE_COMPLETE.md delete mode 100644 docs/1.0/test_admin_features.md delete mode 100644 docs/2.0/google_workspace_style_ui_mockup.png delete mode 100644 docs/2.0/implementation_plan.md delete mode 100644 docs/2.0/refacting.md delete mode 100644 docs/3.0/knowledge_graph_analysis.md delete mode 100644 docs/DEVELOPMENT_STANDARDS.md delete mode 100644 docs/QUICK-REFERENCE.md delete mode 100644 docs/admin-credentials.md delete mode 100644 docs/debugging-checklist.md delete mode 100644 docs/design/feat-auto-title-generation.md delete mode 100644 docs/design/feat-cross-doc-comparison.md delete mode 100644 docs/design/feat-highlight-jump.md delete mode 100644 docs/design/feat-query-expansion-hyde.md delete mode 100644 docs/docker-hybrid-guide.md delete mode 100644 docs/feishu-assessment-implementation-summary.md delete mode 100644 docs/feishu-assessment-integration-design.md delete mode 100644 docs/feishu-assessment-integration-summary.md delete mode 100644 docs/git-setup.md delete mode 100644 docs/plans/2026-04-18-l1-talent-assessment-design.md delete mode 100644 docs/plans/2026-04-18-l1-talent-assessment-implementation-plan.md delete mode 100644 docs/plans/2026-04-20-assessment-system-complete-plan.md delete mode 100644 docs/plans/2026-04-23-assessment-system-full-plan.md delete mode 100644 docs/plans/2026-05-14-code-integration-review.md delete mode 100644 docs/superpowers/plans/2026-03-16-feishu-bot-integration.md delete mode 100644 docs/superpowers/plans/2026-03-17-feishu-websocket-integration.md delete mode 100644 docs/superpowers/plans/2026-03-17-i18n-japanese-fallback-fix.md delete mode 100644 docs/superpowers/specs/2026-03-16-talent-assessment-management-design.md delete mode 100644 docs/superpowers/specs/2026-03-17-feishu-websocket-integration-design.md diff --git a/docs/1.0/API.md b/docs/1.0/API.md deleted file mode 100644 index 2fd758e..0000000 --- a/docs/1.0/API.md +++ /dev/null @@ -1,444 +0,0 @@ -# API リファレンス - -## 基本情報 - -- **ベース URL**: `http://localhost:3000` -- **認証方式**: JWT Bearer トークン -- **Content-Type**: `application/json` - -## 認証 API - -### ユーザー登録 - -```http -POST /auth/register -Content-Type: application/json - -{ - "username": "string", - "password": "string" -} -``` - -**レスポンス**: - -```json -{ - "message": "ユーザーが正常に作成されました", - "user": { - "id": "string", - "username": "string", - "isAdmin": false - } -} -``` - -### ユーザーログイン - -```http -POST /auth/login -Content-Type: application/json - -{ - "username": "string", - "password": "string" -} -``` - -**レスポンス**: - -```json -{ - "access_token": "jwt_token_string", - "user": { - "id": "string", - "username": "string", - "isAdmin": false - } -} -``` - -### パスワード変更 - -```http -POST /auth/change-password -Authorization: Bearer -Content-Type: application/json - -{ - "currentPassword": "string", - "newPassword": "string" -} -``` - -## モデル設定 API - -### モデル一覧の取得 - -```http -GET /model-configs -Authorization: Bearer -``` - -**レスポンス**: - -```json -[ - { - "id": "string", - "name": "string", - "provider": "openai|gemini", - "modelId": "string", - "baseUrl": "string", - "type": "llm|embedding|rerank", - "supportsVision": boolean - } -] -``` - -### モデル設定の作成 - -```http -POST /model-configs -Authorization: Bearer -Content-Type: application/json - -{ - "name": "string", - "provider": "openai|gemini", - "modelId": "string", - "baseUrl": "string", - "apiKey": "string", - "type": "llm|embedding|rerank", - "supportsVision": boolean -} -``` - -### モデル設定の更新 - -```http -PUT /model-configs/:id -Authorization: Bearer -Content-Type: application/json - -{ - "name": "string", - "apiKey": "string", - // ... その他のフィールド -} -``` - -### モデル設定の削除 - -```http -DELETE /model-configs/:id -Authorization: Bearer -``` - -## ナレッジベース API - -### ファイルのアップロード - -```http -POST /upload -Authorization: Bearer -Content-Type: multipart/form-data - -{ - "file": File, - "chunkSize": number, - "chunkOverlap": number, - "embeddingModelId": "string", - "mode": "fast|precise" // 処理モード -} -``` - -**レスポンス**: - -```json -{ - "id": "string", - "name": "string", - "originalName": "string", - "size": number, - "mimetype": "string", - "status": "pending|indexing|completed|failed" -} -``` - -### ファイル一覧の取得 - -```http -GET /knowledge-bases -Authorization: Bearer -``` - -**レスポンス**: - -```json -[ - { - "id": "string", - "name": "string", - "originalName": "string", - "size": number, - "mimetype": "string", - "status": "pending|indexing|completed|failed", - "createdAt": "datetime" - } -] -``` - -### ファイルの削除 - -```http -DELETE /knowledge-bases/:id -Authorization: Bearer -``` - -### ナレッジベースの全消去 - -```http -DELETE /knowledge-bases/clear -Authorization: Bearer -``` - -## チャット API - -### ストリーミングチャット - -```http -POST /chat/stream -Authorization: Bearer -Content-Type: application/json - -{ - "message": "string", - "history": [ - { - "role": "user|assistant", - "content": "string" - } - ], - "userLanguage": "zh|en|ja" -} -``` - -**レスポンス**: Server-Sent Events (SSE) - -``` -data: {"type": "content", "data": "ナレッジベースを検索中..."} - -data: {"type": "content", "data": "関連情報が見つかりました..."} - -data: {"type": "content", "data": "回答内容の断片"} - -data: {"type": "sources", "data": [ - { - "fileName": "string", - "content": "string", - "score": number, - "chunkIndex": number - } -]} - -data: [DONE] -``` - -## ユーザー設定 API - -### ユーザー設定の取得 - -```http -GET /user-settings -Authorization: Bearer -``` - -**レスポンス**: - -```json -{ - "selectedLLMId": "string", - "selectedEmbeddingId": "string", - "selectedRerankId": "string", - "temperature": number, - "maxTokens": number, - "topK": number, - "enableRerank": boolean, - "similarityThreshold": number, - "enableFullTextSearch": boolean, - "language": "zh|en|ja" -} -``` - -### ユーザー設定の更新 - -```http -PUT /user-settings -Authorization: Bearer -Content-Type: application/json - -{ - "selectedLLMId": "string", - "temperature": number, - "maxTokens": number, - // ... その他の設定フィールド -} -``` - -## Vision Pipeline API - -### 推奨モードの取得 - -```http -GET /api/vision/recommend-mode?file=xxx&size=xxx -Authorization: Bearer -``` - -**レスポンス**: - -```json -{ - "recommendedMode": "precise", - "reason": "ファイルサイズが大きいため、高精度モードを推奨します", - "estimatedCost": 0.5, - "estimatedTime": 60, - "warnings": ["処理時間が長くなる可能性があります", "API 利用料が発生します"] -} -``` - -### LibreOffice 変換サービス - -```http -POST /libreoffice/convert -Content-Type: multipart/form-data - -{ - "file": File -} -``` - -**レスポンス**: - -```json -{ - "pdf_path": "/uploads/document.pdf", - "converted": true, - "original": "document.docx", - "file_size": 102400 -} -``` - -### ヘルスチェック - -```http -GET /libreoffice/health -``` - -**レスポンス**: - -```json -{ - "status": "healthy", - "service": "libreoffice-converter", - "version": "1.0.0", - "uptime": 3600.5 -} -``` - -## ユーザー管理 API (管理者用) - -### ユーザー一覧の取得 - -```http -GET /users -Authorization: Bearer -``` - -### ユーザーの作成 - -```http -POST /users -Authorization: Bearer -Content-Type: application/json - -{ - "username": "string", - "password": "string", - "isAdmin": boolean -} -``` - -### ユーザーの削除 - -```http -DELETE /users/:id -Authorization: Bearer -``` - -## エラーレスポンス形式 - -```json -{ - "statusCode": number, - "message": "string", - "error": "string" -} -``` - -## ステータスコードの説明 - -- `200` - 成功 -- `201` - 作成成功 -- `400` - リクエストパラメータの不正 -- `401` - 認証エラー / トークン無効 -- `403` - 権限不足 -- `404` - リソースが見つかりません -- `409` - リソースの競合 -- `500` - サーバー内部エラー - -## 実装例 - -### JavaScript/TypeScript - -```javascript -// ログイン -const loginResponse = await fetch('/auth/login', { - method: 'POST', - headers: { - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - username: 'user', - password: 'password' - }) -}); - -const { access_token } = await loginResponse.json(); - -// ファイル一覧の取得 -const filesResponse = await fetch('/knowledge-bases', { - headers: { - 'Authorization': `Bearer ${access_token}` - } -}); - -const files = await filesResponse.json(); - -// ストリーミングチャット -const chatResponse = await fetch('/chat/stream', { - method: 'POST', - headers: { - 'Authorization': `Bearer ${access_token}`, - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - message: 'こんにちは', - history: [], - userLanguage: 'ja' - }) -}); - -const reader = chatResponse.body.getReader(); -// SSE ストリームの処理... -``` diff --git a/docs/1.0/CHUNK_SIZE_LIMITS.md b/docs/1.0/CHUNK_SIZE_LIMITS.md deleted file mode 100644 index d5e3eeb..0000000 --- a/docs/1.0/CHUNK_SIZE_LIMITS.md +++ /dev/null @@ -1,361 +0,0 @@ -# チャンクサイズの制限に関する完全スキーム - -## 🎯 設計目標 - -**主要な問題の解決：** - -1. ✅ チャンクサイズがモデルの入力制限を超えないようにする -2. ✅ 環境変数でグローバルな上限を設定可能にする -3. ✅ フロントエンドのスライダーで動的に制限し、上限を超えられないようにする -4. ✅ バックエンドで自動検証と調整を行う - ---- - -## 📋 設定階層構造 - -``` -┌─────────────────────────────────────────┐ -│ 環境変数の設定 (server/.env) │ -│ MAX_CHUNK_SIZE=8191 │ -│ MAX_OVERLAP_SIZE=200 │ -└─────────────────────────────────────────┘ - ↓ 優先度1（最も厳格） -┌─────────────────────────────────────────┐ -│ モデル制限設定 (ChunkConfigService) │ -│ OpenAI: 8191 tokens │ -│ Gemini: 2048 tokens │ -└─────────────────────────────────────────┘ - ↓ 優先度2 -┌─────────────────────────────────────────┐ -│ ユーザー設定 (フロントエンドスライダー)│ -│ chunkSize: 200 tokens │ -│ chunkOverlap: 40 tokens │ -└─────────────────────────────────────────┘ - ↓ 最終検証 -┌─────────────────────────────────────────┐ -│ 実際に適用される値 (自動調整) │ -└─────────────────────────────────────────┘ -``` - ---- - -## 🔧 環境変数の設定 - -### server/.env - -```env -# チャンクサイズの上限 (tokens) -# 使用する埋め込みモデルに合わせて設定 -# OpenAI text-embedding-3-large: 8191 -# OpenAI text-embedding-3-small: 8191 -# Google Gemini embedding-001: 2048 -MAX_CHUNK_SIZE=8191 - -# チャンクオーバーラップの上限 (tokens) -# チャンクサイズの 10-20% を推奨 -MAX_OVERLAP_SIZE=200 -``` - ---- - -## 🏗️ アーキテクチャの実装 - -### 1. ChunkConfigService (バックエンドコア) - -```typescript -// 環境変数から上限を読み込む -private readonly envMaxChunkSize: number; -private readonly envMaxOverlapSize: number; - -// 主要なモデルの制限 -private readonly MODEL_LIMITS = { - 'text-embedding-3-large': { - maxInputTokens: 8191, - maxBatchSize: 2048, - expectedDimensions: 3072, - }, - 'embedding-001': { - maxInputTokens: 2048, - maxBatchSize: 100, - expectedDimensions: 768, - }, -}; - -// 最終的な上限を計算 -const effectiveMaxChunkSize = Math.min( - this.envMaxChunkSize, // 環境変数 - limits.maxInputTokens // モデルの制限 -); -``` - -### 2. 検証ロジック - -```typescript -async validateChunkConfig(chunkSize, chunkOverlap, modelId, userId) { - const warnings = []; - - // 1. 最終的な上限を計算 - const effectiveMaxChunkSize = Math.min( - this.envMaxChunkSize, - limits.maxInputTokens - ); - - // 2. チャンクサイズの検証 - if (chunkSize > effectiveMaxChunkSize) { - warnings.push(`上限 ${effectiveMaxChunkSize} を超えています`); - chunkSize = effectiveMaxChunkSize; - } - - // 3. オーバーラップサイズの検証 - const maxOverlap = Math.min( - this.envMaxOverlapSize, - Math.floor(chunkSize * 0.5) - ); - if (chunkOverlap > maxOverlap) { - warnings.push(`オーバーラップが上限 ${maxOverlap} を超えています`); - chunkOverlap = maxOverlap; - } - - return { - chunkSize, - chunkOverlap, - warnings, - effectiveMaxChunkSize, - effectiveMaxOverlapSize, - }; -} -``` - -### 3. API エンドポイント - -```typescript -// GET /api/knowledge-bases/chunk-config/limits?embeddingModelId=xxx -{ - "maxChunkSize": 8191, - "maxOverlapSize": 200, - "defaultChunkSize": 200, - "defaultOverlapSize": 40, - "modelInfo": { - "name": "text-embedding-3-large", - "maxInputTokens": 8191, - "maxBatchSize": 2048, - "expectedDimensions": 3072 - } -} -``` - ---- - -## 🎨 フロントエンドの実装 - -### IndexingModal.tsx - -```typescript -// 状態管理 -const [limits, setLimits] = useState(null); -const [chunkSize, setChunkSize] = useState(200); -const [chunkOverlap, setChunkOverlap] = useState(40); - -// モデル選択時に制限をロード -useEffect(() => { - if (selectedEmbedding) { - const limitData = await chunkConfigService.getLimits(selectedEmbedding, token); - setLimits(limitData); - - // 現在の値を自動調整 - if (chunkSize > limitData.maxChunkSize) { - setChunkSize(limitData.maxChunkSize); - } - } -}, [selectedEmbedding]); - -// スライダー変更時の処理 -const handleChunkSizeChange = (value) => { - if (limits && value > limits.maxChunkSize) { - showWarning(`最大値は ${limits.maxChunkSize} です`); - setChunkSize(limits.maxChunkSize); - return; - } - setChunkSize(value); - - // オーバーラップの自動調整 - if (chunkOverlap > value * 0.5) { - setChunkOverlap(Math.floor(value * 0.5)); - } -}; -``` - -### UI 機能 - -1. **動的なスライダー範囲** - - ```jsx - - ``` - -2. **制限のリアルタイム表示** - - ``` - チャンクサイズ: 200 tokens (上限: 8191) - ``` - -3. **モデル情報の表示** - - ``` - モデル: text-embedding-3-large - チャンク上限: 8191 tokens - オーバーラップ上限: 200 tokens - バッチ制限: 2048 - ``` - -4. **最適化アドバイス** - - ``` - 💡 最適化アドバイス - • チャンクが大きすぎます (800)。検索精度に影響する可能性があります。 - • 少なくとも 80 tokens のオーバーラップを推奨します。 - • 最大値を使用すると、処理速度が低下する可能性があります。 - ``` - ---- - -## 📊 ユースケース例 - -### シナリオ1: OpenAI + 環境変数による制限 - -**設定:** - -```env -MAX_CHUNK_SIZE=4000 # モデルより厳格なカスタム制限 -``` - -**ユーザー操作:** - -``` -1. モデル選択: text-embedding-3-large -2. スライダー上限: 4000 (環境変数による制限) -3. ユーザー設定: 3000 tokens -4. バックエンド検証: ✅ 合格 -5. 実適用値: 3000 tokens -``` - -### シナリオ2: Gemini + モデルによる制限 - -**設定:** - -```env -MAX_CHUNK_SIZE=8191 # 環境変数は緩和 -``` - -**ユーザー操作:** - -``` -1. モデル選択: embedding-001 -2. スライダー上限: 2048 (モデル制限の方が厳格) -3. ユーザー設定: 1500 tokens -4. バックエンド検証: ✅ 合格 -5. 実適用値: 1500 tokens -``` - -### シナリオ3: 制限超過時の自動調整 - -**ユーザー操作:** - -``` -1. モデル選択: embedding-001 (制限 2048) -2. ユーザー入力: 3000 tokens -3. フロントエンド表示: "最大値は 2048 です" -4. スライダーを自動的に 2048 に調整 -5. バックエンド記録: ⚠️ 設定修正ログ -``` - ---- - -## 🔍 優先順位ルール - -### 上限計算ロジック - -```typescript -最終的な上限 = min(環境変数, モデル制限) - -例: -- 環境変数: 8191 -- モデル制限: 2048 (Gemini) -- 最終上限: 2048 ✅ - -- 環境変数: 4000 -- モデル制限: 8191 (OpenAI) -- 最終上限: 4000 ✅ -``` - -### 検証順序 - -```typescript -1. チャンクサイズ ≤ 最終上限 かを確認 -2. チャンクサイズ ≥ 最小値 (50) かを確認 -3. オーバーラップサイズ ≤ 環境変数の上限 かを確認 -4. オーバーラップサイズ ≤ チャンクサイズの 50% かを確認 -5. オーバーラップサイズ ≥ 0 かを確認 -``` - ---- - -## 📝 デプロイ時の推奨設定 - -### 開発環境 - -```env -# テストに適した設定 -MAX_CHUNK_SIZE=8191 -MAX_OVERLAP_SIZE=200 -``` - -### 本番環境 (OpenAI) - -```env -# 大容量ファイルへの対策を考慮した保守的な設定 -MAX_CHUNK_SIZE=4000 -MAX_OVERLAP_SIZE=500 -``` - -### 本番環境 (Gemini) - -```env -# モデルの制限に合わせた設定 -MAX_CHUNK_SIZE=2048 -MAX_OVERLAP_SIZE=300 -``` - ---- - -## ✅ メリットのまとめ - -| 特徴 | 実装方法 | 効果 | -|------|----------|------| -| **安全性** | 環境変数 + モデル制限の二重保護 | API の制限を超えない | -| **柔軟性** | 環境変数で調整可能 | 異なるデプロイ要件に対応 | -| **ユーザー体験** | フロントエンドでの動的制限 | 無効な値を選択できない | -| **透明性** | 制限情報をリアルタイム表示 | 設定理由が明確 | -| **自動調整** | バックエンドでの検証・修正 | 実行時のエラーを回避 | -| **ログ管理** | 詳細な警告情報 | 問題の切り分けがスムーズ | - ---- - -## 🎯 結論 - -このスキームにより、以下が実現されました： - -1. ✅ **環境変数の設定** - グローバルに制御可能な上限 -2. ✅ **モデル制限の認識** - 異なるモデルの自動識別 -3. ✅ **フロントエンドでの制限** - 無効な値を選択不可に -4. ✅ **バックエンド検証** - 二重の保険 -5. ✅ **自動調整** - 制限超過時の自動修正 -6. ✅ **透明なフィードバック** - 制限理由の表示 - -**これで、ユーザーがモデルの制限を超える値を選択することはなくなり、システムが自動的に保護されます！** diff --git a/docs/1.0/CURRENT_IMPLEMENTATION.md b/docs/1.0/CURRENT_IMPLEMENTATION.md deleted file mode 100644 index 6bd3fce..0000000 --- a/docs/1.0/CURRENT_IMPLEMENTATION.md +++ /dev/null @@ -1,165 +0,0 @@ -# 現在の実装状況ドキュメント - -## システムアーキテクチャ - -### 技術スタック - -- **フロントエンド**: React + TypeScript + Vite + Tailwind CSS -- **バックエンド**: NestJS + LangChain + Elasticsearch + TypeORM -- **データベース**: SQLite (ユーザー、モデル設定、ナレッジベース、ユーザー設定) -- **ベクトルストレージ**: Elasticsearch -- **ファイル処理**: Apache Tika (高速モード) + Vision Pipeline (高精度モード) -- **認証**: JWT -- **ドキュメント変換**: LibreOffice + ImageMagick - -### コアモジュール - -#### 1. ユーザー認証システム (Auth) - -- JWT 認証システム -- ユーザー登録/ログイン/パスワード変更 -- ユーザー管理画面 -- ルート保護と権限制御 - -#### 2. モデル設定管理 (ModelConfig) - -- 多様なモデルプロバイダーをサポート： - - **OpenAI 互換**: OpenAI API および互換インターフェース（DeepSeek, Claude など）に対応 - - **Google Gemini**: ネイティブ SDK によるサポート -- モデルタイプ： - - **LLM**: 対話生成モデル - - **Embedding**: ベクトル化モデル - - **Rerank**: 再ランキングモデル -- ユーザー独自の API キーとモデルパラメータの設定が可能 -- ビジョン機能のフラグ管理をサポート - -#### 3. ナレッジベース管理 (KnowledgeBase) - -- ファイルのアップロードと保存（日本語ファイル名に対応） -- **デュアルモード処理**: - - **高速モード**: Apache Tika によるテキスト抽出 - - **高精度モード**: Vision Pipeline による画像・テキスト混合処理 -- インテリジェントなドキュメントのチャンク分割とベクトル化 -- Elasticsearch インデックスとハイブリッド検索 -- ファイルステータス管理（待機中、インデックス中、完了、失敗） -- 数百種類のファイル形式をサポート: PDF, Word, PPT, Excel, Markdown, コードファイル, 画像など - -#### 4. RAG 質問応答システム (Chat) - -- **ストリーミング出力**: Server-Sent Events (SSE) を利用 -- **インテリジェント検索**: LangChain キーワード抽出 + ES ハイブリッド検索 -- **類似度フィルタリング**: 関連性の低いコンテンツをフィルタリングするしきい値を設定可能 -- **引用表示**: ソースの断片、ファイル名、類似度スコアを表示 -- **多言語サポート**: ユーザーの言語設定に合わせて AI の回答言語を調整 - -#### 5. 統合設定管理 (Unified Settings) - -- **統合設定モーダル**: 各種管理機能を一つのタブ形式インターフェースに集約 - - **一般設定 (General)**: 言語切り替え、パスワード変更 - - **ユーザー管理 (User)**: ユーザー一覧、ユーザー追加（管理者機能） - - **モデル管理 (Model)**: LLM, Embedding, Rerank モデルの設定と管理 -- **クイックアクセス**: サイドバー下部の「設定」ボタンからワンクリックでアクセス可能 -- **一貫した体験**: 統一されたフォーム操作とステータスフィードバック - -## チャットフロー - -``` -ユーザーの質問 → キーワード抽出 → ESハイブリッド検索 → 類似度フィルタリング → コンテキスト構築 → LLMストリーミング生成 → 引用元の表示 -``` - -### 詳細ステップ - -1. **キーワード抽出** - - LangChain を使用して、ユーザーの質問から 3-5 個のキーワードを抽出します。 - - 不要な言葉（「の」「は」「のぼり」など）を除去します。 - -2. **ハイブリッド検索** - - キーワードを組み合わせてベクトル検索を実行します。 - - 全文検索を併用して再現率を向上させます。 - - 類似度しきい値でフィルタリングします。 - - 最も関連性の高いセグメントを返します。 - -3. **ストリーミング生成** - - 処理の進捗を表示します（「ナレッジベースを検索中...」など）。 - - LLM が生成した回答内容をリアルタイムで出力します。 - - 取得したセグメントに基づき、引用付きの回答を生成します。 - - 多言語での回答をサポートします。 - -4. **引用元の表示** - - セグメント内容の要約（最大150文字）を表示します。 - - 出典元ファイル名を表示します。 - - 類似度のパーセンテージを表示します。 - - セグメント番号を表示します。 - -## 主要な API エンドポイント - -### 認証関連 - -- `POST /auth/login` - ログイン -- `POST /auth/register` - ユーザー登録 -- `POST /auth/change-password` - パスワード変更（設定モーダル内から呼び出し） - -### チャット API - -- `POST /chat/stream` - ストリーミングチャット - - ユーザーが設定した LLM モデルと API キーを自動取得 - - OpenAI 互換インターフェースと Gemini をサポート - - SSE ストリーミングレスポンスを返却 - - 多言語パラメータの受け渡しに対応 - -### モデル管理 - -- `GET /model-configs` - モデル設定の一覧取得 -- `POST /model-configs` - モデル設定の作成 -- `PUT /model-configs/:id` - モデル設定の更新 -- `DELETE /model-configs/:id` - モデル設定の削除 - -### ナレッジベース管理 - -- `POST /upload` - ファイルアップロード（チャンクパラメータの設定が可能） -- `GET /knowledge-bases` - ファイル一覧の取得 -- `DELETE /knowledge-bases/:id` - ファイルの削除 -- `DELETE /knowledge-bases/clear` - ナレッジベースの全消去 - -### ユーザー設定 - -- `GET /user-settings` - 設定の取得 -- `PUT /user-settings` - 設定の更新 -- **注**: フロントエンドは統一された `SettingsModal` コンポーネントを介してこれらのエンドポイントと通信します。 - -## 利用方法 - -1. **ユーザー登録/ログイン** -2. **基本構成の設定** - - サイドバー下部の「設定」ボタンをクリックします。 - - 「モデル管理」タブで OpenAI 互換の LLM と Embedding モデルを追加します。 - - API キーとモデルパラメータを設定します。 - - 「一般設定」タブで言語を切り替えたり、パスワードを変更したりできます。 -3. **ドキュメントのアップロード** - - PDF, テキスト, 画像などの形式をサポートします。 - - チャンクサイズと Embedding モデルを設定します。 - - 自動的にベクトル化とインデックス化が行われます。 -4. **詳細設定の調整** - - 使用するモデルを選択します。 - - 推論パラメータと検索パラメータを構成します。 - - UI 言語を設定します。 -5. **対話を開始** - - 質問を送信します。 - - ストリーミング処理の経過を観察します。 - - 引用付きのインテリジェントな回答を確認します。 - -## 特筆すべき機能 - -- ✅ **ユーザー分離**: 各ユーザーに独立したモデル設定とナレッジベースを提供 -- ✅ **ストリーミング体験**: 処理の進捗と生成内容をリアルタイム表示 -- ✅ **インテリジェント検索**: キーワード抽出 + ハイブリッド検索 + 類似度フィルタリング -- ✅ **引用追跡**: 回答の根拠となるソースと関連セグメントを明確に表示 -- ✅ **マルチモデル対応**: OpenAI 互換インターフェース + Gemini ネイティブサポート -- ✅ **柔軟な設定**: ユーザー独自の API キーと推論パラメータのカスタマイズ -- ✅ **多言語サポート**: UI と AI 回答の両方を完全国際化 -- ✅ **ビジョン機能**: 画像処理をサポートするマルチモーダルモデルに対応 -- ✅ **ユーザー管理**: 登録、ログイン、パスワード管理の完備 -- ✅ **デュアルモード処理**: 高速モード (テキストのみ) + 高精度モード (画像・テキスト混合) -- ✅ **メモリの最適化**: 大容量ファイルを分割処理し、メモリオーバーフローを防止 -- ✅ **統合管理**: モデル、ユーザー、一般設定を一つにまとめたモダンな UI -- ✅ **ミニマルなデザイン**: サイドバーとヘッダーの冗余を排除し、対話体験に集中 diff --git a/docs/1.0/DEPLOYMENT.md b/docs/1.0/DEPLOYMENT.md deleted file mode 100644 index 063c160..0000000 --- a/docs/1.0/DEPLOYMENT.md +++ /dev/null @@ -1,444 +0,0 @@ -# デプロイガイド - -## 開発環境のデプロイ - -### 前提条件 - -- Node.js 18+ -- Yarn -- Docker & Docker Compose - -### 1. プロジェクトのクローン - -```bash -git clone -cd simple-kb -``` - -### 2. 依存関係のインストール - -```bash -yarn install -``` - -### 3. 基本サービスの起動 - -```bash -# Elasticsearch と Tika を起動 -docker-compose up -d elasticsearch tika -``` - -### 4. 環境変数の設定 - -```bash -# 環境変数のテンプレートをコピー -cp server/.env.sample server/.env - -# 設定ファイルを編集 -vim server/.env -``` - -### 5. 開発サービスの起動 - -```bash -# フロントエンドとバックエンドを同時に起動 -yarn dev - -# または個別に起動 -yarn dev:web # フロントエンド (ポート 5173) -yarn dev:server # バックエンド (ポート 3000) -``` - -## 本番環境のデプロイ - -### Docker Compose を使用する場合 - -1. **環境変数の設定** - -```bash -cp .env.sample .env -# 本番環境の設定を編集 -``` - -1. **ビルドと起動** - -```bash -# すべてのサービスを一括起動 -docker-compose up -d -``` - -1. **サービスへのアクセス** - -- HTTPS: (推奨) -- HTTP: (HTTPS へ自動リダイレクト) -- バックエンド API: Nginx プロキシ経由でアクセス -- Elasticsearch: -- Tika: - -### サービス構成 - -- **nginx**: リバースプロキシ。HTTPS と CORS 処理を担当 -- **web**: フロントエンド静的ファイルサービス (React) -- **server**: バックエンド API サービス (NestJS) -- **libreoffice**: LibreOffice ドキュメント変換サービス (FastAPI, ポート 8100) -- **elasticsearch**: ベクトル検索エンジン (ポート 9200) -- **tika**: ドキュメント内容抽出サービス (ポート 9998) - -### アーキテクチャ図 - -``` -ユーザー → nginx → web (React) - ↓ - server (NestJS) → elasticsearch - ↓ ↓ - libreoffice tika - (FastAPI) (Java) -``` - -### SSL 証明書の設定 - -#### 自己署名証明書（開発環境用） - -```bash -# 自己署名証明書を生成 -./nginx/generate-ssl.sh -``` - -#### 本番環境用証明書 - -正式な SSL 証明書を以下の場所に配置してください： - -- 証明書ファイル: `nginx/ssl/cert.pem` -- 秘密鍵ファイル: `nginx/ssl/key.pem` - -### Docker 常用コマンド - -```bash -# すべてのサービスのログを表示 -docker-compose logs -f - -# 特定のサービスのログを表示 -docker-compose logs -f nginx -docker-compose logs -f server - -# サービスの再起動 -docker-compose restart - -# 特定のサービスの再起動 -docker-compose restart nginx - -# サービスの停止 -docker-compose down - -# 再ビルドして起動 -docker-compose up -d --build -``` - -### データの永続化 - -#### SQLite データベース - -- データベースファイルの場所: `./data/database.sqlite` -- コンテナ外部に自動マウントされるため、コンテナ再起動時もデータは失われません。 - -#### アップロードファイル - -- ファイルの保存場所: `./uploads/` -- アップロードされたすべてのドキュメントと画像はホストマシンに保存されます。 - -#### Elasticsearch データ - -- データボリューム: `elasticsearch-data` -- ベクトルインデックスデータが永続的に保存されます。 - -### 手動デプロイ - -1. **フロントエンドのビルド** - -```bash -cd web -yarn build -``` - -1. **バックエンドのビルド** - -```bash -cd server -yarn build -``` - -1. **Nginx の設定** - -```nginx -server { - listen 80; - server_name your-domain.com; - - # フロントエンド静的ファイル - location / { - root /path/to/web/dist; - try_files $uri $uri/ /index.html; - } - - # バックエンド API プロキシ - location /api { - proxy_pass http://localhost:3000; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - } -} -``` - -## 環境変数の設定 - -### バックエンド環境変数 (server/.env) - -```bash -# データベース -DATABASE_PATH=./data/metadata.db - -# Elasticsearch -ELASTICSEARCH_HOST=http://localhost:9200 -ELASTICSEARCH_INDEX=knowledge_base_chunks - -# Tika サービス -TIKA_HOST=http://localhost:9998 - -# LibreOffice サービス -LIBREOFFICE_URL=http://localhost:8100 - -# Vision API -VISION_API_KEY=sk-xxx-your-key -VISION_API_BASE=https://api.openai.com/v1 -VISION_MODEL=gpt-4-vision-preview - -# ファイルアップロード -UPLOAD_FILE_PATH=./uploads -MAX_FILE_SIZE=50MB - -# 一時ディレクトリ -TEMP_DIR=./temp - -# JWT -JWT_SECRET=your-jwt-secret-key -JWT_EXPIRES_IN=7d - -# サービスポート -PORT=3000 -``` - -### フロントエンド環境変数 (web/.env) - -```bash -# API アドレス -VITE_API_BASE_URL=http://localhost:3000 - -# アプリケーション設定 -VITE_APP_TITLE=簡易ナレッジベース -VITE_MAX_FILE_SIZE=50 -``` - -## バックアップと復元 - -### SQLite データベースのバックアップ - -```bash -# バックアップ -cp server/data/metadata.db backup/metadata_$(date +%Y%m%d).db - -# 復元 -cp backup/metadata_20240101.db server/data/metadata.db -``` - -### Elasticsearch データのバックアップ - -```bash -# スナップショット用リポジトリの作成 -curl -X PUT "localhost:9200/_snapshot/backup_repo" -H 'Content-Type: application/json' -d' -{ - "type": "fs", - "settings": { - "location": "/backup/elasticsearch" - } -}' - -# スナップショットの作成 -curl -X PUT "localhost:9200/_snapshot/backup_repo/snapshot_1" -``` - -## 監視とログ - -### アプリケーションログ - -- フロントエンドログ: ブラウザのコンソール -- バックエンドログ: `server/logs/` -- Elasticsearch ログ: Docker コンテナログ - -### ヘルスチェック - -```bash -# バックエンドのヘルスチェック -curl http://localhost:3000/health - -# Elasticsearch のヘルスチェック -curl http://localhost:9200/_cluster/health -``` - -## トラブルシューティング - -### よくある質問 - -1. **Elasticsearch への接続に失敗する** - - Docker コンテナの状態を確認してください。 - - ポート 9200 がアクセス可能か確認してください。 - - ファイアウォールの設定を確認してください。 - -2. **ファイルのアップロードに失敗する** - - uploads ディレクトリの権限を確認してください。 - - Tika サービスが正常に動作しているか確認してください。 - - ファイルサイズの制限を確認してください。 - -3. **モデル API の呼び出しに失敗する** - - API キーの設定を確認してください。 - - ネットワーク接続を確認してください。 - - モデル ID が正しいか確認してください。 - -#### 1. Elasticsearch への接続失敗 - -**症状**: バックエンドログに "Connection refused" または "ECONNREFUSED" と表示される -**解決策**: - -- Docker コンテナの状態確認: `docker-compose ps` -- ポート 9200 のアクセス確認: `curl http://localhost:9200` -- ファイアウォール設定の確認 -- Elasticsearch の再起動: `docker-compose restart elasticsearch` - -#### 2. ファイルのアップロード失敗 - -**症状**: アップロード時に「アップロード失敗」または「処理失敗」と表示される -**解決策**: - -- uploads ディレクトリの権限確認: `ls -la server/uploads/` -- Tika サービスの状態確認: `curl http://localhost:9998/version` -- ファイルサイズ制限の確認（デフォルト 50MB） -- バックエンドログの詳細エラーを確認 - -#### 3. モデル API の呼び出し失敗 - -**症状**: チャット時に「API キーが無効」または「モデルの呼び出しに失敗」と表示される -**解決策**: - -- API キーの設定が正しいか確認 -- ネットワーク接続とファイアウォールの確認 -- モデル ID の確認（例: gpt-4, gpt-3.5-turbo） -- API の利用残高と権限の確認 -- Base URL の設定確認（OpenAI 互換インターフェースの場合） - -#### 4. ユーザー認証の問題 - -**症状**: ログイン失敗またはトークンの期限切れ -**解決策**: - -- ユーザー名とパスワードの確認 -- ブラウザのキャッシュと localStorage のクリア -- JWT_SECRET の設定確認 -- ユーザーアカウントの再登録 - -#### 5. ナレッジベースの検索結果が出ない - -**症状**: 質問後に「関連する知識が見つかりません」と表示される -**解決策**: - -- ファイルのインデックスが完了しているか確認（ステータスが「完了」） -- 類似度しきい値の設定を調整 -- Embedding モデルの設定確認 -- 別のキーワードで質問してみる - -#### 6. フロントエンドページにアクセスできない - -**症状**: ブラウザに「このサイトにアクセスできません」と表示される -**解決策**: - -- フロントエンドサービスがポート 5173 で動作しているか確認 -- ファイアウォールとプロキシの設定確認 -- ブラウザのキャッシュのクリア -- シークレットモードでのアクセスを試す - -### デバッグツール - -#### サービス状態の確認 - -```bash -# すべての Docker コンテナを確認 -docker-compose ps - -# ポートの使用状況を確認 -netstat -tulpn | grep :5173 -netstat -tulpn | grep :3000 -``` - -#### 詳細ログの表示 - -```bash -# バックエンドログ -docker-compose logs -f server - -# Elasticsearch ログ -docker-compose logs -f elasticsearch - -# フロントエンド開発ログ -cd web && yarn dev -``` - -#### ヘルスチェック - -```bash -# バックエンド API のヘルスチェック -curl http://localhost:3000/health - -# Elasticsearch のヘルスチェック -curl http://localhost:9200/_cluster/health - -# LibreOffice サービスのチェック -curl http://localhost:8100/health - -# LibreOffice API ドキュメントの表示 -open http://localhost:8100/docs -``` - -### パフォーマンスの最適化 - -#### 1. Elasticsearch のチューニング - -```bash -# JVM ヒープメモリの増量 -export ES_JAVA_OPTS="-Xms2g -Xmx2g" - -# インデックス状態の確認 -curl http://localhost:9200/_cat/indices?v -``` - -#### 2. ファイル処理の最適化 - -- 同時にアップロードするファイル数を制限する -- チャンクサイズを適切に調整する（推奨 512-1024 トークン） -- 不要なインデックスデータを定期的に整理する - -### データの復元 - -#### SQLite データベースの復元 - -```bash -# バックアップから復元 -cp backup/metadata_20240101.db server/data/metadata.db - -# データベースの整合性チェック -sqlite3 server/data/metadata.db "PRAGMA integrity_check;" -``` - -#### Elasticsearch データの復元 - -```bash -# スナップショットの復元 -curl -X POST "localhost:9200/_snapshot/backup_repo/snapshot_1/_restore" -``` diff --git a/docs/1.0/DESIGN.md b/docs/1.0/DESIGN.md deleted file mode 100644 index e78bdd1..0000000 --- a/docs/1.0/DESIGN.md +++ /dev/null @@ -1,217 +0,0 @@ -# 簡易ナレッジベース (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 回答の完全な国際化サポート -- ✅ **ビジョン機能**: 画像処理に対応したマルチモーダルモデルのサポート -- ✅ **デュアルモード処理**: 高速モード (テキストのみ) + 高精度モード (画像・テキスト混合) diff --git a/docs/1.0/DEVELOPMENT_STANDARDS.md b/docs/1.0/DEVELOPMENT_STANDARDS.md deleted file mode 100644 index abe552b..0000000 --- a/docs/1.0/DEVELOPMENT_STANDARDS.md +++ /dev/null @@ -1,71 +0,0 @@ -# 開発基準 - -## コードコメントの基準 - -### 1. コメントの言語 - -- **すべてのコードコメントは中国語を使用する必要があります** -- 以下を含みますが、これらに限定されません： - - 関数/メソッドのコメント - - 行内コメント - - コードブロックの説明 - - TODO/FIXME コメント - -### 2. ログ出力の基準 - -- **すべてのログ出力は中国語を使用する必要があります** -- 以下を含みますが、これらに限定されません： - - `logger.log()` 情報ログ - - `logger.warn()` 警告ログ - - `logger.error()` ラーログ - - `console.log()` デバッグ出力 - -### 3. エラーメッセージの基準 - -- **ユーザーに表示されるエラーメッセージは中国語を使用します** -- **開発デバッグ用のエラーメッセージは中国語を使用します** -- 例外スロー時のエラーメッセージには中国語を使用します - -## 例 - -### 正しいコメントとログ - -```typescript -// 正解：中国語のコメント -async getEmbeddings(texts: string[]): Promise { - this.logger.log(`正在为 ${texts.length} 个文本生成嵌入向量`); // 正解：中国語のログ - - try { - // APIを呼び出して埋め込みベクトルを取得 - const response = await this.callEmbeddingAPI(texts); - return response.data; - } catch (error) { - this.logger.error('获取嵌入向量失败', error); // 正解：中国語のログ - throw new Error('嵌入向量生成失败'); // 正解：中国語のエラーメッセージ - } -} -``` - -### 誤ったコメントとログ - -```typescript -// 誤り：英語のコメントとログ -async getEmbeddings(texts: string[]): Promise { - this.logger.log(`Getting embeddings for ${texts.length} texts`); - - try { - // Call API to get embeddings - const response = await this.callEmbeddingAPI(texts); - return response.data; - } catch (error) { - this.logger.error('Failed to get embeddings', error); - throw new Error('Embedding generation failed'); - } -} -``` - -## 履行基準 - -1. **コードレビュー時には、必ずコメントとログの言語をチェックしてください** -2. **新規コードは、中国語のコメントとログの基準に従う必要があります** -3. **既存のコードをリファクタリングする際は、同時にコメントとログも中国語に更新してください** diff --git a/docs/1.0/EMBEDDING_MODEL_ID_FIX.md b/docs/1.0/EMBEDDING_MODEL_ID_FIX.md deleted file mode 100644 index 6cb850b..0000000 --- a/docs/1.0/EMBEDDING_MODEL_ID_FIX.md +++ /dev/null @@ -1,219 +0,0 @@ -# Embedding モデル ID 連携の修正 - -## 🐛 問題の記述 - -``` -混合検索失敗: NotFoundException: ModelConfig with ID "embedding-3" not found or not owned by user. -``` - -## 🔍 問題の分析 - -### 混同されやすい概念 - -システム内には2種類の異なる「ID」が存在します： - -1. **モデル設定テーブルの ID** (`ModelConfig.id`) - - データベースの主キー - - 例：`"embedding-3"`, `"default-embedding"` - - 用途：`ModelConfigService.findOne(id, userId)` - -2. **モデル識別子** (`ModelConfig.modelId`) - - AI ベンダー側でのモデル名 - - 例：`"text-embedding-3-large"`, `"text-embedding-ada-002"` - - 用途：AI API 呼び出し時のパラメータ - -### データフロー - -``` -ユーザー設定: user_setting.selectedEmbeddingId = "embedding-3" ✅ テーブルID - -フロントエンド: settings.selectedEmbeddingId - ↓ 転送 -バックエンド Controller: selectedEmbeddingId = "embedding-3" - ↓ 転送 -ChatService: embeddingModel.id = "embedding-3" ✅ 正常 - ↓ 転送 -hybridSearch: embeddingModelId = "embedding-3" - ↓ 転送 -EmbeddingService.getEmbeddings(embeddingModelId) - ↓ 呼び出し -ModelConfigService.findOne("embedding-3", userId) ✅ 正常 -``` - -### 以前の誤り - -**ChatService.ts (誤り):** - -```typescript -// 182行目付近 -searchResults = await this.hybridSearch( - [message], - userId, - embeddingModel.modelId, // ❌ 誤り！ "text-embedding-3-large" を渡してしまっていた -); -``` - -**hybridSearch (受信側):** - -```typescript -private async hybridSearch( - keywords: string[], - userId: string, - embeddingModelId?: string, // "text-embedding-3-large" を受け取ってしまう -) -``` - -**EmbeddingService (期待値):** - -```typescript -async getEmbeddings( - texts: string[], - userId: string, - embeddingModelConfigId: string, // 本来は "embedding-3" を期待 -) { - const modelConfig = await this.modelConfigService.findOne( - embeddingModelConfigId, // ❌ "text-embedding-3-large" で検索しても見つからない！ - userId, - ); -} -``` - -## ✅ 修正内容 - -### 修正箇所 - -**server/src/chat/chat.service.ts:** - -```typescript -// 182行目付近 -searchResults = await this.hybridSearch( - [message], - userId, - embeddingModel.id, // ✅ テーブルID "embedding-3" を使用するように変更 -); -``` - -### 修正後のフロー - -``` -1. ユーザーが埋め込みモデルを選択: text-embedding-3-large - ↓ -2. システムが user_setting テーブルに保存: - selectedEmbeddingId = "embedding-3" (ModelConfig テーブルの主キー) - ↓ -3. フロントエンドがチャットリクエストを送信: - { selectedEmbeddingId: "embedding-3" } - ↓ -4. バックエンド Controller が受信: - selectedEmbeddingId = "embedding-3" - ↓ -5. ChatService がモデルを検索: - embeddingModel = models.find(m => m.id === "embedding-3") - // 結果: { id: "embedding-3", modelId: "text-embedding-3-large", ... } - ↓ -6. ChatService が hybridSearch を呼び出し: - hybridSearch(..., embeddingModel.id) // "embedding-3" を渡す - ↓ -7. hybridSearch が EmbeddingService を呼び出し: - getEmbeddings(..., "embedding-3") - ↓ -8. EmbeddingService が設定を検索: - findOne("embedding-3", userId) // ✅ 設定が見つかる - ↓ -9. AI API を呼び出し: - model: "text-embedding-3-large" // modelId を用いて API を実行 -``` - -## 📊 ID の対応関係 - -| シーン | 使用するフィールド | 例 | 用途 | -|------|-----------|--------|------| -| ユーザー設定 | `user_setting.selectedEmbeddingId` | `"embedding-3"` | ユーザーの選択を保存 | -| 設定の検索 | `ModelConfig.id` | `"embedding-3"` | データベースクエリ | -| API 呼び出し | `ModelConfig.modelId` | `"text-embedding-3-large"` | AI ベンダーのインターフェース | - -## 🔑 重要な原則 - -### 1. データベース操作にはテーブル ID を使用する - -```typescript -// ✅ 正解 -const model = await modelConfigService.findOne(modelId, userId); // modelId = "embedding-3" - -// ❌ 誤り -const model = await modelConfigService.findOne(modelId, userId); // modelId = "text-embedding-3-large" -``` - -### 2. API 呼び出しにはモデル識別子を使用する - -```typescript -// ✅ 正解 -fetch(apiUrl, { - body: JSON.stringify({ - model: modelConfig.modelId, // "text-embedding-3-large" - }), -}); -``` - -### 3. 内部的な受け渡しにはテーブル ID を使用する - -```typescript -// ✅ 正解 -embeddingService.getEmbeddings(texts, userId, modelConfig.id); // "embedding-3" - -// ❌ 誤り -embeddingService.getEmbeddings(texts, userId, modelConfig.modelId); // "text-embedding-3-large" -``` - -## 🧪 検証 - -### テスト手順 - -1. **ユーザー設定の確認** - - ```sql - SELECT selectedEmbeddingId FROM user_setting WHERE userId = 'xxx'; - -- 期待値: "embedding-3" (テーブルID) - ``` - -2. **モデル設定の確認** - - ```sql - SELECT id, modelId, name FROM model_config WHERE userId = 'xxx'; - -- 期待値: embedding-3 | text-embedding-3-large | Text Embedding 3 Large - ``` - -3. **チャットメッセージの送信** - - バックエンドログを確認 - - 期待される出力: "使用嵌入模型: Text Embedding 3 Large text-embedding-3-large ID: embedding-3" - -4. **埋め込みベクトルの生成確認** - - ログに "从 Text Embedding 3 Large 获取到 X 个嵌入向量" と表示されること - -### 期待されるログ出力 - -``` -=== ChatService.streamChat === -User ID: user-123 -Selected Embedding ID: embedding-3 -ID に基づいてモデルを検索: embedding-3 -使用するモデル: Text Embedding 3 Large text-embedding-3-large ID: embedding-3 -埋め込みベクトルを生成中... -Text Embedding 3 Large から 1 個の埋め込みベクトルを取得しました。次元数: 2560 -``` - -## 📁 修正されたファイル - -- `server/src/chat/chat.service.ts` - 182行目。 `embeddingModel.modelId` ではなく `embeddingModel.id` を渡すように変更。 - -## 💡 学んだ教訓 - -1. **2種類の ID を区別すること**：テーブル主キー vs モデル識別子 -2. **パラメータ名を明確にすること**：`embeddingModelConfigId` vs `embeddingModelId` -3. **呼び出し先の期待値を確認すること**：`EmbeddingService` がどのタイプの ID を求めているか -4. **ログ出力の工夫**：デバッグを容易にするため、両方の ID を出力する - -```typescript -console.log('使用するモデル:', embeddingModel.name, embeddingModel.modelId, 'ID:', embeddingModel.id); -// 出力: 使用するモデル: Text Embedding 3 Large text-embedding-3-large ID: embedding-3 -``` diff --git a/docs/1.0/FEATURE_SUMMARY.md b/docs/1.0/FEATURE_SUMMARY.md deleted file mode 100644 index 8428aa5..0000000 --- a/docs/1.0/FEATURE_SUMMARY.md +++ /dev/null @@ -1,29 +0,0 @@ -# 功能说明 - -## 用户信息显示功能已完成 - -此更新为系统添加了以下功能： - -1. 在侧边栏顶部显示当前登录用户的信息，包括： - - 用户头像和用户名 - - 管理员标识（如果用户是管理员） - - 用户ID的部分显示 - -2. 主要文件变更： - - 创建了 `UserInfoDisplay.tsx` 组件 - - 更新了 `SidebarRail.tsx` 以集成用户信息显示 - - 更新了 `App.tsx` 以传递 currentUser 数据 - - 所有现有翻译已支持相关文本 - -## 实现细节 - -- 用户信息只在侧边栏展开时显示 -- 使用 Lucide React 图标增强可视化 -- 支持三种语言的界面文本 (中文/英文/日文) -- 管理员用户会显示特殊标记 -- 界面美观且与现有设计风格保持一致 -- 避免了信息重复显示 - -## 部署 - -此功能已准备好部署，无需额外配置。 \ No newline at end of file diff --git a/docs/1.0/INTERNAL_DEPLOYMENT_GUIDE.md b/docs/1.0/INTERNAL_DEPLOYMENT_GUIDE.md deleted file mode 100644 index debd684..0000000 --- a/docs/1.0/INTERNAL_DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,94 +0,0 @@ -# 内网部署指南 - Simple-KB 知识库系统 - -## 概述 - -本文档介绍如何在内部网络环境中部署Simple-KB知识库系统，确保所有外部依赖都被移除或替换为内部资源。 - -## 主要修改内容 - -### 1. 外部CDN资源移除 - -已完成修改： -- 将 KaTeX CSS 文件从外部 CDN (https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css) 移至本地 -- `web/index.html` 已更新为引用本地 `/katex/katex.min.css` -- KaTeX CSS 文件已复制到 `web/public/katex/katex.min.css` - -### 2. AI模型API配置 - -系统本身支持内部模型API配置： -- 模型配置通过 `ModelConfig` 实体管理 -- 支持自定义 `baseUrl` 来指定内部模型服务 -- 用户可通过UI界面配置内部模型端点 - -## 内网部署配置步骤 - -### 步骤1: 部署内部AI模型服务 - -在启动Simple-KB之前，请确保已部署内部AI模型服务，如： -- 自托管的OpenAI兼容接口 (如 vLLM, Text Generation WebUI等) -- 内部大语言模型服务 -- 内部嵌入模型服务 - -### 步骤2: 配置模型端点 - -1. 启动Simple-KB系统 -2. 登录系统后，在模型配置页面添加内部模型配置： - - LLM模型: 配置内部LLM服务的URL和API密钥 - - 嵌入模型: 配置内部嵌入服务的URL和API密钥 - - 重排序模型: 配置内部重排序服务的URL和API密钥 - -### 步骤3: Docker配置（可选高级配置） - -如果需要修改Docker构建过程以使用内部注册表，请修改以下文件： - -#### 修改 server/Dockerfile: -```dockerfile -# 替换这行： -RUN yarn config set registry https://registry.npmmirror.com && \ -# 为： -RUN yarn config set registry http://your-internal-npm-registry && \ -``` - -#### 修改 web/Dockerfile: -```dockerfile -# 替换这行： -RUN yarn config set registry https://registry.npmmirror.com && \ -# 为： -RUN yarn config set registry http://your-internal-npm-registry && \ -``` - -#### 修改 libreoffice-server/Dockerfile: -```dockerfile -# 替换APK仓库源 -RUN echo "http://your-internal-mirror/alpine/v3.19/main" > /etc/apk/repositories && \ - echo "http://your-internal-mirror/alpine/v3.19/community" >> /etc/apk/repositories && \ - -# 替换pip源 -RUN pip install --no-cache-dir -r requirements.txt -i http://your-internal-pypi/ - -# 替换npm源 -RUN npm install --registry=http://your-internal-npm-registry -``` - -### 步骤4: Nginx配置 - -如果需要修改Nginx配置以适应内部环境： - -1. 更新 `nginx/conf.d/kb.conf` 中的SSL证书路径 -2. 根据需要修改服务器名称 -3. 确保代理路径正确指向内部服务 - -## 验证步骤 - -1. 确认前端界面正常加载且无外部资源错误 -2. 测试数学公式渲染功能是否正常（KaTeX功能） -3. 配置内部模型服务并测试问答功能 -4. 确认所有API调用都在内部网络中完成 - -## 注意事项 - -- 系统的所有核心功能现均可在内部网络中运行 -- 外部CDN依赖已被完全移除 -- AI模型服务需单独部署内部实例 -- 在完全离线环境中，构建过程可能需要预先下载所有依赖包 -- 如需完全离线部署，建议预构建镜像并部署到内部镜像仓库 \ No newline at end of file diff --git a/docs/1.0/INTERNAL_DEPLOYMENT_SUMMARY.md b/docs/1.0/INTERNAL_DEPLOYMENT_SUMMARY.md deleted file mode 100644 index 9e3bba8..0000000 --- a/docs/1.0/INTERNAL_DEPLOYMENT_SUMMARY.md +++ /dev/null @@ -1,40 +0,0 @@ -# 内网部署修改摘要 - Simple-KB 知识库系统 - -## 修改概述 - -已完成对Simple-KB知识库系统的修改，以支持内部网络环境部署，消除了外部依赖。 - -## 具体修改内容 - -### 1. 外部CDN资源移除 -- **文件**: `web/index.html` -- **修改**: 将 KaTeX CSS 从外部 CDN (https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css) 更改为本地资源 (/katex/katex.min.css) -- **文件**: `web/public/katex/katex.min.css` -- **操作**: 从 node_modules 复制 KaTeX CSS 文件到本地目录 - -### 2. 文档更新 -- **新增文件**: `INTERNAL_DEPLOYMENT_GUIDE.md` -- **内容**: 详细的内网部署指南，包括配置内部AI模型服务的方法 -- **更新文件**: `README.md` -- **内容**: 添加了内网部署章节，链接到部署指南 - -## 系统状态 - -✅ **已完成**: -- 消除前端外部CDN依赖 -- 提供内部网络部署文档 -- 保持所有原有功能完整性 - -✅ **系统已准备好在内部网络环境中部署**: -- 所有前端资源均为本地资源 -- AI模型服务可通过配置指向内部服务 -- 系统不再依赖外部CDN或API端点(除用户自行配置的AI模型外) - -## 部署说明 - -要在内部网络中部署此系统： - -1. 按照 `INTERNAL_DEPLOYMENT_GUIDE.md` 的说明进行配置 -2. 部署内部AI模型服务（如适用） -3. 配置模型端点以使用内部服务 -4. 启动系统并验证功能 \ No newline at end of file diff --git a/docs/1.0/KNOWLEDGE_BASE_ENHANCEMENTS.md b/docs/1.0/KNOWLEDGE_BASE_ENHANCEMENTS.md deleted file mode 100644 index 9634afd..0000000 --- a/docs/1.0/KNOWLEDGE_BASE_ENHANCEMENTS.md +++ /dev/null @@ -1,464 +0,0 @@ -# ナレッジベースの強化機能設計 - -## 🎯 機能概要 - -今回の開発には、以下の3つのコア機能が含まれます： - -1. **ナレッジベースのグループ化** - グループを作成し、ドキュメントを複数のグループに所属させ、検索時にグループを指定可能にします。 -2. **検索履歴** - 対話プロセス全体を保存し、過去の会話の閲覧や再開を可能にします。 -3. **PDF プレビュー** - すべてのファイルを PDF 形式に変換し、オンラインでプレビューできるようにします。 - -## 🗄️ データベース設計 - -### 新規テーブル構造 - -```sql --- ナレッジベースグループ管理テーブル -CREATE TABLE knowledge_groups ( - id TEXT PRIMARY KEY, - name TEXT NOT NULL, - description TEXT, - color TEXT DEFAULT '#3B82F6', -- グループの色分けID - user_id TEXT NOT NULL, - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - updated_at DATETIME DEFAULT CURRENT_TIMESTAMP -); - --- ドキュメント・グループ関連付けテーブル (多対多) -CREATE TABLE knowledge_base_groups ( - knowledge_base_id TEXT NOT NULL, - group_id TEXT NOT NULL, - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - PRIMARY KEY (knowledge_base_id, group_id), - FOREIGN KEY (knowledge_base_id) REFERENCES knowledge_base(id) ON DELETE CASCADE, - FOREIGN KEY (group_id) REFERENCES knowledge_groups(id) ON DELETE CASCADE -); - --- 検索履歴テーブル -CREATE TABLE search_history ( - id TEXT PRIMARY KEY, - user_id TEXT NOT NULL, - title TEXT NOT NULL, -- 対話タイトル (質問の先頭50文字) - selected_groups TEXT, -- JSON配列: ["group1", "group2"] または null(すべて) - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - updated_at DATETIME DEFAULT CURRENT_TIMESTAMP -); - --- 対話メッセージテーブル -CREATE TABLE chat_messages ( - id TEXT PRIMARY KEY, - search_history_id TEXT NOT NULL, - role TEXT NOT NULL CHECK (role IN ('user', 'assistant')), - content TEXT NOT NULL, - sources TEXT, -- JSON配列: 引用ソース情報 - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - FOREIGN KEY (search_history_id) REFERENCES search_history(id) ON DELETE CASCADE -); -``` - -### 既存テーブルの修正 - -```sql --- knowledge_base テーブルに PDF パスフィールドを追加 -ALTER TABLE knowledge_base ADD COLUMN pdf_path TEXT; -``` - -## 🔌 API エンドポイント設計 - -### ナレッジベースグループ API - -```typescript -// ユーザーの全グループを取得 -GET /api/knowledge-groups -Response: { - groups: Array<{ - id: string; - name: string; - description?: string; - color: string; - fileCount: number; // 含まれるファイル数 - createdAt: string; - }> -} - -// グループの作成 -POST /api/knowledge-groups -Body: { name: string; description?: string; color?: string } -Response: { id: string; name: string; description?: string; color: string } - -// グループの更新 -PUT /api/knowledge-groups/:id -Body: { name?: string; description?: string; color?: string } - -// グループの削除 -DELETE /api/knowledge-groups/:id - -// グループ内のファイルを取得 -GET /api/knowledge-groups/:id/files -Response: { files: KnowledgeBase[] } - -// ファイルをグループに追加 -POST /api/knowledge-bases/:fileId/groups -Body: { groupIds: string[] } - -// グループからファイルを削除 -DELETE /api/knowledge-bases/:fileId/groups/:groupId -``` - -### 検索履歴 API - -```typescript -// 検索履歴の取得 (ページネーション) -GET /api/search-history?page=1&limit=20 -Response: { - histories: Array<{ - id: string; - title: string; - selectedGroups: string[] | null; - messageCount: number; - lastMessageAt: string; - createdAt: string; - }>; - total: number; - page: number; - limit: number; -} - -// 対話詳細の取得 -GET /api/search-history/:id -Response: { - id: string; - title: string; - selectedGroups: string[] | null; - messages: Array<{ - id: string; - role: 'user' | 'assistant'; - content: string; - sources?: Array<{ - fileName: string; - content: string; - score: number; - chunkIndex: number; - }>; - createdAt: string; - }>; -} - -// 新しい対話の作成 -POST /api/search-history -Body: { - title: string; - selectedGroups?: string[]; - firstMessage: string; -} -Response: { id: string } - -// 対話の削除 -DELETE /api/search-history/:id - -// 対話の継続 (既存のチャットインターフェースを拡張し、historyId パラメータを追加) -POST /api/chat/stream -Body: { - message: string; - history: ChatMessage[]; - userLanguage?: string; - selectedGroups?: string[]; // 新規：選択されたグループ - historyId?: string; // 新規：対話履歴ID -} -``` - -### PDF プレビュー API - -```typescript -// ファイルの PDF プレビューを取得 -GET /api/knowledge-bases/:id/pdf -Response: PDF ファイルストリーム、または PDF URL へのリダイレクト - -// PDF ステータスの確認 -GET /api/knowledge-bases/:id/pdf-status -Response: { - status: 'pending' | 'converting' | 'ready' | 'failed'; - pdfPath?: string; - error?: string; -} -``` - -## 🎨 フロントエンドコンポーネント設計 - -### 1. ナレッジベースグループコンポーネント - -```typescript -// グループマネージャー -interface GroupManagerProps { - groups: KnowledgeGroup[]; - onCreateGroup: (group: CreateGroupData) => void; - onUpdateGroup: (id: string, data: UpdateGroupData) => void; - onDeleteGroup: (id: string) => void; -} - -// グループセレクター (検索時の選択用) -interface GroupSelectorProps { - groups: KnowledgeGroup[]; - selectedGroups: string[]; - onSelectionChange: (groupIds: string[]) => void; - showSelectAll?: boolean; -} - -// ファイルグループタグ -interface FileGroupTagsProps { - fileId: string; - groups: KnowledgeGroup[]; - assignedGroups: string[]; - onGroupsChange: (groupIds: string[]) => void; -} -``` - -### 2. 検索履歴コンポーネント - -```typescript -// 履歴リスト -interface SearchHistoryListProps { - histories: SearchHistoryItem[]; - onSelectHistory: (historyId: string) => void; - onDeleteHistory: (historyId: string) => void; - onLoadMore: () => void; - hasMore: boolean; -} - -// 履歴対話ビューアー -interface HistoryViewerProps { - historyId: string; - onContinueChat: (historyId: string) => void; - onClose: () => void; -} -``` - -### 3. PDF プレビューコンポーネント - -```typescript -// PDF プレビューアー -interface PDFPreviewProps { - fileId: string; - fileName: string; - onClose: () => void; -} - -// PDF プレビューボタン -interface PDFPreviewButtonProps { - fileId: string; - fileName: string; - status: 'pending' | 'converting' | 'ready' | 'failed'; -} -``` - -## 🔄 ビジネスフロー設計 - -### ナレッジベースグループ化フロー - -``` -1. ユーザーがグループを作成 → knowledge_groups テーブルに保存 -2. ファイルアップロード時 → グループを選択可能 → knowledge_base_groups テーブルに関連付けを保存 -3. 検索時 → グループを選択 → Elasticsearch のクエリ範囲をフィルタリング -4. ファイル管理 → ファイルの所属グループを編集可能 -``` - -### 検索履歴フロー - -``` -1. ユーザーがチャットを開始 → search_history データを生成 -2. 各メッセージ → chat_messages テーブルに保存 -3. 履歴の確認 → 履歴リストをページネーションでロード -4. 履歴をクリック → 対話内容全体をロード -5. 対話の継続 → 既存の履歴をベースに新しいメッセージを追加 -``` - -### PDF プレビューフロー - -``` -1. ファイルアップロード → PDF かどうかを確認 -2. PDF 以外の場合 → LibreOffice を呼び出して PDF に変換 -3. PDF パスを knowledge_base.pdf_path に保存 -4. フロントエンドからプレビューをリクエスト → PDF ファイルストリームを返却 -5. HTML の または