template-streamlit

概要 (Overview)

template-streamlitは、Streamlitアプリケーションの開発に必要な基本構造とツールを提供するテンプレートリポジトリです。このテンプレートを使用することで、AI 機能を持つ Web アプリケーションを迅速に開発・デプロイすることができます。

This template repository provides the basic structure and tools needed for developing Streamlit applications. By using this template, you can quickly develop and deploy web applications with AI capabilities.

特徴と利点 (Features and Benefits)

主な特徴 (Key Features)

• Streamlit フレームワーク: インタラクティブな Web アプリケーションを短時間で構築
• LangChain サポート: AI モデル（Azure OpenAI、Ollama）との連携機能
• Docker サポート: コンテナベースの開発・デプロイが可能
• テキスト分割プレイグラウンド: 異なるテキスト分割方法の視覚化
• 環境変数管理: API キーなどの機密情報を安全に管理
• MkDocs 統合: プロジェクトドキュメントの自動生成

利点 (Benefits)

• 開発時間の短縮: 必要なコンポーネントが事前構成済み
• Makefile による標準化: 一貫した開発ワークフロー
• コンテナ対応: 環境依存性の問題を削減
• モジュール構造: 拡張や機能追加が容易
• CI パイプライン: ビルドとテスト自動化の設定済み

前提条件 (Prerequisites)

• Python 3.10+
• uv
• GNU Make
• Docker（Docker を使用する場合）

開発手順 (Development Instructions)

当プロジェクトはMakefileを中心とした開発ワークフローを採用しています。主な操作はすべて Make コマンドから実行できます。

ヘルプ表示 (View Help)

Makefileで定義されているすべてのコマンドを表示するには：

make
# または
make help

ローカル開発 (Local Development)

依存関係のインストール (Install Dependencies)

# 開発用依存関係をインストール
make install-deps-dev

# 本番用依存関係のみをインストール
make install-deps

コードフォーマットとリント (Code Formatting and Linting)

# コードフォーマットを適用
make format

# 自動修正を適用
make fix

# リントチェック
make lint

テスト実行 (Run Tests)

# テストを実行
make test

# CIテストを実行（フォーマットチェック、リント、テスト）
make ci-test

Streamlit アプリの実行 (Run Streamlit App)

# Streamlitアプリを起動（ポート8000）
make streamlit

実行後、ブラウザで http://localhost:8000 を開くと Streamlit アプリケーションにアクセスできます。

その他の開発ツール (Other Development Tools)

# JupyterLabを起動
make jupyterlab

# ドキュメントをローカルで表示
make docs-serve

Docker 開発 (Docker Development)

Docker を使用して開発環境を構築することもできます。

# Dockerイメージをビルド
make docker-build

# Dockerコンテナを実行
make docker-run

# DockerでCIテストを実行
make ci-test-docker

Docker 使用方法 (Docker Usage)

簡単な実行方法 (Quick Start)

Docker を使ってワンライナーでアプリを実行する：

docker run --rm -p 8000:8000 ks6088ts/template-streamlit:latest streamlit run main.py --server.port 8000 --server.address 0.0.0.0

環境変数の設定 (Environment Variables)

環境変数を使用する場合（例：Azure OpenAI API キー）：

# .envファイルをコンテナにマウント
docker run --rm \
  -v $(pwd)/.env:/app/.env \
  -p 8000:8000 \
  ks6088ts/template-streamlit:latest

.envファイルの例（.env.templateをコピーして作成）：

AZURE_OPENAI_API_KEY=your_api_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2023-07-01-preview
AZURE_OPENAI_GPT_MODEL=your-gpt-deployment

ポート設定 (Port Configuration)

デフォルトでポート 8000 を使用しますが、ホスト側のポートは変更可能です：

# ホスト側ポート3000をコンテナの8000にマッピング
docker run --rm \
  -p 3000:8000 \
  ks6088ts/template-streamlit:latest

この場合、ブラウザで http://localhost:3000 にアクセスします。

トラブルシューティング (Troubleshooting)

• コンテナが起動しない場合: ポートが既に使用されていないか確認してください
• 環境変数が読み込まれない場合: .envファイルのパスが正しいか確認してください
• API エラー: .envファイル内の API キーや設定を確認してください

デプロイ手順 (Deployment Instructions)

Docker Hub

Docker Hub にイメージを公開するには、アクセストークンを作成し、リポジトリの設定に以下のシークレットを設定する必要があります。

gh secret set DOCKERHUB_USERNAME --body $DOCKERHUB_USERNAME
gh secret set DOCKERHUB_TOKEN --body $DOCKERHUB_TOKEN