aurak/QUICK_START.md

クイックスタートガイド

🚀 5分でクイック起動

1. 環境設定

# プロジェクトディレクトリに移動
cd /home/fzxs/workspaces/demo/simple-kb

# 環境設定ファイルの作成
cp server/.env.sample server/.env

# 設定の編集
vim server/.env

2. 依存関係のインストール

yarn install

3. サービスの起動

# 基本サービスの起動
docker-compose up -d elasticsearch tika libreoffice

# 開発サーバーの起動
yarn dev

4. サービスの検証

# サービスの状態を確認
docker-compose ps

# 期待される出力:
# NAME                COMMAND                  STATUS
# local-es            ...                      Up
# simple-kb-tika      ...                      Up
# simple-kb-libreoffice ...                    Up

http://localhost:5173 にアクセスして開始してください！

📝 利用フロー

ステップ1: システムへログイン

1. http://localhost にアクセスします。
2. 既存のアカウントでログインするか、新しいアカウントを登録します。

ステップ2: モデルの設定

1. 「モデル管理」に移動します。
2. Vision モデルを追加します (OpenAI/Gemini をサポート)。
3. API キーを設定します。
4. デフォルトの Vision モデルとして設定します。

ステップ3: ドキュメントのアップロード

1. 「ドキュメントのアップロード」をクリックします。
2. PDF/Word/PPT ファイルを選択します。
3. アップロード用モーダルウィンドウで:
   • Embedding(埋め込み)モデルを選択します。
   • 処理モードを選択します:
     • ⚡ 高速モード: テキストのみを抽出
     • 🎯 高精度モード: 画像とテキストを混合して分析
   • チャンク設定を調整します (任意)。
4. 「処理開始」をクリックします。

ステップ4: 結果の確認

1. バックエンドの処理が完了するまで待ちます。
2. ファイルの状態を確認します: 「処理中」 → 「抽出完了」 → 「ベクトル化完了」
3. チャット画面で RAG 検索をテストします。

🔍 モード選択ガイド

高速モードを使用する場合

✅ 推奨シーン:

• テキストのみのドキュメント
• コードファイル
• シンプルな Markdown
• 画像コンテンツが不要な場合

メリット:

• 処理が速い (数秒)
• 追加コストがかからない
• 安定していて信頼性が高い

高精度モードを使用する場合

✅ 推奨シーン:

• PDF ドキュメント (画像とテキストが混在しているもの)
• Word/PPT (グラフや表が含まれているもの)
• レイアウト情報を保持する必要がある場合
• 重要なドキュメント

メリット:

• 画像コンテンツを保持
• グラフや表を認識
• ページのレイアウトを保持
• インデックスの質が高い

注意点:

• API 利用料が必要 (目安: $0.01/ページ)
• 処理に時間がかかる
• Vision モデルの設定が必要

💰 コスト管理

利用枠(クォータ)の確認

# ユーザーのクォータを照会
GET /api/users/:userId/quota

# レスポンス例
{
  "monthlyCost": 15.50,
  "maxCost": 100,
  "remaining": 84.50,
  "usagePercent": 15.5
}

コスト見積もり

ファイルタイプ	サイズ	ページ数	予想コスト	予想時間
PDF	10MB	~20ページ	$0.20	60秒
Word	5MB	~10ページ	$0.10	30秒
PPT	15MB	~30ページ	$0.30	90秒

クォータの管理

-- 管理者によるクォータのリセット
UPDATE users SET monthly_cost = 0 WHERE id = 'user-uuid';

-- クォータ制限の調整
UPDATE users SET max_cost = 200 WHERE id = 'user-uuid';

🐛 トラブルシューティング

問題1: LibreOffice サービスが利用できない

症状:

❌ LibreOffice 健康診断: 失敗

解決策:

docker-compose up -d libreoffice
docker-compose logs libreoffice

問題2: ImageMagick がインストールされていない

症状:

❌ convert: command not found

解決策:

# server イメージを再ビルド
docker build -t simple-kb-server:latest ./server/
docker-compose up -d server

問題3: クォータ不足

症状:

❌ クォータ不足: 残り $5.00, 必要 $10.00

解決策:

• 翌月の自動リセットを待つ
• 管理者に連絡してクォータを増やす
• 高速モードで処理する

問題4: 一時ファイルが多すぎる

症状:

⚠️  100個以上の一時ファイルが見つかりました

解決策:

# 手動でクリーンアップ
rm -rf temp/*

# または .env で自動クリーンアップを設定
TEMP_CLEANUP=true

📊 モニタリングとログ

処理ログを確認する

# リアルタイムログ
docker-compose logs -f server

# Vision Pipeline のログをフィルタリング
docker-compose logs -f server | grep "Vision\|高精度モード\|コスト"

主要なログの例

✅ 高精度モードでの処理を開始
✅ 予想コスト: $0.15, 予想時間: 45秒
✅ クォータチェックに合格
✅ PDFを画像に変換: 15ページ
✅ Vision 分析: 15/15 成功
✅ 実際のコストを差し引きました: $0.15
✅ 処理完了: 所要時間 42秒

🎯 ベストプラクティス

1. ドキュメントの準備

• ファイルサイズの最適化: 大容量ファイルは分割して処理します。
• 鮮明な画像: 高品質な画像の方が認識精度が高まります。
• 標準フォーマット: PDF > Word > PPT の順で推奨されます。

2. モードの選択

• 小規模ファイル (<10MB): 高精度モード
• 大規模ファイル (>50MB): 分割するか、高速モードを検討
• テキストのみ: 高速モード
• 画像・テキスト混在: 高精度モード

3. コスト削減

• 使用率の監視: 75%で警告、90%で重大な警告を表示します。
• 定期的な整理: 不要なドキュメントを削除します。
• バッチ処理: 適切なバッチサイズを使用して効率化します。

4. パフォーマンスの最適化

• チャンクサイズ: 200-500 トークン
• オーバーラップ率: 10-20%
• バッチサイズ: 50-100

📞 テクニカルサポート

ドキュメントの参照

• 詳細な実装: docs/VISION_PIPELINE_IMPLEMENTATION.md
• API ドキュメント: VISION_PIPELINE_SUMMARY.md
• テストスクリプト: server/test-*.ts

デバッグツール

# LibreOffice のテスト
curl http://localhost:8100/health

# Tika のテスト
curl http://localhost:9998

# Elasticsearch のテスト
curl http://localhost:9200

# コンテナの状態を確認
docker-compose ps

✅ チェックリスト

起動前のチェック項目:

• Docker と Docker Compose がインストールされている
• ポート 80, 3001, 8100, 9200, 9998 が他で使用されていない
• server/.env が設定されている
• Vision モデルの API キーが用意されている
• 少なくとも 4GB のメモリが使用可能
• 十分なディスク容量がある (>5GB)

使用前のチェック項目:

• すべてのサービスの状態が Up になっている
• Vision モデルが設定されている
• Embedding(埋め込み)モデルが設定されている
• クォータが十分にある
• テスト用ファイルが用意されている

---

完了です！ これで Vision Pipeline システムを使用して、画像とテキストが混在したドキュメントを処理する準備が整いました！🎉