CR-004 依存関係のバージョン固定 実装完了レポート

実装日時

2025-12-02 13:45（日本時間）

概要

CR-004「依存関係のバージョン固定（特に OpenAI/Google/Tensorflow/Gradio 周り）」を実装しました。本番運用時に上流ライブラリの破壊的変更で突然壊れないよう、主要ランタイム依存のバージョンを明示的に固定しました。

目的: 本番運用時に「上流ライブラリの破壊的変更」で突然壊れないよう、主要ランタイム依存のバージョンを明示的に固定する。

実装ステップ

Step 1: 現状把握

確認したファイル:

  • requirements.txt: ランタイム依存関係（バージョン指定なしのパッケージ多数）
  • requirements-dev.txt: 開発ツール依存関係（バージョン指定なし）
  • pyproject.toml: ツール設定のみ（依存関係なし）
  • Pipfile, poetry.lock: 存在しない

発見事項:

  • 主要パッケージ（openai, tensorflow, google-generativeai, gradio）がバージョン指定なし
  • Flask, FastAPI, Celery などの重要フレームワークもバージョン指定なし
  • pytest 関連が requirements.txt と requirements-dev.txt の両方に含まれている（重複）

Step 2: requirements.txt のバージョン固定

変更ファイル: requirements.txt

実装内容:

  1. コアAI/MLパッケージ:
    • openai>=1.30.0,<2.0.0 - OpenAI SDK 1.x 系を前提
    • tensorflow>=2.14.0,<3.0.0 - TensorFlow 2.x 系を前提
    • google-generativeai>=0.4.0,<1.0.0 - Google Generative AI 0.x 系を前提
    • scipy>=1.10.0,<2.0.0 - SciPy 1.x 系を前提
  2. Web UI/Server パッケージ:
    • gradio>=4.16.0,<5.0.0 - Gradio 4.x 系を前提
    • fastapi>=0.110.0,<1.0.0 - FastAPI 0.x 系を前提
    • Flask>=2.2.0,<3.0.0 - Flask 2.x 系を前提
    • celery>=5.3.0,<6.0.0 - Celery 5.x 系を前提
    • その他のWeb関連パッケージもバージョンレンジを設定
  3. テストフレームワーク:
    • pytest>=7.4.0,<8.0.0
    • pytest-cov>=4.1.0,<5.0.0
    • pytest-anyio>=4.0.0,<5.0.0
    • pytest-mock>=3.12.0,<4.0.0
    • 注: pytest 関連は requirements-dev.txt にも含まれているが、CI/CD やランタイムでのテスト実行を考慮して requirements.txt にも含めている
  4. その他のランタイム依存:
    • 音声処理、翻訳、ユーティリティパッケージもバージョンレンジを設定

Step 3: requirements-dev.txt のバージョン固定

変更ファイル: requirements-dev.txt

実装内容:

  1. 開発ツール:
    • black>=23.12.0,<25.0.0 - Black フォーマッタ
    • ruff>=0.1.0,<1.0.0 - Ruff リンター
    • mypy>=1.7.0,<2.0.0 - mypy 型チェック
    • pytest>=7.4.0,<8.0.0 - pytest（requirements.txt と重複）
    • pytest-cov>=4.1.0,<5.0.0 - pytest-cov（requirements.txt と重複）
  2. 型付きスタブ:
    • types-requests>=2.31.0,<3.0.0
    • types-PyYAML>=6.0.0,<7.0.0

Step 4: ドキュメントの更新

変更ファイル:

  • README.md
  • docs/TEST_EXECUTION_GUIDE.md

実装内容:

  1. README.md:
    • 依存関係インストール時のバージョン固定に関する注意書きを追加
    • 開発ツールのインストール方法を明記
  2. docs/TEST_EXECUTION_GUIDE.md:
    • 依存関係のバージョンレンジに関する注意事項セクションを追加
    • 主要な依存関係のバージョンレンジを明記

変更ファイル一覧

変更ファイル

  • requirements.txt: 主要ランタイム依存関係のバージョンレンジを追加
  • requirements-dev.txt: 開発ツールのバージョンレンジを追加
  • README.md: 依存関係のバージョン固定に関する注意書きを追加
  • docs/TEST_EXECUTION_GUIDE.md: バージョンレンジに関する注意事項を追加

