hangshuo652/aurak
1
0
Fork 1
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: 清理 docs 目录冗余文档（55个→9个）

Browse Source 
删除:
- 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 <noreply@anthropic.com>
This commit is contained in:
Developer
2026-06-16 14:31:44 +08:00
parent 3d73618270
commit b21899055d
51 changed files with 0 additions and 12885 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/1.0/MEMORY_OPTIMIZATION_FIX.md
-348
View File
@@ -1,348 +0,0 @@
# 大容量ファイルアップロード時のメモリオーバーフロー修正のまとめ
## 問題の分析
### 根本的な原因
旧アーキテクチャには、大容量ファイルを処理する際のメモリボトルネックが複数存在していました：
1. **TikaService** - `fs.readFileSync()` により、ファイル全体を一度にメモリへ読み込んでいました。
2. **TextChunkerService** - `chunkText()` が、生成されたすべてのチャンクを保持する配列を返していました。
3. **KnowledgeBaseService** - すべてのチャンクのベクトルを一度に生成し、メモリ上に保持していました。
4. **EmbeddingService** - すべてのチャンクの埋め込みベクトルを一括でリクエストしていました。
### メモリ使用量の推定（500MB ドキュメントの例）
| フェーズ | メモリ使用量 | 説明 |
|------|----------|------|
| Tika 抽出 | 約 1GB | 元ファイル + テキストデータ |
| チャンク分割 | 約 500MB | 50万個のチャンクオブジェクト |
| 一括ベクトル化 | 約 5.5GB | 50万個 × 2560次元 × 4バイト |
| **合計ピーク時** | **約 7GB以上** | 制限を大幅に超過 |
---
## クイック修正案（実施済み）
### 1. フロントエンドの最適化
#### デフォルト設定の変更
**ファイル**: `web/components/IndexingModal.tsx`
```typescript
// 変更前
const [chunkSize, setChunkSize] = useState(500);
const [chunkOverlap, setChunkOverlap] = useState(50);
// 変更後
const [chunkSize, setChunkSize] = useState(200); // 50% 削減
const [chunkOverlap, setChunkOverlap] = useState(40); // 20% 削減
```
**効果**: チャンク数を約 60% 削減し、メモリ負荷を軽減。
#### ファイルサイズ制限の追加
**ファイル**: `web/App.tsx`
```typescript
const MAX_FILE_SIZE = 104857600; // 100MB
const MAX_SIZE_MB = 100;
// 検証ロジック
if (file.size > MAX_FILE_SIZE) {
errors.push(`${file.name} - ${MAX_SIZE_MB}MB の制限を超えています`);
continue;
}
```
**効果**: 超大容量ファイルのアップロードをブロックし、フロントエンドで即座にフィードバック。
---
### 2. バックエンドの最適化
#### ファイルアップロード制限
**ファイル**: `server/src/upload/upload.module.ts`
```typescript
MulterModule.registerAsync({
useFactory: (configService: ConfigService) => {
const maxFileSize = parseInt(
configService.get<string>('MAX_FILE_SIZE', '104857600')
);
return {
storage: multer.diskStorage({...}),
limits: {
fileSize: maxFileSize, // 100MB 制限
},
};
},
});
```
#### アップロードコントローラーの強化
**ファイル**: `server/src/upload/upload.controller.ts`
```typescript
// 1. ファイル形式のフィルタリング
const allowedMimeTypes = [
'application/pdf',
'application/msword',
'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
'text/plain',
'image/jpeg', 'image/png', 'image/gif', 'image/webp'
];
// 2. ファイルサイズの検証
if (file.size > maxFileSize) {
throw new BadRequestException(
`ファイルサイズが制限を超えています: ${this.formatBytes(file.size)}、最大許可: ${this.formatBytes(maxFileSize)}`
);
}
// 3. 設定パラメータの安全な制限
const indexingConfig = {
chunkSize: Math.max(100, Math.min(2000, config.chunkSize || 200)),
chunkOverlap: Math.max(0, Math.min(500, config.chunkOverlap || 40)),
// オーバーラップがチャンクサイズの 50% を超えないように調整
chunkOverlap: Math.min(chunkOverlap, chunkSize * 0.5)
};
```
---
### 3. コアメモリ管理
#### メモリ監視サービス（新規作成）
**ファイル**: `server/src/knowledge-base/memory-monitor.service.ts`
```typescript
@Injectable()
export class MemoryMonitorService {
private readonly MAX_MEMORY_MB = 1024; // 1GB 上限
private readonly BATCH_SIZE = 100; // 1バッチ 100 チャンク
private readonly GC_THRESHOLD_MB = 800; // GC トリガーしきい値
// メモリ使用状況の取得
getMemoryUsage(): MemoryStats { ... }
// メモリが空くまで待機（タイムアウトあり）
async waitForMemoryAvailable(): Promise<void> { ... }
// バッチサイズを動的に調整
getDynamicBatchSize(currentMemoryMB: number): number { ... }
// 大量データのバッチ処理
async processInBatches<T, R>(items: T[], processor): Promise<R[]> { ... }
// メモリ使用量の推定
estimateMemoryUsage(itemCount, itemSizeBytes, vectorDim): number { ... }
}
```
#### 刷新された KnowledgeBaseService
**ファイル**: `server/src/knowledge-base/knowledge-base.service.ts`
```typescript
private async vectorizeToElasticsearch(kbId, userId, text, config) {
// 1. テキストのチャンク分割
const chunks = this.textChunkerService.chunkText(text, chunkSize, chunkOverlap);
// 2. メモリ使用量を推定し、バッチ処理が必要か判断
const useBatching = this.memoryMonitor.shouldUseBatching(
chunks.length,
avgChunkSize,
defaultDimensions
);
if (useBatching) {
// 3. バッチ処理を実行
await this.processInBatches(chunks, async (batch, batchIndex) => {
// 3.1 バッチ単位でベクトルを生成
const embeddings = await this.embeddingService.getEmbeddings(
batch.map(c => c.content),
userId,
kb.embeddingModelId
);
// 3.2 即座に Elasticsearch へインデックス
for (let i = 0; i < batch.length; i++) {
await this.elasticsearchService.indexDocument(...);
}
// 3.3 参照のクリア
batch.length = 0;
});
} else {
// 小規模ファイルの一括処理
}
}
```
---
## 設定パラメータ
### 環境変数 (server/.env)
```env
# ファイルアップロード設定
UPLOAD_FILE_PATH=./uploads
MAX_FILE_SIZE=104857600 # 100MB
# ベクトル次元
DEFAULT_VECTOR_DIMENSIONS=2560
# メモリ管理設定
MAX_MEMORY_USAGE_MB=1024 # メモリ上限 (MB)
CHUNK_BATCH_SIZE=100 # バッチサイズ (チャンク数)
GC_THRESHOLD_MB=800 # GC トリガーしきい値 (MB)
```
---
## 改善の効果
### 最適化前（500MB ドキュメント）
- **チャンクサイズ**: 500 tokens
- **チャンク数**: 約 500,000
- **メモリピーク**: 約 7GB以上
- **結果**: メモリ溢れによるプロセス停止
### 最適化後（500MB ドキュメント）
- **チャンクサイズ**: 200 tokens (デフォルト)
- **チャンク数**: 約 1,000,000 (バッチ処理により制御)
- **メモリピーク**: 1GB未満 (MAX_MEMORY_USAGE_MB で制限)
- **結果**: 正常に処理完了、メモリ消費が安定
---
## 処理フローの比較
### 旧フロー
```
ファイル → Tika 抽出(全量) → 切片(全量) → 向量(全量) → 索引(全量)
↑ ↑ ↑ ↑
ピーク: 7GB+ ピーク: 7GB+ ピーク: 7GB+ ピーク: 7GB+
```
### 新フロー
```
ファイル → Tika 抽出 → チャンク分割 → メモリ評価 → バッチ処理
↓
┌────────┴────────┐
│ バッチ1 (100チャンク) │ → ベクトル化 → インデックス → クリア
│ バッチ2 (100チャンク) │ → ベクトル化 → インデックス → クリア
│ ... │
└─────────────────┘
ピーク: <1GB ピーク: <1GB ピーク: <1GB
```
---
## 監視とログ
### メモリ監視ログの例
```
[KnowledgeBaseService] メモリ状態 - 処理前: 256/1024MB
[KnowledgeBaseService] 推定メモリ使用量: 1200MB
[KnowledgeBaseService] 推定メモリ 1200MB がしきい値 716MB を超えたため、バッチ処理を使用します
[MemoryMonitorService] バッチ処理開始: 500,000 項目
[MemoryMonitorService] 処理中 1/5000 バッチ: 100 項目
[KnowledgeBaseService] バッチ 1/5000 完了, 現在のメモリ: 280MB
[MemoryMonitorService] メモリ消費が高いため、解放待ち... 950/1024MB
[MemoryMonitorService] 強制ガベージコレクションを実行中...
[MemoryMonitorService] GC 完了: 950MB → 320MB (630MB 解放)
...
[KnowledgeBaseService] バッチ処理完了: 500,000 項目, 所要時間 125.3s, 最終メモリ 350MB
```
---
## 今後の最適化の方向性
### フェーズ2：ストリーミングアーキテクチャ（推奨）
1. **ストリーミングテキスト抽出** - 全文をキャッシュせず、読み取りながら処理。
2. **ストリーミングチャンキング** - 一度に一つのテキストブロックのみを処理。
3. **増分インデックス** - チャンクごとにベクトル化とインデックス化を順次実行。
### フェーズ3：非同期キュー
1. **タスクキュー** - Redis/BullMQ を活用。
2. **バックグラウンド処理** - メインスレッドをブロックしないよう設計。
3. **進捗フィードバック** - リアルタイムな進捗バー表示。
---
## テストと検証
### テストシナリオ
| ファイルサイズ | チャンクサイズ | チャンク数 | 処理時間 | メモリピーク | 結果 |
|----------|----------|----------|----------|----------|------|
| 10MB | 200 | 20,000 | 8秒 | 280MB | ✅ |
| 50MB | 200 | 100,000 | 35秒 | 450MB | ✅ |
| 100MB | 200 | 200,000 | 72秒 | 680MB | ✅ |
| 500MB | 200 | 1,000,000 | 310秒 | 950MB | ✅ |
---
## デプロイのアドバイス
### Docker Compose
```yaml
services:
server:
environment:
- NODE_OPTIONS=--max-old-space-size=2048
- MAX_FILE_SIZE=104857600
- CHUNK_BATCH_SIZE=100
- MAX_MEMORY_USAGE_MB=1024
- GC_THRESHOLD_MB=800
```
### 本番環境のモニタリング
- メモリ使用率の監視
- 処理時間の計測
- エラー率の追跡
- アラートしきい値の設定
---
## まとめ
### 主要な改善点
1. ✅ **フロントエンドの制限**: デフォルトのチャンクサイズ縮小、ファイルサイズ制限。
2. ✅ **バックエンドの検証**: ファイル形式、サイズ、設定値のバリデーション。
3. ✅ **バッチ処理**: 100 チャンクごとの処理、および動的な調整。
4. ✅ **メモリ監視**: リアルタイム監視と自動ガベージコレクション。
5. ✅ **設定の柔軟化**: 環境変数による全パラメータの制御。
### メモリ最適化の効果
- **ピークメモリ**: 7GB以上から 1GB未満へ削減。
- **安定性**: メモリ溢れによる停止を回避。
- **拡張性**: より大容量のファイル処理に対応。
### ユーザー体験の向上
- 明確なエラー表示。
- 合理的な初期構成。
- 処理の進捗を可視化。
- システム全体の安定稼働。