A newer version of the Gradio SDK is available:
5.45.0
Genemicliと実践！GitHub ActionsでHugging Face SpacesへAIアプリを自動デプロイするガイド
AIモデルを使ったアプリケーション開発は、時に予期せぬ課題に直面します。しかし、genemicliのような強力なCLIアシスタントと連携することで、それらの課題を乗り越え、スムーズにプロジェクトを進めることができます。この記事では、私たちがgenemicliと共に、GitHub ActionsとHugging Face Spacesを連携させ、AIアプリケーションを自動でデプロイするまでの道のりを、具体的な実装手順と問題解決のプロセスを交えながら解説します。
1. Hugging Face Spacesの準備
まず、Hugging Face Spacesで新しいSpaceを作成します。
- Hugging Faceにログインし、「Spaces」タブから「Create new Space」を選択。
- 「Space name」を決め、「Gradio」SDKを選択します。
- 「Create Space」をクリック。
2. GitHubリポジトリの準備
あなたのAIアプリケーションのコードがGitHubリポジトリにあることを確認してください。
3. Hugging Faceアクセストークンの取得
GitHub ActionsからHugging Face Spacesにアクセスするために、アクセストークンが必要です。
- Hugging Faceにログインし、右上のプロフィールアイコン → 「Settings」 → 「Access Tokens」へ。
- 「New token」をクリックし、
write権限を持つトークンを作成し、コピーします。
4. GitHub Secretsへのトークン登録
コピーしたアクセストークンをGitHubリポジトリのSecretsに登録します。これは、セキュリティのためにコードに直接トークンを書き込まないための重要な手順です。
- GitHubリポジトリの「Settings」→「Secrets and variables」→「Actions」へ。
- 「New repository secret」をクリックし、Nameを
HF_TOKEN、Secretにコピーしたトークンを貼り付けて登録します。genemicliとの連携:genemicliは、このHF_TOKENの登録方法を丁寧に案内してくれました。
4.5. アプリケーション用Secretsの登録 (Hugging Face Spaces側)
HF_TOKENはGitHub Actionsがデプロイを行うために必要なトークンですが、デプロイされたアプリケーション自体が実行時に必要とする機密情報（APIキーやパスワードなど）は、Hugging Face Spaces側で設定する必要があります。
今回のプロジェクトでは、APIを保護するためのGRADIO_PASSWORDが必要です。
- Hugging Face Spaceの「Settings」ページに移動します。
- 「Variables and Secrets」セクションで、「New secret」をクリックします。
- Nameを
GRADIO_PASSWORD、Valueに設定したいパスワードを入力して登録します。
これにより、アプリケーションは安全にパスワードを読み込んで認証を有効にすることができます。
5. GitHub Actionsワークフローの作成
GitHubリポジトリのルートに .github/workflows/sync-to-space.yml というファイルを作成し、以下の内容を記述します。このワークフローは、GitHubのmainブランチへのプッシュをトリガーにして、Spaceのコンテンツを自動で更新します。
name: Sync to Hugging Face hub
on:
push:
branches: [main] # mainブランチへのプッシュをトリガー
workflow_dispatch: # 手動実行も可能にする
jobs:
sync-to-hub:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
lfs: true # LFSファイルがある場合
- name: Push to hub
env:
HF_TOKEN: ${{ secrets.HF_TOKEN }} # GitHub Secretsからトークンを取得
run: |
# Spaceのリモートを追加（YOUR_HF_USERNAMEとYOUR_SPACE_NAMEを置き換える）
git remote add space https://YOUR_HF_USERNAME:${{ secrets.HF_TOKEN }}@huggingface.co/spaces/YOUR_HF_USERNAME/YOUR_SPACE_NAME
# mainブランチをSpaceに強制プッシュ
git push --force space main
注意点:
YOUR_HF_USERNAMEとYOUR_SPACE_NAMEは、あなたのHugging Faceのユーザー名とSpace名に置き換えてください。fetch-depth: 0とlfs: trueは、大きなモデルファイルなどを扱う場合に重要です。genemicliとの連携:genemicliは、このワークフローの作成をサポートし、YOUR_HF_USERNAMEとYOUR_SPACE_NAMEを実際の値に置き換えるよう指示してくれました。
6. README.md の設定
Hugging Face Spacesは、README.mdの先頭にあるメタデータブロックを読み込んでSpaceの設定を行います。あなたのREADME.mdの先頭に以下の内容を追加してください。
---
title: あなたのアプリのタイトル
emoji: ✨
colorFrom: "#FFD700" # 好みの色に
colorTo: "#FFA500" # 好みの色に
sdk: gradio
sdk_version: "4.x.x" # requirements.txtのGradioバージョンに合わせる
app_file: app.py # アプリケーションのエントリーポイントファイル
pinned: false
---
注意点:
title、emoji、colorFrom、colorToは自由に設定してください。sdk_versionはrequirements.txtに記載されているGradioのバージョンに合わせてください。app_fileは、あなたのGradioアプリケーションのメインファイル（例:app.pyやsrc/main.pyなど）のパスを記述します。genemicliとの連携:genemicliは、Spaceが画面表示されない問題に直面した際、このREADME.mdのメタデータ設定が不足していることを特定し、必要な項目（title、sdk、app_fileなど）の追加を提案・適用してくれました。
7. アプリケーションのエントリーポイントの調整 (app.pyの作成)
Hugging Face SpacesでModuleNotFoundErrorが発生した場合、アプリケーションのエントリーポイントを調整する必要があります。これは、Pythonのモジュールパスの問題を解決するためです。
GitHubリポジトリのルートに app.py というファイルを作成し、以下の内容を記述します。
import sys
sys.path.append('./src') # srcディレクトリをPythonのパスに追加
from ai_api.main import iface # src/ai_api/main.pyからifaceオブジェクトをインポート
if __name__ == "__main__":
iface.launch(server_name="0.0.0.0") # Gradioアプリケーションを起動
genemicliとの連携:genemicliは、Space上でModuleNotFoundError: No module named 'ai_api'というエラーが発生した際、このapp.pyラッパーファイルの作成を提案・実装してくれました。これにより、srcディレクトリ内のモジュールが正しく認識され、アプリケーションが起動できるようになりました。
8. デプロイの確認
これらの設定が完了したら、GitHubリポジリにコードをプッシュしてください。GitHub Actionsが自動的に実行され、Hugging Face Spaceにコードが同期されます。
Hugging Face Spaceのページにアクセスし、アプリケーションが正常に表示されるか確認しましょう。もし問題があれば、Spaceページの「Logs」タブでエラーメッセージを確認してください。