KnowledgeBase/libreoffice-server

LibreOffice FastAPI ドキュメント変換サービス

📋 概要

これは FastAPI ベースの独立したドキュメント変換サービスで、Word、PPT、Excel などのドキュメントを PDF に変換するために使用されます。RAG の高精度モードにおけるドキュメント処理パイプラインをサポートします。

🎯 コア機能

• 形式変換: Word/PPT/Excel → PDF
• PDF スルーパス: PDF ファイルは変換せずにそのまま返却
• 自動ドキュメント生成: /docs にアクセスしてインタラクティブな API ドキュメントを確認可能
• ヘルスチェック: /health エンドポイントによるサービス状態の監視
• 非同期処理: FastAPI の非同期アーキテクチャによる高性能な処理

🚀 クイックスタート

ローカル開発

# 1. 依存関係のインストール
pip install -r requirements.txt

# 2. サービスの起動
uvicorn main:app --reload --port 8100

# 3. ドキュメントへのアクセス
open http://localhost:8100/docs

Docker デプロイ

# 1. イメージのビルド
docker build -t libreoffice-server .

# 2. コンテナの実行
docker run -d \
  --name lo-converter \
  -p 8100:8100 \
  -v ./uploads:/uploads \
  -v ./temp:/temp \
  libreoffice-server

# 3. ヘルスチェック
curl http://localhost:8100/health

📡 API エンドポイント

POST /convert

ドキュメントを PDF に変換します。

リクエスト:

curl -X POST -F "file=@test.docx" http://localhost:8100/convert

レスポンス:

{
  "pdf_path": "/uploads/test.pdf",
  "converted": true,
  "original": "test.docx",
  "file_size": 102400
}

サポートされている形式:

• .pdf - そのまま返却
• .doc, .docx - Word ドキュメント
• .ppt, .pptx - PowerPoint プレゼンテーション
• .xls, .xlsx - Excel スプレッドシート

GET /health

ヘルスチェックを行います。

レスポンス:

{
  "status": "healthy",
  "service": "libreoffice-converter",
  "version": "1.0.0",
  "uptime": 123.45
}

GET /docs

自動生成される API ドキュメント (Swagger UI) です。

🐳 Docker Compose との統合

メインプロジェクトの docker-compose.yml に以下を追加してください：

services:
  libreoffice:
    build: ./libreoffice-server
    container_name: lo-converter
    volumes:
      - ./uploads:/uploads
      - ./temp:/temp
    ports:
      - "8100:8100"
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'

🔧 環境変数

サービス自体に特別な環境変数は必要ありませんが、ボリュームのマウントによって以下のディレクトリを構成できます：

• /uploads - ドキュメントの保存ディレクトリ
• /temp - 一時ファイルのディレクトリ

📊 パフォーマンスの目安

ドキュメント形式	ページ数	変換時間	備考
Word	50ページ	約10秒	書式を保持
PPT	50ページ	約15秒	各ページを画像として処理
Excel	10ページ	約8秒	表として変換
PDF	任意	約0秒	直接返却

🛠️ デバッグのヒント

ログの確認

docker logs -f lo-converter

変換テスト

# テストファイルの準備
echo "test" > test.docx

# 変換テストの実行
curl -X POST -F "file=@test.docx" http://localhost:8100/convert | jq

コンテナ内でのデバッグ

docker exec -it lo-converter sh

🔗 依存関係の説明

• FastAPI: モダンな Python Web フレームワーク
• Uvicorn: ASGI サーバー
• LibreOffice: ドキュメント変換エンジン
• Pydantic: データバリデーション

📝 注意事項

1. ファイルサイズ: 100MB 以内に制限することを推奨します。
2. タイムアウト: デフォルトは 300 秒です。必要に応じてコード内で調整してください。
3. 並列処理: 2〜3 個のワーカーを推奨します。
4. メモリ制限: 1GB を推奨します。
5. 一時ファイル: 定期的なクリーンアップが必要です。

🎯 メインシステムとの連携

サーバー側の呼び出し例

// server/src/libreoffice/libreoffice.service.ts
async convertToPDF(filePath: string): Promise<string> {
  const fileName = path.basename(filePath);
  const fileBuffer = await fs.readFile(filePath);

  const formData = new FormData();
  formData.append('file', fileBuffer, fileName);

  const response = await axios.post(
    `${this.baseUrl}/convert`,
    formData,
    { timeout: 300000 }
  );

  return response.data.pdf_path;
}

📚 関連ドキュメント

• メインプロジェクト README
• Vision Pipeline の設計
• デプロイガイド

🚨 故障診断

問題	原因	解決策
変換失敗	LibreOffice がインストールされていない	Dockerfile の依存関係を確認してください
タイムアウト	ファイルが大きすぎる	タイムアウト時間を増やすか、ファイルを分割してください
ポート競合	8100 ポートが既に使用されている	ポートマッピングを変更してください
権限エラー	ディレクトリの権限不足	ボリュームの権限を確認してください

📄 ライセンス

MIT License