動作確認結果

静的解析結果

  • リンターエラー: なし
  • ファイル形式: すべての requirements.txt と requirements-dev.txt の形式が正しいことを確認

バージョン固定の確認

主要パッケージのバージョンレンジ:

パッケージ バージョンレンジ 理由
openai >=1.30.0,<2.0.0 OpenAI SDK 1.x 系を前提（2.0 で破壊的変更の可能性）
tensorflow >=2.14.0,<3.0.0 TensorFlow 2.x 系を前提（3.0 で破壊的変更の可能性）
google-generativeai >=0.4.0,<1.0.0 Google Generative AI 0.x 系を前提
gradio >=4.16.0,<5.0.0 Gradio 4.x 系を前提（5.0 で破壊的変更の可能性）
Flask >=2.2.0,<3.0.0 Flask 2.x 系を前提（3.0 で破壊的変更の可能性）
FastAPI >=0.110.0,<1.0.0 FastAPI 0.x 系を前提
Celery >=5.3.0,<6.0.0 Celery 5.x 系を前提（6.0 で破壊的変更の可能性）

設計上の改善点

アーキテクチャの改善

  • バージョンレンジ固定により、メジャーバージョンアップでの破壊的変更を防止
  • マイナーバージョンアップは許可することで、セキュリティパッチやバグ修正を自動的に取り込める

将来の拡張性への配慮

  • バージョンレンジ形式（>=x.y,<x+1.0）により、将来的なメジャーバージョンアップ時の対応が容易
  • コメントでバージョン固定の理由を明記し、将来のメンテナンスを容易に

コード品質の向上

  • すべての主要依存関係にバージョンレンジを設定
  • ドキュメントにバージョン固定に関する注意書きを追加

既知の制約・注意事項

既存コードとの互換性

  • 既存のインストールコマンド（pip install -r requirements.txt）は変更なし
  • 既存のCI/CDパイプラインとの互換性を維持

制限事項やトレードオフ

  • pytest の重複: pytest 関連が requirements.txt と requirements-dev.txt の両方に含まれているが、CI/CD やランタイムでのテスト実行を考慮して意図的に重複させている
  • バージョンレンジの幅: メジャーバージョン内での互換性を前提としており、マイナーバージョン間での破壊的変更は考慮していない

移行時の注意点

  • 既存環境での更新: 既存の環境で pip install -r requirements.txt --upgrade を実行すると、指定されたバージョンレンジ内の最新版がインストールされる
  • 新規環境でのインストール: 新規環境では、指定されたバージョンレンジ内の最新版がインストールされる

次のステップ

推奨されるフォローアップアクション

  1. requirements.lock.txt の生成:
    • pip freeze > requirements.lock.txt を実行して、実際にインストールされたバージョンを記録
    • CI/CD で使用する場合は、requirements.lock.txt を使用して再現性を確保
  2. 定期的なバージョン更新:
    • 定期的に依存関係のバージョンを確認し、セキュリティパッチや重要なバグ修正を取り込む
    • メジャーバージョンアップの検討（例: OpenAI SDK 2.0 への移行）
  3. 依存関係の監査:
    • pip-audit などのツールを使用して、既知の脆弱性をチェック
    • セキュリティパッチが利用可能な場合は、バージョンレンジを更新
  4. ドキュメントの更新:
    • 新しい依存関係を追加する際は、必ずバージョンレンジを設定することを明記
    • バージョンアップ時の手順をドキュメント化
  5. CI/CD での検証:
    • CI/CD パイプラインで、指定されたバージョンレンジ内でのテストを実行
    • バージョン更新時の自動テストを実装

関連ファイル

  • requirements.txt: ランタイム依存関係（バージョンレンジ固定済み）
  • requirements-dev.txt: 開発ツール依存関係（バージョンレンジ固定済み）
  • README.md: 依存関係のインストール方法とバージョン固定に関する注意書き
  • docs/TEST_EXECUTION_GUIDE.md: テスト実行時の依存関係バージョンに関する注意事項
  • docs/completion_reports/CR-004_DEPENDENCY_VERSION_PINNING_COMPLETION_REPORT.md: 本レポート
This site uses Just the Docs, a documentation theme for Jekyll.