Hugging Face's logo

Spaces:
chibafes-dev
/
circle-search-26-api
Sleeping

App Files Community
circle-search-26-api / README.md
yukikase's picture
yukikase
docs: README.mdの誤記を修正
7eda24d
preview code
|
Raw
History Blame Contribute Delete
7.46 kB
metadata 
title: Chibafes Website API
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false

千葉大祭団体企画情報の提供&検索システム

目次

APIの仕様

docs/システムガイド.md のセクション7「APIの使い方」を参照してください。

ローカル作業の準備

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

git clone https://github.com/chibafes-dev/circle-search-26-api.git

クローンのためには Read 以上のリポジトリ権限が必要です。また、作業をしてプッシュをするには Write 以上のリポジトリ権限が必要です。

2. ローカルで .env ファイルを作成

以下の...部分を適切な値に変更する。（なんらかの方法で引き継いでもらう。）

# API側 GitHub の secrets と HF Spaces の Secrets の両方に登録
HF_TOKEN=...
# HF Spaces の secrets に登録
API_SECRET_KEY=...
HF_EMBEDDINGS_REPO_ID=...

!!! 注意 !!!
.envは機密情報なので絶対にリポジトリにプッシュしないこと！！.gitignoreに含まれていることを確認してください。

3. 適切なバージョンのPythonを入手する

やり方はいくつかありますが、筆者は pyenv を使用しました。適切なバージョンがインストールできればなんでもいいですが、ここでは pyenv を紹介します。
英語が読める人は 公式リポジトリ を参考にしてインストールしてください。

英語が読めないWindowsユーザー向け（WSL2はLinux向けを確認）

残念ながら pyenv はWindowsに対応していないので、代わりに pyenv-win を使いましょう。

参考：https://github.com/pyenv-win/pyenv-win/blob/master/docs/installation.md#powershell

  1. Powershellで以下のコマンドを実行

    Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

    もし UnauthorizedAccess エラーが出たら、以下のコマンドを「管理者権限で」実行したのち、上のコマンドを再度試してください。

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

  2. インストールができたことを確認する

    以下のコマンドを実行：

    pyenv --version

    バージョン情報が出れば成功。

英語が読めないMacユーザー向け

参考：https://github.com/pyenv/pyenv/blob/master/README.md#macos

  1. どうにかしてHomebrewを入れる

    やり方はググってください。

  2. Homebrew経由で pyenv をインストール

    brew update
brew install pyenv

  3. シェル環境を整える

    zsh を使っている人向けの説明。自分が何を使っているかわからない人は echo $SHELL を実行。

    最近のMacだと zsh がデフォルトらしいです。敢えて bash とか fish にするような方には私の説明は不要だと思うので、公式リポジトリ を見てご自身でうまいことやってほしいです。

    以下の3つのコマンドを1行ずつ順に実行する。

    echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc

  4. シェルを再起動する

    exec "$SHELL"

英語が読めないLinuxユーザー向け（WSL2含む）

参考：https://github.com/pyenv/pyenv/blob/master/README.md#linuxunix

  1. 自動インストーラを使用する

    curl -fsSL https://pyenv.run | bash

<全OS共通> Python をインストールする

  1. .python-version に記載された Python のバージョンを確認

    以下例として 3.12.11 の場合を仮定します。

  2. pyenv で Python をインストールする

    pyenv install 3.12.11

  3. Python のバージョンを切り替え

    pyenv が .python-version を自動で読み取って切り替えてくれるので操作は不要です。

    以下のコマンドで Python のバージョンを確認しましょう。

    pyenv version

    （versionsではない）

手動で切り替えたい場合

このリポジトリ circle-search-26-api があるフォルダに移動し、以下のコマンドを実行

pyenv local 3.12.11

これを実行すると、そのフォルダの中で 3.12.11 が有効化されます。

全部のフォルダで有効化したい場合は local の代わりに global としてください。

4. Pythonの仮想環境を作成・有効化 

python -m venv .venv
source .venv/bin/activate

5. ライブラリをインストール 

pip install --upgrade pip
pip install -r requirements.txt

開発用サーバーの起動

（初回のみ）必要ファイルの作成

!!! 注意 !!!
大容量（約6GB）のダウンロードが発生するので、必ずWiFi環境で行うこと！！

python scripts/build_all.py

サーバー起動 

uvicorn app.main:app --reload

http://localhost:8000からアクセスできます（デフォルトポート）。Hugging Face Spacesでは7860ポートで起動します。

仕組み・企画データ更新

企画データ更新のためには以下のステップを実行してください。

  1. Google Spreadsheets でデータの整理 → CSVファイルのダウンロード
  2. CSVファイルを resources/ に設置
  3. config/files.json 内 circles > original_csv を実際のパス・ファイル名に変更
    {
    ...
    "circles": {
        "original_csv": "resources/original_circles.csv", // ここを変更
        "circles_json": "data/generated/circles.json"
    },
    ...
}
  4. python scripts/build_all.py を実行 → ローカルで動作確認
  5. GitHubにプッシュ（main ブランチにマージ）

詳細な仕組み等は docs/ を確認してください。