README.md

metadata

title: test
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 4.42.0
app_file: work/spaces/test/app.py
pinned: false

🔔上記はHuggingfaceのSpacesの設定です。 Spacesを作成する場合は各リポジトリごとに以上を書き換えてください。 詳細な説明はHuggingface Spacesの設定にて記載しています。

🚀 Almondo PoC Template

このリポジトリは、PoCプロジェクトのための包括的なテンプレートです。本READMEでは、プロジェクトのセットアップから開発プロセス、ディレクトリ構造まで、詳細かつ分かりやすく説明します。

📑 目次

• 🚀 Almondo PoC Template
  • 📑 目次
  • 🛠 セットアップ
    • 前提条件
    • セットアップ手順
    • Dockerの基本操作
    • パッケージの管理
  • 🔄 開発の手順
    • 開発フロー
  • 📂 ディレクトリ構造
    • 主要ディレクトリの説明
      • work/
      • data/
  • VSCode上での作業(Dev container)
    • 前提条件
    • 🔧 セットアップ手順
      • 1️⃣ 拡張機能のインストール
      • 2️⃣ プロジェクトを開く
      • 3️⃣ Dev Containerの設定
      • 4️⃣ Dev Container内でプロジェクトを再オープン
      • 5️⃣ 開発開始
  • Huggingface Spacesの設定

🛠 セットアップ

前提条件

• git,dockerのインストール

セットアップ手順

1. リポジトリのクローン

   git clone [リポジトリのurl]
   cd [ディレクトリ名]
   

2. デフォルトブランチの確認

   git branch
   

   💡 developブランチがアクティブであることを確認してください。

   * develop
     main
   

3. 環境設定ファイルの作成

   cp .env.dev.template .env.dev
   

   ⚠️ .env.devファイルを編集し、必要な環境変数を設定してください。

4. Dockerコンテナの起動

   docker-compose run development bash
   

   🔔 初回実行時はイメージのビルドが行われるため、時間がかかる場合があります。

5. パッケージのインストール

   poetry install
   

   📘 これにより、pyproject.tomlに定義された全ての依存パッケージがインストールされます。

Dockerの基本操作

コマンド	説明
docker ps	実行中のコンテナ一覧を表示
docker compose exec development bash	実行中のコンテナに接続
docker-compose down	コンテナを停止し削除

パッケージの管理

Poetryを使用してパッケージを管理します。

• パッケージの追加:

  poetry add [パッケージ名]
  

• パッケージの削除:

  poetry remove [パッケージ名]
  

• lock fileの更新:

  poetry lock
  

📝 パッケージの追加や削除を行った後は必ずlock fileを更新して、poetry.lockとpyproject.tomlの差分をコミットしてください

🔄 開発の手順

本プロジェクトでは、効率的かつ体系的な開発を行うため、Issue driven開発手法を採用しています。

📚 詳細はIssue driven運用のドキュメントをご参照ください。

開発フロー

1. Issueの作成

   • リポジトリの「Issues」タブから新規Issueを作成
   • タスクの詳細、目的、期待される結果を明確に記述

2. ブランチの作成 作成したIssueからGUI上でbranchを作成してください

   • 命名規則:
     • 新機能追加: feature/[機能名]
     • バグ修正/改善: fix/[修正内容]

3. 開発作業 GUI上で作成したbranchをローカルにfetchします

   git fetch origin
   git checkout [branch名]
   

   • コードの実装
   • ユニットテストの作成・実行

4. 変更内容のコミットとプッシュ blackとisortをコミット前に実行

   isort .
   black .
   git add .
   git commit -m "commit message"
   git push origin [branch名]
   

5. プルリクエスト(PR)の作成

   • GitHub上で「Compare & pull request」ボタンをクリック
   • PRの説明を記入する

6. コードレビュー

   • PjMがコードをチェック
   • フィードバックがある場合は修正を行い、再度プッシュ

