forked from hangshuo652/aurak
feat: implement QuestionBank CRUD with pagination and template query
- 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
This commit is contained in:
Developer
@@ -0,0 +1,214 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user