forked from hangshuo652/aurak
Developer
0a9588abb7
- Add pagination support to findAll (page, limit query params) - Add findByTemplateId method to service - Add GET /by-template/:templateId endpoint to controller - Service already includes CRUD for QuestionBank and QuestionBankItem
215 lines
5.6 KiB
Markdown
215 lines
5.6 KiB
Markdown
# LibreOffice FastAPI ドキュメント変換サービス
|
|
|
|
## 📋 概要
|
|
|
|
これは FastAPI ベースの独立したドキュメント変換サービスで、Word、PPT、Excel などのドキュメントを PDF に変換するために使用されます。RAG の高精度モードにおけるドキュメント処理パイプラインをサポートします。
|
|
|
|
## 🎯 コア機能
|
|
|
|
- **形式変換**: Word/PPT/Excel → PDF
|
|
- **PDF スルーパス**: PDF ファイルは変換せずにそのまま返却
|
|
- **自動ドキュメント生成**: `/docs` にアクセスしてインタラクティブな API ドキュメントを確認可能
|
|
- **ヘルスチェック**: `/health` エンドポイントによるサービス状態の監視
|
|
- **非同期処理**: FastAPI の非同期アーキテクチャによる高性能な処理
|
|
|
|
## 🚀 クイックスタート
|
|
|
|
### ローカル開発
|
|
|
|
```bash
|
|
# 1. 依存関係のインストール
|
|
pip install -r requirements.txt
|
|
|
|
# 2. サービスの起動
|
|
uvicorn main:app --reload --port 8100
|
|
|
|
# 3. ドキュメントへのアクセス
|
|
open http://localhost:8100/docs
|
|
```
|
|
|
|
### Docker デプロイ
|
|
|
|
```bash
|
|
# 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 に変換します。
|
|
|
|
**リクエスト**:
|
|
|
|
```bash
|
|
curl -X POST -F "file=@test.docx" http://localhost:8100/convert
|
|
```
|
|
|
|
**レスポンス**:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
ヘルスチェックを行います。
|
|
|
|
**レスポンス**:
|
|
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"service": "libreoffice-converter",
|
|
"version": "1.0.0",
|
|
"uptime": 123.45
|
|
}
|
|
```
|
|
|
|
### GET /docs
|
|
|
|
自動生成される API ドキュメント (Swagger UI) です。
|
|
|
|
## 🐳 Docker Compose との統合
|
|
|
|
メインプロジェクトの `docker-compose.yml` に以下を追加してください：
|
|
|
|
```yaml
|
|
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秒 | 直接返却 |
|
|
|
|
## 🛠️ デバッグのヒント
|
|
|
|
### ログの確認
|
|
|
|
```bash
|
|
docker logs -f lo-converter
|
|
```
|
|
|
|
### 変換テスト
|
|
|
|
```bash
|
|
# テストファイルの準備
|
|
echo "test" > test.docx
|
|
|
|
# 変換テストの実行
|
|
curl -X POST -F "file=@test.docx" http://localhost:8100/convert | jq
|
|
```
|
|
|
|
### コンテナ内でのデバッグ
|
|
|
|
```bash
|
|
docker exec -it lo-converter sh
|
|
```
|
|
|
|
## 🔗 依存関係の説明
|
|
|
|
- **FastAPI**: モダンな Python Web フレームワーク
|
|
- **Uvicorn**: ASGI サーバー
|
|
- **LibreOffice**: ドキュメント変換エンジン
|
|
- **Pydantic**: データバリデーション
|
|
|
|
## 📝 注意事項
|
|
|
|
1. **ファイルサイズ**: 100MB 以内に制限することを推奨します。
|
|
2. **タイムアウト**: デフォルトは 300 秒です。必要に応じてコード内で調整してください。
|
|
3. **並列処理**: 2〜3 個のワーカーを推奨します。
|
|
4. **メモリ制限**: 1GB を推奨します。
|
|
5. **一時ファイル**: 定期的なクリーンアップが必要です。
|
|
|
|
## 🎯 メインシステムとの連携
|
|
|
|
### サーバー側の呼び出し例
|
|
|
|
```typescript
|
|
// 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](../README.md)
|
|
- [Vision Pipeline の設計](../docs/VISION_PIPELINE_COMPLETE.md)
|
|
- [デプロイガイド](../docs/DEPLOYMENT.md)
|
|
|
|
## 🚨 故障診断
|
|
|
|
| 問題 | 原因 | 解決策 |
|
|
|------|------|---------|
|
|
| 変換失敗 | LibreOffice がインストールされていない | Dockerfile の依存関係を確認してください |
|
|
| タイムアウト | ファイルが大きすぎる | タイムアウト時間を増やすか、ファイルを分割してください |
|
|
| ポート競合 | 8100 ポートが既に使用されている | ポートマッピングを変更してください |
|
|
| 権限エラー | ディレクトリの権限不足 | ボリュームの権限を確認してください |
|
|
|
|
## 📄 ライセンス
|
|
|
|
MIT License
|