7. マージと後処理

   • レビュー承認後、GUI上でdevelopブランチにマージ
   • GUI上で作業ブランチの削除

💡 Tip: 常にdevelopブランチの最新状態を維持するよう心がけましょう。作業開始前に以下のコマンドを実行することをおすすめします：

git checkout develop
git pull origin develop
git switch [branch名]
git merge —no-ff develop

📂 ディレクトリ構造

root/
├── .github/
│   └── workflows/           # CI/CDワークフロー定義
│       └── pysen-python-app.yaml
├── data/                    # データ関連ファイル (Gitで管理されません)
│   ├── models/              # 学習済みモデル (.pth等)
│   ├── preprocessed/        # 前処理済みデータ (CSV等)
│   ├── raw/                 # 生データ (提供されたExcel等)
│   └── results/             # 解析結果
├── work/                    # プロジェクトのメインコード
│   ├── example/             # デモやサンプルコード
│   ├── experiments/         # 実験用コード
│   ├── src/                 # 共通ライブラリやユーティリティ
│   └── tests/               # テストコード
├── .env.dev.template        # 開発環境変数テンプレート
├── .gitignore               # Git除外設定
├── Dockerfile               # Dockerイメージ定義
├── README.md                # プロジェクト説明 (本ファイル)
├── docker-compose.yml       # Docker Compose設定
├── entrypoint.sh            # Dockerエントリーポイントスクリプト
├── poetry.lock              # 依存関係ロックファイル
├── pyproject.toml           # Poetryプロジェクト設定
└── LICENSE                  # ライセンス情報

主要ディレクトリの説明

work/

• example/: クリーンなデモ用コード、Spaces用スクリプトなど
• experiments/: 実験的コードや一時的なスクリプト
• src/: プロジェクト共通の基本クラスやユーティリティ
• tests/: 単体テストコード

data/

• models/: 学習済みモデル（.pthファイルなど）
• preprocessed/: 前処理済みデータ（CSVやテキストファイル）
• raw/: 元データ（提供されたExcelファイルなど）
• results/: 各タスクの出力結果

⚠️ 注意: data/ディレクトリの内容はGitで管理されません。dataディレクトリからdata.zipファイルに圧縮しgoogledriveにて保管してください。

VSCode上での作業(Dev container)

vscode上でdocker環境で作業する方法に[Dev container]という拡張機能があるのでご紹介します

前提条件

以下のツールがインストールされていることを確認してください：

• ✅ Visual Studio Code
• ✅ Docker Desktop (起動済みであること)

🔧 セットアップ手順

1️⃣ 拡張機能のインストール

詳細手順を表示

1. VSCodeを開く
2. 左サイドバーの拡張機能アイコン（🧩）をクリック（または Ctrl+Shift+X / Cmd+Shift+X）
3. 検索バーに "Remote Development" と入力
4. 表示された拡張機能をインストール

2️⃣ プロジェクトを開く

詳細手順を表示

1. VSCodeで開発したいプロジェクトのフォルダを開く（File > Open Folder）

3️⃣ Dev Containerの設定

詳細手順を表示

1. コマンドパレットを開く（Ctrl+Shift+P または Cmd+Shift+P）
2. "Dev containers:Add Dev Containers Configuration Files..." と入力し選択
3. プロジェクトに適したテンプレートを選択（例：Python, Node.js など）

4️⃣ Dev Container内でプロジェクトを再オープン

詳細手順を表示

1. コマンドパレットを再度開く
2. "Dev-Containers: Reopen in Container" を選択
3. VSCodeがコンテナをビルドし、プロジェクトを開くのを待つ

5️⃣ 開発開始

• 🎉 コンテナ内でVSCodeが起動したら、開発を開始できます
• 💻 ターミナルも自動的にコンテナ内で動作します

🔗 詳細情報は公式VSCode Dev Containersドキュメントをご覧ください。

Huggingface Spacesの設定

以下の設定を書き換えてくささい