Python on KnightLiブログ

uv インストールガイド：macOS、Linux、Windows、pipx、Homebrew、WinGet の選び方

Thu, 07 May 2026 23:23:58 +0800

uv は Astral が提供する Python ツールチェーンマネージャーです。Python バージョン、仮想環境、依存関係、スクリプト、プロジェクト、ツールを管理できます。インストール方法は多く、公式ドキュメントではスタンドアロンインストーラーのほか、PyPI、Homebrew、WinGet、Scoop、Docker、GitHub Releases、Cargo が案内されています。

すばやく入れたいだけなら、まず公式のスタンドアロンインストーラーを使うのがおすすめです。システムのパッケージマネージャーでバージョンを管理したいなら Homebrew、WinGet、Scoop を選びます。Python ツールを隔離環境に入れる運用に慣れているなら pipx が向いています。

すばやく選ぶ

シーン	推奨方法	コマンド
macOS / Linux で素早くインストール	公式スタンドアロンインストーラー	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
macOS / Linux に curl がない	公式スクリプト + wget	`wget -qO- https://astral.sh/uv/install.sh \| sh`
Windows で素早くインストール	PowerShell インストーラー	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`
Python ツールを隔離して入れる	pipx	`pipx install uv`
一時的または従来型の Python インストール	pip	`pip install uv`
macOS のパッケージ管理	Homebrew	`brew install uv`
macOS の MacPorts ユーザー	MacPorts	`sudo port install uv`
Windows のパッケージ管理	WinGet	`winget install --id=astral-sh.uv -e`
Windows の Scoop ユーザー	Scoop	`scoop install main/uv`
Rust ユーザー	Cargo	`cargo install --locked uv`

汎用的におすすめしやすい選択肢は次の通りです。

macOS / Linux：公式スタンドアロンインストーラー；
Windows：公式 PowerShell インストーラー、または WinGet；
pipx で Python CLI ツールを管理している場合：pipx install uv。

macOS と Linux：公式インストーラー

公式でもっとも直接的な方法は、curl でスクリプトを取得して sh に渡す方法です。

`1`	`curl -LsSf https://astral.sh/uv/install.sh \| sh`

システムに curl がない場合は wget を使えます。

`1`	`wget -qO- https://astral.sh/uv/install.sh \| sh`

特定バージョンをインストールしたい場合は、URL にバージョン番号を含めます。たとえば公式例の 0.11.11 は次のようになります。

`1`	`curl -LsSf https://astral.sh/uv/0.11.11/install.sh \| sh`

この方法は、ほとんどの個人開発環境に向いています。シンプルでクロスプラットフォームであり、uv 公式の更新機構とも相性が良いからです。

インストーラーは uv、uvx などのバイナリをユーザーディレクトリ配下に配置し、コマンドをターミナルから直接使えるように shell profile を変更する場合があります。PATH を変更されたくない場合は、公式 installer オプションを確認し、たとえば UV_NO_MODIFY_PATH=1 を設定します。

Windows：PowerShell インストーラー

Windows の公式インストール方法は、PowerShell でインストーラースクリプトを実行する方法です。

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`

特定バージョンをインストールする場合も、URL にバージョン番号を含めます。

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.11/install.ps1 \| iex"`

ここでの ExecutionPolicy ByPass は、インターネットから取得したインストーラースクリプトを実行できるようにするための指定です。安全のため、実行前にスクリプト内容を確認することもできます。

`1`	`powershell -c "irm https://astral.sh/uv/install.ps1 \| more"`

Windows のパッケージマネージャーに慣れているなら、WinGet や Scoop を優先してもよいでしょう。

pipx でインストールする

公式ドキュメントでは、uv が PyPI に公開されていることも説明されています。PyPI からインストールする場合は、pipx などで隔離環境に入れることが推奨されます。

`1`	`pipx install uv`

この方法は、pipx を Python CLI ツールマネージャーとして使っている人に向いています。uv を現在のプロジェクト環境と混ぜずに済みます。

pipx がない場合は、pip を直接使うこともできます。

`1`	`pip install uv`

ただし、uv は多くのプラットフォーム向けに事前ビルド済み wheel を提供していますが、対象 platform の wheel がない場合はソースからビルドされます。その場合は Rust ツールチェーンが必要です。

私のおすすめは、個人マシンでは pip install uv より pipx install uv のほうがきれい、というものです。プロジェクト環境の中では、uv をプロジェクト依存関係として入れないほうがよいでしょう。

Homebrew、MacPorts、WinGet、Scoop

システムのパッケージマネージャーを好む場合、uv は一般的な配布経路にも対応しています。

macOS では Homebrew を使えます。

`1`	`brew install uv`

MacPorts ユーザーは次のコマンドです。

`1`	`sudo port install uv`

Windows では WinGet を使えます。

`1`	`winget install --id=astral-sh.uv -e`

Scoop ユーザーは次の通りです。

`1`	`scoop install main/uv`

これらの方法の利点は、システムのパッケージマネージャーに一元管理できることです。欠点は、更新タイミングが uv 公式インストーラーではなく、各パッケージソースに依存することです。

Docker、GitHub Releases、Cargo

uv は GitHub Container Registry で Docker イメージも提供しています。

`1`	`ghcr.io/astral-sh/uv`

これは CI、Dockerfile、イメージビルド、一時的な実行環境に向いています。実際に使う場合は、公式の Docker 統合ドキュメントも確認するのがおすすめです。

バイナリを手動でダウンロードしたい場合は、GitHub Releases を使えます。各 release ページには通常、対応プラットフォーム向けのバイナリが含まれ、GitHub URL を使ってスタンドアロンインストーラーを呼び出す方法も説明されています。

Rust ユーザーは crates.io からもインストールできます。

`1`	`cargo install --locked uv`

ただし、この方法はソースからビルドするため、互換性のある Rust ツールチェーンが必要です。Rust エコシステムからインストールする明確な理由がない限り、一般ユーザーが Cargo を優先する必要はありません。

uv をアップグレードする

uv を公式スタンドアロンインストーラーで入れた場合は、自己更新コマンドを使えます。

`1`	`uv self update`

公式ドキュメントでは、uv の更新時にインストーラーが再実行され、shell profile が変更される可能性があると説明されています。更新時に PATH を変更されたくない場合は、次を設定します。

`1`	`UV_NO_MODIFY_PATH=1`

別の方法でインストールした場合は、その方法に対応するパッケージマネージャーでアップグレードします。たとえば pip で入れた場合は次の通りです。

`1`	`pip install --upgrade uv`

Homebrew、WinGet、Scoop、MacPorts も、それぞれのアップグレードコマンドを使います。

shell 補完を有効にする

uv は shell 補完に対応しています。公式ドキュメントでは、まず現在の shell を確認することが推奨されています。

`1`	`echo $SHELL`

Bash：

`1`	`echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc`

Zsh：

`1`	`echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc`

fish：

`1`	`echo 'uv generate-shell-completion fish \| source' > ~/.config/fish/completions/uv.fish`

PowerShell：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

uvx もよく使う場合は、uvx の補完を別途有効にできます。

Bash：

`1`	`echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc`

Zsh：

`1`	`echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc`

fish：

`1`	`echo 'uvx --generate-shell-completion fish \| source' > ~/.config/fish/completions/uvx.fish`

PowerShell：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

設定後は shell を再起動するか、対応する設定ファイルを再読み込みします。

uv をアンインストールする

uv をアンインストールする場合は、まずキャッシュと uv が保存しているデータを削除できます。

1
2
3

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

その後、バイナリを削除します。

macOS / Linux：

`1`	`rm ~/.local/bin/uv ~/.local/bin/uvx`

Windows：

1
2
3

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

公式ドキュメントでは、0.5.0 より前の uv は ~/.cargo/bin にインストールされていた点も注意されています。古いバージョンからアップグレードした場合、古いバイナリが残っていることがあるため、手動で削除する必要があります。

インストール後に最初にすること

インストール後は、まずバージョンを確認します。

`1`	`uv --version`

その後、いくつかのよく使うタスクから始められます。

uv python install
uv venv
uv pip install requests
uvx ruff --version

新規プロジェクトなら、次も確認するとよいでしょう。

uv init：プロジェクトを初期化する；
uv add：依存関係を追加する；
uv sync：環境を同期する；
uv run：プロジェクト環境でコマンドを実行する；
uvx：Python CLI ツールを一時的に実行する。

私のおすすめ

個人の開発マシンでは、公式スタンドアロンインストーラーを優先するのがおすすめです。uv 公式ドキュメントにもっとも近く、uv self update も使えるためです。

Windows ユーザーでリモートスクリプトを実行したくない場合は、WinGet や Scoop を使えます。macOS ユーザーでツールをすべて Homebrew に任せたい場合は、brew install uv で問題ありません。

すでに pipx で Python CLI ツールを管理している人は、pipx install uv を使うとよいでしょう。ただし、具体的なプロジェクトの仮想環境内で pip install uv するのはおすすめしません。ツールチェーンとプロジェクト依存関係が混ざりやすくなるからです。

CI やコンテナビルドでは、Docker と GitHub Releases を優先的に確認し、イメージビルドの流れに合わせてバージョンを固定します。

faster-whisper：より高速な Whisper 文字起こしエンジン

Fri, 01 May 2026 22:31:26 +0800

faster-whisper は SYSTRAN がメンテナンスしている Whisper 推論実装です。CTranslate2 をバックエンドとして使い、Whisper に近い使い勝手を保ちながら、推論速度、メモリ使用量、デプロイの柔軟性をエンジニアリング用途に合わせやすくしています。

すでに openai/whisper を使ったことがあるなら、faster-whisper はより本番運用向けの代替実装として理解できます。インターフェースはモデル読み込み、音声文字起こし、セグメント結果の取得を中心にしていますが、実行層はより高速で、CPU、GPU、量子化、バッチ処理に合わせて調整しやすくなっています。

何を解決するのか

Whisper の精度は優れていますが、元の実装をそのままデプロイすると、よく次のような問題に当たります。

長い音声の文字起こしに時間がかかる。
GPU メモリ使用量が大きい。
CPU でも動くが、速度が十分でないことがある。
大量の音声や動画をバッチ処理するとき、スループットを上げにくい。

faster-whisper は主にこれらの問題を改善するための実装です。プロジェクトの README では、同じ精度で openai/whisper より最大 4 倍高速で、メモリ使用量も少ないと説明されています。8-bit 量子化を使うと、さらに速度を上げられます。

インストール

通常の Python 環境では、そのままインストールできます。

`1`	`pip install faster-whisper`

GPU を使う場合は、ローカルの CUDA、cuDNN、CTranslate2 のバージョンが合っているか確認してください。ここでつまずきやすいのは、GPU ドライバーと CUDA ランタイムの不一致です。コード自体に問題がなくても、モデル読み込み時や初回推論時に失敗することがあります。

基本的な使い方

最小構成の例はシンプルです。

from faster_whisper import WhisperModel

model_size = "large-v3"

model = WhisperModel(model_size, device="cuda", compute_type="float16")

segments, info = model.transcribe("audio.mp3", beam_size=5)

print("Detected language '%s' with probability %f" % (info.language, info.language_probability))

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

主なパラメータは次の通りです。

パラメータ	役割
`model_size`	`small`、`medium`、`large-v3` などの Whisper モデルサイズを選ぶ
`device`	推論デバイス。よく使う値は `cuda` または `cpu`
`compute_type`	計算精度。例：`float16`、`int8_float16`、`int8`
`beam_size`	デコード時の探索幅。大きいほど安定しやすいが遅くなる

ローカルで素早く文字起こししたい場合は、まず medium または large-v3 から試すとよいです。GPU メモリが厳しい場合は、量子化を検討します。

CPU と GPU の選び方

NVIDIA GPU がある場合は、まず次の設定を使います。

`1`	`model = WhisperModel("large-v3", device="cuda", compute_type="float16")`

GPU メモリが足りない場合は、次のように変更できます。

`1`	`model = WhisperModel("large-v3", device="cuda", compute_type="int8_float16")`

GPU がない場合は、CPU で実行できます。

`1`	`model = WhisperModel("small", device="cpu", compute_type="int8")`

CPU モードは軽いタスク、低頻度のバックグラウンド処理、または GPU のないサーバーに向いています。大量の長い音声を処理するなら、やはり GPU のほうが適しています。

バッチ文字起こし

faster-whisper はバッチ文字起こしにも対応しています。大量の短い音声を処理する場合や、GPU のスループットを上げたい場合に便利です。

from faster_whisper import WhisperModel, BatchedInferencePipeline

model = WhisperModel("turbo", device="cuda", compute_type="float16")
batched_model = BatchedInferencePipeline(model=model)
segments, info = batched_model.transcribe("audio.mp3", batch_size=16)

for segment in segments:
    print("[%.2fs -> %.2fs] %s" % (segment.start, segment.end, segment.text))

batch_size は大きければよいわけではありません。スループットは上がりますが、GPU メモリの負荷も増えます。実際のデプロイでは、4、8、16 のような値を段階的に試し、安定して動く点を探すのがおすすめです。

VAD と単語単位のタイムスタンプ

音声文字起こしでは、長い無音、背景ノイズ、字幕の位置合わせがよく問題になります。faster-whisper には、文字起こし時にそのまま有効化できる実用的なパラメータがあります。

VAD を有効化する例：

`1`	`segments, info = model.transcribe("audio.mp3", vad_filter=True)`

単語単位のタイムスタンプを取得する例：

segments, info = model.transcribe("audio.mp3", word_timestamps=True)

for segment in segments:
    for word in segment.words:
        print("[%.2fs -> %.2fs] %s" % (word.start, word.end, word.word))

VAD は、会議録音、ポッドキャスト、ライブ配信のアーカイブなど、長い無音を含む音声に向いています。単語単位のタイムスタンプは、字幕生成、逐語録の校正、プレイヤー上での単語ハイライトに便利です。

モデルの選び方

モデル選びでは、主に精度、速度、マシンリソースを見ます。

場面	推奨
すばやく試す	`small` または `medium`
中国語コンテンツで品質優先	`large-v3`
GPU メモリが厳しい	`int8_float16` またはより小さいモデル
CPU でバックグラウンド処理	小さいモデルと `int8`
大量の短い音声	`BatchedInferencePipeline` を試す

中国語音声では、品質を重視するならまず large-v3 を試すのがおすすめです。マシンへの負荷が大きすぎる場合は、モデルサイズを下げるか量子化を使います。最初から速度だけを見るのは避けたほうがよいです。文字起こし品質が下がると、手作業の校正時間で推論時間の節約分が消えてしまうことがあります。

向いている用途

faster-whisper は次のようなタスクに向いています。

動画字幕の生成。
ポッドキャスト、会議、講義録音の文字起こし。
Bilibili、YouTube などの動画をローカルで文字起こしするワークフロー。
音声の一括アーカイブと検索。
音声コンテンツを RAG、ナレッジベース、検索システムに渡す処理。

話者分離、要約、チャプター分割のような上位タスクを直接解決するものではありませんが、安定した文字起こし層として使えます。その後に pyannote で話者分離を行い、LLM で要約や構造化整理を行う構成にできます。

デプロイ時のすすめ方

実際に使うときは、次の順番で調整するとよいです。

まず 1 から 3 分程度の音声で、環境が正しく動くか確認する。
対象言語と実際の音質に近いサンプルで精度を確認する。
GPU メモリ使用量を見て、量子化を有効にするか決める。
長い音声は先に分割し、失敗時にすべてを再実行しなくて済むようにする。
結果は TXT と SRT の両方で保存し、後から校正しやすくする。

サーバータスクでは、リクエストごとにモデルを読み込むのではなく、サービス起動時にモデルを読み込むのがよいです。モデル読み込みには時間がかかり、頻繁に読み込むと GPU メモリ管理も不安定になりやすくなります。

まとめ

faster-whisper の価値は、Whisper を長期運用しやすい文字起こしコンポーネントにする点にあります。別のモデルに置き換えるのではなく、より効率のよい推論バックエンドとエンジニアリング向けのインターフェースを使う、という位置づけです。

個人のワークフローでは、動画、会議、講義音声をすばやくテキスト化できます。サーバー側のタスクでは、GPU、量子化、バッチ処理、VAD を組み合わせて性能を調整できます。マシン環境が正しく設定されていれば、安定した一括音声文字起こしには元の Whisper 実装より扱いやすい選択肢になります。

プロジェクト：https://github.com/SYSTRAN/faster-whisper

Google LangExtract：LLM で長文から構造化データを抽出する

Fri, 01 May 2026 02:58:21 +0800

LangExtract は、Google が公開している Python ライブラリで、非構造化テキストから構造化情報を抽出するためのものです。

使い方は分かりやすく、テキスト、プロンプト、少数の例を与えると、大規模言語モデルが定義したフィールドに従って内容を抽出し、後続処理しやすいデータとして整理します。

普通に「モデルに要約してもらう」のとは違い、LangExtract は主に 3 つの点を重視します。

固定した構造で情報を抽出する
抽出結果と原文位置の対応を保つ
長文ドキュメントと可視化チェックを支援する

レポート、論文、診療記録、契約書、ログ、Web ページなどから、エンティティ、イベント、関係、属性をよく抽出するなら、この種のツールは手書きの正規表現より柔軟で、単なるチャット型の質問より後続のデータ処理につなげやすくなります。

何を解決するのか

多くのテキスト抽出タスクは簡単そうに見えますが、実際には面倒です。

たとえば、長文から次のようなものを抽出したい場合があります。

人名、組織名、場所
イベント、時間、参加者
薬剤、投与量、副作用
製品型番、パラメーター、価格
契約条項、義務、期限
ログ内のエラー種別とコンテキスト

形式が固定されていれば、正規表現や従来のパーサーで対応できます。
しかし文章表現が少し自然になるだけで、ルールは急に複雑になります。

大規模言語モデルは自然言語の理解に向いていますが、単に「抽出して」と頼むだけでは、いくつかの問題が起きやすくなります。

出力形式が安定しない
情報が原文のどこから来たのか分からない
長文では漏れやすい
バッチ処理しにくい
人間が結果をレビューしにくい

LangExtract が解決しようとしているのはこの部分です。LLM の理解力を、より制御しやすい抽出ワークフローとして扱えるようにします。

LangExtract の特徴

1. 例で抽出形式を制約する

LangExtract は、曖昧な一文のプロンプトだけに頼るのではなく、prompt と examples を使ってモデルに次を伝えます。

何を抽出するか
フィールド名は何か
各フィールドをどう埋めるか
不確実な場合にどう扱うか

この few-shot 方式は情報抽出タスクに向いています。
例が実データに近いほど、モデルは同じ構造で安定して出力しやすくなります。

2. 抽出結果を原文へ対応付けられる

情報抽出で困るのは、「正しそうに見えるが、どこから来たのか分からない」結果です。

LangExtract の重要な点のひとつは、抽出結果と原文位置を対応付けることです。後から確認するとき、JSON の結果だけでなく、その情報が原文のどの部分に由来するのかも確認できます。

これは、医療テキスト、法律文書、研究資料、社内文書など、レビューが必要な場面で重要です。

3. 長文ドキュメントを扱える

長文の抽出では、コンテキストウィンドウ、抽出漏れ、重複抽出の問題が起きやすくなります。

LangExtract は長文向けの処理方法を提供し、ドキュメントを分割して並列処理し、抽出結果を整理できます。

そのため、短いテキスト片だけでなく、完全なレポート、論文、長い Web ページ、まとまった資料の処理にも向いています。

4. 可視化チェックを支援する

抽出結果が JSON だけだと、問題を見落としやすくなります。

LangExtract は抽出結果の可視化を支援し、モデルがどこから何を抽出したのかを直感的に確認できます。
これは prompt の調整、抽出漏れの確認、誤抽出の確認に役立ちます。

どんなときに使うべきか

LangExtract は次のような場面に向いています。

自然言語テキストから構造化フィールドを抽出したい
テキスト形式が完全には固定されていない
抽出結果と原文の対応関係を残したい
長いドキュメントを処理したい
結果に人間のレビューが必要
後続で表、データベース、データ分析に流したい

典型例は次の通りです。

医療テキストから症状、薬剤、投与量、反応を抽出する
契約書から当事者、義務、金額、期限を抽出する
論文から研究対象、方法、結論を抽出する
製品資料から仕様パラメーターを抽出する
カスタマーサポート記録から問題種別と対応結果を抽出する

短いテキストの概要を一時的に知りたいだけなら、普通のチャットモデルで十分です。
テキストを後続処理できるデータに変えたい場合は、LangExtract のほうが向いています。

基本的なインストール

プロジェクトは pip でインストールできます。

`1`	`pip install langextract`

ソースからインストールすることもできます。

1
2
3

git clone https://github.com/google/langextract.git
cd langextract
pip install -e .

モデル API を使う場合は、対応するモデルプロバイダーの API key を設定します。
プロジェクト文書では Gemini 関連の使い方が中心に紹介されており、アダプター経由で他のモデルプロバイダーにも接続できます。

基本的な使い方

典型的な流れは次のようになります。

原文テキストを準備する
抽出対象を明確に書く
少数の例を与える
LangExtract を呼び出して抽出する
構造化結果を確認する
必要なら可視化ページを生成してレビューする

特に重要なのは 2 番目と 3 番目です。

プロンプトではタスクを明確に書く必要があります。

テキスト内に明示された情報だけを抽出する
常識で補完しない
フィールドが欠けている場合は空にする
同じ種類のエンティティでは同じフィールド構造を保つ
出力に原文断片または位置を残す

例は実際の入力にできるだけ近づけるべきです。
実テキストにノイズ、略語、改行、表の残骸があるなら、例にもそれを反映するとよいです。

使うときの注意点

第一に、抽出タスクを広くしすぎないことです。

「有用な情報を抽出する」は広すぎます。
「薬剤名、投与量、投与頻度、副作用を抽出する」のように書くほうがよいです。

第二に、モデル出力を完全には信頼しないことです。

LangExtract は結果と原文を対応付けられますが、モデルが漏れや誤抽出をしないという意味ではありません。重要な場面ではサンプリング確認や人間のレビューが必要です。

第三に、長い説明より例が有効です。

情報抽出タスクでは、モデルは出力形式を理解するために例へ強く依存します。
抽象的なルールを長く書くより、高品質な example をいくつか用意するほうが有効です。

第四に、長文ではコストと速度を見ることです。

長文分割、並列抽出、モデル呼び出しにはコストがかかります。本格的なバッチ処理の前に、小さなサンプルでプロンプトとフィールド構造を調整するのがよいです。

正規表現や従来 NLP との違い

正規表現は、形式が安定しルールが明確なテキストに向いています。

従来の NLP パイプラインは、タスク境界が明確で、モデルや辞書がすでに準備されている場面に向いています。

LangExtract は、形式がそこまで固定されていないが、意味は比較的明確なテキストに向いています。
すべての表現に対してルールを書くのではなく、LLM が例から抽出対象を理解します。

ただし、正規表現の完全な代替ではありません。

固定形式のテキストでは、正規表現のほうが安価で安定している
高リスク場面では検証とレビューが必要
大規模バッチ処理ではモデル呼び出しコストを考える必要がある

現実的には、ルールが明確な部分はプログラムで処理し、意味の揺れが大きい部分を LangExtract に任せるのがよいです。

どんな開発者に向いているか

次のようなことをしているなら、LangExtract を試す価値があります。

長文を表に整理する
文書からエンティティと関係を抽出する
ナレッジベース投入前のデータクレンジングをする
業務テキストからフィールドを抽出する
LLM 駆動の情報抽出プロトタイプを作る
抽出結果と原文証拠を残したい

これは「クリックすればすべての文書を理解する」ツールではありません。LLM 抽出フローを工程化するためのライブラリに近いものです。

それでも、フィールド設計、例の作成、結果確認は必要です。
しかし毎回モデル呼び出しを書き、prompt を組み、出力を解析するより、より完整な抽出フレームワークを提供します。

参考

google/langextract

最後に

LangExtract の価値は、「LLM にテキストから情報を探させる」作業をより制御しやすくすることにあります。

気軽な要約ではなく、フィールド、根拠、レビュー要求がある情報抽出タスクに向いています。
長文を構造化データに変える仕事が多いなら、試す価値のあるツールです。

rembgプロジェクト整理：ローカル画像背景除去ツール

Sun, 19 Apr 2026 08:56:01 +0800

rembg は画像の背景を除去するツールです。コマンドラインツール、Python ライブラリ、HTTP サーバー、Docker コンテナとして使えます。役割はとても明確で、画像を入力すると、透明チャンネル付きの前景画像を出力します。商品画像、プロフィール画像、素材の一括処理、自動画像処理フローに向いています。

この種のツールの大きな利点は、ローカルで動かせることです。元画像をオンラインの背景除去サービスへアップロードしたくない場合、大量の画像を処理したい場合、背景除去をスクリプトや業務システムに組み込みたい場合、rembg はWebツールより自動化しやすい選択肢です。

01 インストール方法

現在のバージョンは Python >=3.11,<3.14 を要求します。インストール時はハードウェアに合わせてバックエンドを選びます。

`1`	`pip install "rembg[cpu]"`

CLI も必要な場合は cli を追加します。

`1`	`pip install "rembg[cpu,cli]"`

NVIDIA CUDA 環境では GPU 版をインストールできます。

`1`	`pip install "rembg[gpu,cli]"`

AMD ROCm 環境では、先に ROCm 公式手順に従って onnxruntime-rocm を入れ、その後でインストールします。

`1`	`pip install "rembg[rocm,cli]"`

GPU 版のつまずきどころは、多くの場合 rembg 本体ではなく、onnxruntime-gpu、CUDA、cuDNN、ドライバーのバージョンが合っているかです。うまく入らないときは、まず CPU 版で処理フローが動くことを確認してから GPU 環境を調整すると、無駄な遠回りを減らせます。

02 CLI サブコマンド

CLI をインストールすると、ターミナルで rembg を直接使えます。主なサブコマンドは 4 つです。

i：単一ファイルを処理する。
p：フォルダー全体を処理する。
s：HTTP サーバーを起動する。
b：RGB24 ピクセルのバイナリストリームを処理する。FFmpeg と組み合わせる場面でよく使います。

ヘルプを確認します。

1
2

rembg --help
rembg i --help

ローカル画像を1枚処理します。

`1`	`rembg i input.png output.png`

リモート画像をパイプで入力します。

`1`	`curl -s http://input.png \| rembg i > output.png`

モデルを指定します。

`1`	`rembg i -m u2netp input.png output.png`

mask だけを出力します。

`1`	`rembg i -om input.png mask.png`

alpha matting を有効にします。

`1`	`rembg i -a input.png output.png`

-a は髪の毛、細い輪郭、半透明の境界を自然にできる場合があります。ただし処理は遅くなり、すべての画像で明確に改善するわけではありません。

03 フォルダーの一括処理

一括処理は rembg の実用的な機能です。元画像を1つのディレクトリに入れ、結果を別のディレクトリへ出力できます。

`1`	`rembg p path/to/input path/to/output`

ディレクトリの変更を監視し、新規または更新された画像を自動処理します。

`1`	`rembg p -w path/to/input path/to/output`

このモードは、ダウンロードスクリプト、商品画像整理、素材フォルダーと組み合わせやすいです。たとえば処理待ち画像を input に入れると、rembg が透明 PNG を output に自動生成します。

04 Python ライブラリとして使う

自分のスクリプトに組み込むなら、もっとも簡単なのは remove を使う方法です。

from rembg import remove

with open("input.png", "rb") as i:
    with open("output.png", "wb") as o:
        input_data = i.read()
        output_data = remove(input_data)
        o.write(output_data)

PIL 画像を直接処理することもできます。

from rembg import remove
from PIL import Image

input_image = Image.open("input.png")
output_image = remove(input_image)
output_image.save("output.png")

一括処理では session を再利用し、画像ごとにモデルを初期化し直さないようにするのがおすすめです。

from pathlib import Path
from rembg import remove, new_session

session = new_session()

for file in Path("input").glob("*.png"):
    output = file.parent / f"{file.stem}.out.png"
    with open(file, "rb") as i:
        with open(output, "wb") as o:
            o.write(remove(i.read(), session=session))

長時間動く画像処理サービスを作るなら、CLI を毎回呼ぶより session を再利用するほうが向いています。

05 HTTP サーバーを起動する

rembg は HTTP サーバーとして直接起動することもできます。

`1`	`rembg s --host 0.0.0.0 --port 7000 --log_level info`

起動後は次の URL にアクセスできます。

`1`	`http://localhost:7000/api`

URL から背景を除去します。

`1`	`curl -s "http://localhost:7000/api/remove?url=http://input.png" -o output.png`

ローカル画像をアップロードします。

`1`	`curl -s -F file=@input.jpg "http://localhost:7000/api/remove" -o output.png`

API だけが必要で Gradio UI が不要なら、UI を無効にしてアイドル時の CPU 使用率を下げられます。

`1`	`rembg s --no-ui`

サーバーモードは、社内ツール、自動化フロー、ほかのアプリケーションから呼び出す用途に向いています。ただし完全な画像アセット管理システムではありません。認証、レート制限、キュー、ファイル削除などは外側で補う必要があります。

06 Docker 実行

CPU 版は公式イメージをそのまま使えます。

`1`	`docker run -v .:/data danielgatis/rembg i /data/input.png /data/output.png`

CUDA 加速にはホスト側の NVIDIA Container Toolkit が必要で、多くの場合、プロジェクト内の Dockerfile_nvidia_cuda_cudnn_gpu から自分でイメージをビルドします。

`1`	`docker build -t rembg-nvidia-cuda-cudnn-gpu -f Dockerfile_nvidia_cuda_cudnn_gpu .`

実行例です。

docker run --rm -it --gpus all \
  -v /dev/dri:/dev/dri \
  -v $PWD:/data \
  rembg-nvidia-cuda-cudnn-gpu \
  i -m birefnet-general /data/input.png /data/output.png

公式 README では、GPU イメージは CPU イメージよりかなり大きく、モデルファイルはイメージに含まれないと説明されています。モデルの再ダウンロードを避けるには、モデルディレクトリをマウントします。

`1`	`docker run -v /path/to/models:/root/.u2net ...`

07 モデル選択

rembg は初回使用時にモデルを ~/.u2net/ へ自動ダウンロードします。よく使われるモデルは次の通りです。

u2net：一般用途向けの汎用モデル。
u2netp：軽量版で、速度とサイズの面で扱いやすい。
u2net_human_seg：人物分割寄り。
u2net_cloth_seg：衣服解析寄り。
silueta：u2net に近いが、より小さい。
isnet-general-use：汎用用途向けの新しいモデル。
isnet-anime：アニメキャラクター分割寄り。
birefnet-general：README の例で汎用画像に使われているモデル。
sam：プロンプト点などの追加パラメータと組み合わせて使える。

実際の利用では、モデル名だけで決めないほうがよいです。商品画像、人物、二次元画像、複雑な背景、透明物体では求める挙動が違います。代表的な画像を何枚か選び、複数モデルで試し、輪郭、抜け、誤除去、速度を見てからデフォルトモデルを決めるのが安定します。

カスタム .onnx モデルを使う場合は、ファイルをデフォルトのモデルディレクトリ ~/.u2net/ に置き、必要に応じて次を設定します。

`1`	`MODEL_CHECKSUM_DISABLED=1`

これにより、チェックサム処理で rembg が置いたモデルファイルを上書きするのを避けられます。

08 向いている場面

rembg は次のようなタスクに向いています。

透明背景の商品画像を一括生成する。
プロフィール画像、証明写真、素材画像から前景を抽出する。
背景除去を Python スクリプトやバックエンドサービスに組み込む。
社内ネットワークに簡単な背景除去 API を置く。
FFmpeg パイプで動画フレームや連番画像を処理する。
プライバシーや素材の権利に敏感で、第三者のオンラインサービスへアップロードしたくない。

あまり向いていないのは次のような場合です。

人手レベルのエッジ修正や複雑な透明素材が必要。
すべての画像に安定した商業写真レベルの品質が必要。
背景除去だけでなく、完全なオンラインデザインツールが欲しい。
Python / Docker 環境を保守したくない。
GPU ドライバー、CUDA、ROCm 環境がすでに混乱していて、すぐ本番投入したい。

09 使い方のおすすめ

たまに画像を処理するだけなら、CPU 版で十分です。

`1`	`pip install "rembg[cpu,cli]"`

数千枚を一括処理するなら、次を優先して考えるとよいです。

Python session を再利用する。
モデルディレクトリを固定し、再ダウンロードを避ける。
入力、出力、モデルファイルは SSD に置く。
まず小さなバッチでモデル効果を試す。
その後で GPU 加速を導入するか決める。

GPU の価値は主に一括処理のスループットです。たまに1枚処理する程度なら、環境構築コストのほうが節約できる時間より高くつくことがあります。特に Windows で CUDA、cuDNN、onnxruntime-gpu のバージョンが合わない場合は、CPU 版のほうが現実的です。

10 短い判断

rembg のよいところは、シンプルで、オープンソースで、使い方の形が柔軟なことです。CLI で動き、Python から呼べて、HTTP でも使え、Docker でまとめることもできます。ローカル自動背景除去の基礎コンポーネントとして扱いやすいツールです。

ただし魔法の消しゴムではありません。複雑な背景、細かい被写体の輪郭、透明素材、影の保持、商業レベルのレタッチでは、人手や専用ワークフローが必要になることがあります。一括自動化に入れるなら、人による確認や失敗サンプルの回収手順を残しておくほうが安全です。

目的が「画像群の背景をすばやく除去し、処理をローカルに保つこと」なら、rembg はツール箱に入れておく価値があります。

codex-quota 実践ガイド：コマンドをそのまま使う Local・Web・Docker 運用

Thu, 16 Apr 2026 18:13:04 +0800

このプロジェクトは何をするか

codex-quota は ChatGPT Codex のクォータ使用状況を確認できる軽量ツールで、データ取得元は https://chatgpt.com/backend-api/wham/usage です。

主な機能：

単一アカウント・複数アカウント（account/*.auth.json）の両方に対応。
five_hour%、weekly%、weekly_reset を出力し、取得元（network / cache）も表示。
一時的な失敗（408、429、5xx）に対して指数バックオフで再試行。
ローカルキャッシュを内蔵し、クォータ枯渇時の重複リクエストを削減。
Web Dashboard、JSON API、auth ファイル管理画面を提供。

メリット：

軽量：単体スクリプトで実行でき、依存が少ない。
実用的：CLI と Web の両方の入口を使える。
配備しやすい：Docker / Docker Compose をサポート。
運用しやすい：再試行、キャッシュ、定期更新に対応。

先にアカウント認証情報を準備する

account/<name>.auth.json に認証情報ファイルを作成します。例：

{
  "tokens": {
    "access_token": "eyJ...",
    "account_id": "user-xxxxxxxx"
  }
}

説明：

access_token と account_id は API クエリに必要な項目です。
ファイル名の <name> は出力時のアカウント名として使われます。

Local CLI の使い方（元コマンドを維持）

依存をインストール：

`1`	`pip install -r requirements.txt`

説明：プロジェクトの実行依存をインストールします。

全アカウントを照会：

`1`	`python codex_quota.py`

説明：account/*.auth.json を読み込み、全アカウントのクォータを集計表示します。

単一アカウントを照会：

`1`	`python codex_quota.py your_account_name`

説明：account/your_account_name.auth.json のみを照会します。

強制更新（キャッシュ無視）：

`1`	`python codex_quota.py --refresh`

説明：ローカルキャッシュを無視して最新データを直接取得します。

CLI オプション説明（README 準拠）

account_name：任意のアカウント名（.auth.json なし）。
--account-dir：認証ファイルディレクトリ。デフォルトは account。
--chatgpt-url：クォータ API エンドポイント。
--raw-json：JSON レスポンス本文をそのまま表示。
--raw-headers：レスポンスヘッダーを表示。
--refresh：キャッシュを無視。
--retries：再試行回数。デフォルト 3。
--retry-delay：再試行の基本待機秒数。デフォルト 2.0。

Web Dashboard の使い方（元コマンドを維持）

サービス起動：

`1`	`python codex_quota_service.py --host 0.0.0.0 --port 8081`

説明：8081 ポートで HTTP サービスを起動します。

アクセス URL：http://localhost:8081

Service オプション：

--host：バインドアドレス。デフォルト 0.0.0.0。
--port：ポート。デフォルト 8081。
--interval-seconds：定期更新間隔。デフォルト 3600。
--account-dir：認証ファイルディレクトリ。デフォルト account。
--state-file：状態ファイルパス。デフォルト <account-dir>/codex_quota_web_results.json。
--account-name：任意。単一アカウントモード。
--chatgpt-url：クォータ API エンドポイント。
--retries：再試行回数。
--retry-delay：再試行の基本待機。
--refresh：定期実行時に CLI キャッシュを無視。

HTTP エンドポイント（自動化向け）

GET /：Dashboard 画面。
GET /api/results：最新結果の JSON。
GET /refresh：即時更新して / にリダイレクト。
GET /auth：auth ファイル一覧。
GET /auth/new：auth ファイル新規作成フォーム。
GET /auth/edit?name=<account>：auth ファイル編集フォーム。
POST /auth/save：auth ファイル作成/更新。
POST /auth/delete：auth ファイル削除。

Docker の使い方（元コマンドを維持）

イメージをビルド：

`1`	`docker build -t codex-quota .`

説明：現在のプロジェクトを codex-quota イメージとしてビルドします。

コンテナ起動（8081 をマッピング）：

`1`	`docker run --rm -p 8081:8081 -v ./account:/app/account codex-quota`

説明：

--rm：終了後にコンテナを自動削除。
-p 8081:8081：ホストポートをコンテナポートへマッピング。
-v ./account:/app/account：ローカル認証ディレクトリをコンテナにマウント。

アクセス URL：http://localhost:8081

Docker Compose の使い方（元コマンドを維持）

起動：

`1`	`docker compose up --build`

説明：docker-compose.yml に従ってビルド・起動します。

アクセス URL：http://localhost:8081

運用のヒント

複数アカウント運用では、まず Dashboard で一元管理するのがおすすめです。
通知や自動連携には GET /api/results を優先すると扱いやすいです。
公開リポジトリに実際の access_token をコミットしないでください。
一時エラーが多い場合は --retries と --retry-delay を増やしてください。

Codex クォータ使用統計

Sun, 12 Apr 2026 00:01:33 +0800

現在の Codex アカウントの残高を確認したい場合は、ChatGPT の /backend-api/wham/usage インターフェイスを要求する小さなスクリプトを直接作成できます。

このタイプのスクリプトの考え方は非常にシンプルです。

auth.json から tokens.access_token および tokens.account_id を読み取ります
リクエスト https://chatgpt.com/backend-api/wham/usage
リクエストヘッダーに Authorization: Bearer ... と ChatGPT-Account-Id を含めます
返された結果の 5 時間のウィンドウと週ごとのウィンドウクォータを解析します。

やるべきことに適した

この方法は、ローカルですばやく確認するのに適しています。

5 時間の割り当てはどれくらい残っていますか?
週の割り当てはどれくらい残っていますか?
クォータはいつリセットされますか?

複数のアカウントをお持ちの場合は、スクリプトで account/*.auth.json を一括で読み込み、一律に集計表を出力することもできます。 auth.json ファイルは、現在ログインしている chatgpt アカウントに対応する ~/.codex/ ディレクトリにあります。

最も重要なインプット

通常、スクリプトは次の 2 つの資格情報のみに依存します。

access_token
account_id

これらは通常、ローカルの auth.json から入手できます。これら 2 つの値が有効である限り、リクエストヘッダーは次のように構成できます。

headers = {
    "Authorization": f"Bearer {auth_token}",
    "Accept": "application/json",
    "ChatGPT-Account-Id": auth_account_id,
    "Origin": "https://chatgpt.com",
    "Referer": "https://chatgpt.com/",
    "User-Agent": "Mozilla/5.0",
}

返された結果の見方

インターフェイスが戻った後は、次の 2 種類のウィンドウに焦点が当てられます。

five_hour
weekly

スクリプトはそれらを次の項目に整理できます。

残高の割合
リセット時間
対応する時間ウィンドウの長さ

インターフェイスフィールド名が異なる場合、バリアント primary_window、secondary_window、five_hour_limit、および weekly_limit とも互換性がある可能性があります。

よくある質問

スクリプトが 401 を返した場合、通常、access_token の有効期限が切れているか、無効であることを意味します。

403 が返された場合は、通常、現在のアカウントにこのインターフェイスにアクセスする権限がないか、アカウントのステータスが異常であることを意味します。

同じ応答内でフィールドの名前が一貫していない場合でも驚かないでください。実際の処理では、異なる命名方法を統一的にマッピングしてから出力するのがベストです。

参考リンク

codex-auth-manager：https://github.com/RioArisk/codex-auth-manager

コード

import argparse
import base64
import json
import os
import sys
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any

import requests


UTC = timezone.utc
CST = timezone(timedelta(hours=8), name="CST")
JSONDict = dict[str, Any]


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Query ChatGPT Codex usage from /backend-api/wham/usage."
    )
    parser.add_argument(
        "account_name",
        nargs="?",
        help="Account name used to load account/<account_name>.auth.json. If omitted, load all *.auth.json files in account/.",
    )
    parser.add_argument(
        "--account-dir",
        default="account",
        help="Directory containing <account_name>.auth.json files.",
    )
    parser.add_argument(
        "--chatgpt-url",
        default="https://chatgpt.com/backend-api/wham/usage",
        help="ChatGPT usage endpoint.",
    )
    parser.add_argument(
        "--raw-json",
        action="store_true",
        help="Print the full JSON response body.",
    )
    parser.add_argument(
        "--raw-headers",
        action="store_true",
        help="Print response headers.",
    )
    return parser.parse_args()


def print_json(data: Any) -> None:
    print(json.dumps(data, indent=2, ensure_ascii=False))


def load_auth_json(path_str: str | Path | None) -> JSONDict | None:
    if not path_str:
        return None
    path = Path(path_str).expanduser()
    if not path.is_file():
        return None
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError):
        return None


def get_nested_string(data: JSONDict | None, *keys: str) -> str | None:
    current: Any = data
    for key in keys:
        if not isinstance(current, dict):
            return None
        current = current.get(key)
    return current if isinstance(current, str) and current else None


def format_dt(dt: datetime | None) -> str:
    if dt is None:
        return "-"
    return dt.astimezone(CST).strftime("%Y-%m-%d %H:%M:%S %Z")


def format_cst(dt: datetime | None) -> str:
    return format_dt(dt)


def epoch_ms_to_dt(value: Any) -> datetime | None:
    if value is None:
        return None
    try:
        raw = int(value)
    except (TypeError, ValueError):
        return None
    # Newer responses sometimes use epoch seconds, older ones use epoch milliseconds.
    timestamp = raw / 1000 if raw > 10**11 else raw
    return datetime.fromtimestamp(timestamp, tz=UTC)


def first_dict(data: Any, *keys: str) -> JSONDict | None:
    for key in keys:
        value = data.get(key) if isinstance(data, dict) else None
        if isinstance(value, dict):
            return value
    return None


def decode_jwt_exp(token: str) -> datetime | None:
    parts = token.split(".")
    if len(parts) != 3:
        return None
    try:
        payload = parts[1]
        payload += "=" * (-len(payload) % 4)
        data = json.loads(base64.urlsafe_b64decode(payload.encode("ascii")))
        exp = data.get("exp")
        if exp is None:
            return None
        return datetime.fromtimestamp(int(exp), tz=UTC)
    except (ValueError, TypeError, json.JSONDecodeError):
        return None


def get_percent_left(value: JSONDict) -> float | int | None:
    percent_left = value.get("percent_left")
    if percent_left is None:
        percent_left = value.get("remaining_percent")
    if percent_left is not None:
        return percent_left

    used_percent = value.get("used_percent")
    try:
        if used_percent is not None:
            return max(0, 100 - float(used_percent))
    except (TypeError, ValueError):
        return None
    return None


def resolve_limit_window(value: JSONDict) -> JSONDict:
    if (
        "reset_at" not in value
        and "reset_time_ms" not in value
        and isinstance(value.get("primary_window"), dict)
    ):
        return value["primary_window"]
    return value


def parse_limit_entry(name: str, value: Any) -> JSONDict | None:
    if not isinstance(value, dict):
        return None

    value = resolve_limit_window(value)

    percent_left = get_percent_left(value)
    reset_time_ms = value.get("reset_time_ms")
    if reset_time_ms is None:
        reset_time_ms = value.get("reset_at")

    window_seconds = value.get("limit_window_seconds")

    return {
        "name": name,
        "percent_left": percent_left,
        "reset_time_ms": reset_time_ms,
        "reset_at": epoch_ms_to_dt(reset_time_ms),
        "limit_window_seconds": window_seconds,
    }


def infer_limit_name(window_seconds: Any) -> str | None:
    if not isinstance(window_seconds, (int, float)):
        return None
    if window_seconds <= 6 * 3600:
        return "five_hour"
    if window_seconds >= 6 * 24 * 3600:
        return "weekly"
    return None


def relabel_rate_limits(primary: JSONDict | None, secondary: JSONDict | None) -> tuple[JSONDict | None, JSONDict | None]:
    for entry in (primary, secondary):
        if not entry:
            continue
        inferred_name = infer_limit_name(entry.get("limit_window_seconds"))
        if inferred_name:
            entry["name"] = inferred_name

    if primary and secondary and primary.get("name") == secondary.get("name"):
        if primary.get("name") == "weekly":
            primary["name"] = "five_hour"
        else:
            secondary["name"] = "weekly"

    if primary and primary.get("name") == "weekly" and secondary is None:
        return None, primary

    if secondary and secondary.get("name") == "five_hour" and primary is None:
        return secondary, None

    return primary, secondary


def parse_rate_limits(data: JSONDict) -> tuple[JSONDict | None, JSONDict | None]:
    primary = None
    secondary = None

    for primary_key in ("five_hour", "five_hour_limit", "five_hour_rate_limit", "primary"):
        if primary_key in data:
            primary = parse_limit_entry("five_hour", data.get(primary_key))
            if primary:
                break

    for secondary_key in ("weekly", "weekly_limit", "weekly_rate_limit", "secondary"):
        if secondary_key in data:
            secondary = parse_limit_entry("weekly", data.get(secondary_key))
            if secondary:
                break

    if primary is None:
        primary = parse_limit_entry("five_hour", data.get("primary_window"))
    if secondary is None:
        secondary = parse_limit_entry("weekly", data.get("secondary_window"))

    return relabel_rate_limits(primary, secondary)


def format_percent(value: Any) -> str:
    return f"{value:g}" if isinstance(value, (int, float)) else str(value if value is not None else "-")


def percent_sort_value(value: Any, descending: bool) -> tuple[int, float]:
    if isinstance(value, (int, float)):
        numeric_value = float(value)
        return (0, -numeric_value if descending else numeric_value)
    return (1, 0.0)


def get_auth_paths(account_dir: str, account_name: str | None) -> list[Path]:
    base_dir = Path(account_dir)
    if account_name:
        return [base_dir / f"{account_name}.auth.json"]
    return sorted(base_dir.glob("*.auth.json"))


def get_account_name_from_path(path: Path) -> str:
    suffix = ".auth.json"
    return path.name[: -len(suffix)] if path.name.endswith(suffix) else path.stem


def build_summary_row(account_name: str, five_hour: JSONDict | None, weekly: JSONDict | None) -> JSONDict:
    return {
        "account": account_name,
        "five_hour_percent": five_hour["percent_left"] if five_hour else None,
        "weekly_percent": weekly["percent_left"] if weekly else None,
        "weekly_reset_at": weekly["reset_at"] if weekly else None,
    }


def print_summary_rows(rows: list[JSONDict]) -> None:
    if not rows:
        return

    sorted_rows = sorted(
        rows,
        key=lambda row: (
            percent_sort_value(row.get("five_hour_percent"), descending=True),
            percent_sort_value(row.get("weekly_percent"), descending=True),
            format_cst(row.get("weekly_reset_at")),
            row["account"],
        ),
    )

    display_rows = []
    for row in sorted_rows:
        display_rows.append(
            {
                "account": str(row["account"]),
                "five_hour": format_percent(row.get("five_hour_percent")),
                "weekly": format_percent(row.get("weekly_percent")),
                "weekly_reset": format_cst(row.get("weekly_reset_at")),
            }
        )

    headers = {
        "account": "account",
        "five_hour": "five_hour%",
        "weekly": "weekly%",
        "weekly_reset": "weekly_reset",
    }
    widths = {
        key: max(len(headers[key]), max(len(item[key]) for item in display_rows))
        for key in headers
    }

    print(
        f"{headers['account']:<{widths['account']}}  "
        f"{headers['five_hour']:>{widths['five_hour']}}  "
        f"{headers['weekly']:>{widths['weekly']}}  "
        f"{headers['weekly_reset']:<{widths['weekly_reset']}}"
    )
    for item in display_rows:
        print(
            f"{item['account']:<{widths['account']}}  "
            f"{item['five_hour']:>{widths['five_hour']}}  "
            f"{item['weekly']:>{widths['weekly']}}  "
            f"{item['weekly_reset']:<{widths['weekly_reset']}}"
        )


def validate_token_inputs(
    token: str,
    account_id: str,
    auth_token: str | None,
    auth_account_id: str | None,
) -> int | None:
    if token.startswith("sess-"):
        print("status: invalid_token_type", file=sys.stderr)
        print(
            "message: --chatgpt-token looks like a session token (sess-...). Use the JWT access_token instead.",
            file=sys.stderr,
        )
        if auth_token:
            print(
                "hint: Found tokens.access_token in auth.json; omit --chatgpt-token or pass that value instead.",
                file=sys.stderr,
            )
        return 1

    token_exp = decode_jwt_exp(token)
    if token_exp is not None and token_exp <= datetime.now(UTC):
        print("status: expired", file=sys.stderr)
        print(f"message: access_token expired at {format_dt(token_exp)}", file=sys.stderr)
        if auth_token and auth_token != token:
            auth_token_exp = decode_jwt_exp(auth_token)
            hint = format_dt(auth_token_exp) if auth_token_exp else "unknown time"
            print(f"hint: auth.json contains a different access_token expiring at {hint}", file=sys.stderr)
        return 1

    if auth_account_id and account_id != auth_account_id:
        print("warning: supplied --account-id does not match auth.json tokens.account_id", file=sys.stderr)

    return None


def handle_error_response(response: requests.Response, data: Any, raw_json: bool) -> int | None:
    if response.status_code == 401:
        print("status: expired", file=sys.stderr)
        print("message: Token 已过期或无效", file=sys.stderr)
        if raw_json:
            print_json(data)
        return 3

    if response.status_code == 403:
        print("status: forbidden", file=sys.stderr)
        print("message: 账号已被封禁或无权访问", file=sys.stderr)
        if raw_json:
            print_json(data)
        return 3

    if response.status_code >= 400:
        print(f"HTTP {response.status_code}", file=sys.stderr)
        print_json(data)
        return 3

    return None


def fetch_chatgpt_usage(auth_path: Path, args: argparse.Namespace) -> tuple[int, JSONDict | None]:
    auth_data = load_auth_json(auth_path)
    account_name = get_account_name_from_path(auth_path)
    auth_token = get_nested_string(auth_data, "tokens", "access_token")
    auth_account_id = get_nested_string(auth_data, "tokens", "account_id")

    if not auth_data:
        print(f"{account_name}: auth file not found or invalid", file=sys.stderr)
        return 1, None

    if not auth_token:
        print(f"{account_name}: missing access_token", file=sys.stderr)
        return 1, None

    if not auth_account_id:
        print(f"{account_name}: missing account_id", file=sys.stderr)
        return 1, None

    validation_error = validate_token_inputs(
        auth_token,
        auth_account_id,
        auth_token,
        auth_account_id,
    )
    if validation_error is not None:
        return validation_error, None

    headers = {
        "Authorization": f"Bearer {auth_token}",
        "Accept": "application/json",
        "ChatGPT-Account-Id": auth_account_id,
        "Origin": "https://chatgpt.com",
        "Referer": "https://chatgpt.com/",
        "User-Agent": "Mozilla/5.0",
    }

    try:
        response = requests.get(args.chatgpt_url, headers=headers, timeout=60)
    except requests.RequestException as exc:
        print(f"Request failed: {exc}", file=sys.stderr)
        return 2, None

    if args.raw_headers:
        print("=== Headers ===")
        print_json(dict(response.headers))
        print()

    try:
        data = response.json()
    except ValueError:
        print(f"HTTP {response.status_code}", file=sys.stderr)
        print(response.text, file=sys.stderr)
        return 3, None

    error_response = handle_error_response(response, data, args.raw_json)
    if error_response is not None:
        return error_response, None

    if args.raw_json:
        print("=== Raw JSON ===")
        print_json(data)
        print()

    rate_limits = first_dict(data, "rate_limit", "rate_limits")

    if rate_limits is None:
        return 0, build_summary_row(account_name, None, None)

    five_hour, weekly = parse_rate_limits(rate_limits)
    return 0, build_summary_row(account_name, five_hour, weekly)


def main() -> None:
    args = parse_args()
    auth_paths = get_auth_paths(args.account_dir, args.account_name)
    if not auth_paths:
        print("No auth files found.", file=sys.stderr)
        sys.exit(1)

    exit_code = 0
    summary_rows: list[JSONDict] = []
    for auth_path in auth_paths:
        current_exit_code, summary_row = fetch_chatgpt_usage(auth_path, args)
        exit_code = max(exit_code, current_exit_code)
        if summary_row is not None and not args.raw_json:
            summary_rows.append(summary_row)

    if summary_rows:
        print_summary_rows(summary_rows)
    sys.exit(exit_code)


if __name__ == "__main__":
    main()

eコマース商品画像の切り抜きと標準化されたエージェントスキルを共有する

Thu, 09 Apr 2026 21:43:50 +0800

product-cutout-normalize は、商品画像に使用されるエージェントスキルです。

元画像を統一仕様の下透明正方形画像に加工します。デフォルトのルールは次のとおりです。

1024x1024 キャンバス
透明な背景
件名は可能な限り完全なものにしてください
縦長の被写体を横長に自動変換
センターボディ
メインの表示幅は820pxに統一

電子商取引資料、製品ライブラリ、詳細ページの画像の前処理に適しています。

このスキルはどのような問題を解決しますか?

多くの製品画像には、基本的な切り抜き後も次の問題が発生します。

白い枠または薄い灰色の背景が残る
被写体の水平方向と垂直方向が一致しない
キャンバスのサイズが不安定です
被写体のサイズは大きいものから小さいものまでさまざまです
透明部分に小さなノイズがある

このスキルは一定のプロセスに従って処理されます。

ジェミニのカットアウト
明るい背景のエッジをクリーンアップ
ノイズの小さな断片を除去する
縦長画像を横長画像に変換
ターゲットの幅に合わせて拡大縮小する
均一なサイズの透明なキャンバスの中央に配置します。

この方法でエクスポートされた画像はよりきれいになり、バッチ使用に適しています。

該当するシナリオ

以下のニーズに適しています。

商品写真をバッチ処理する
下透過PNGの統合出力
メインビジュアルのサイズを統一する
安定した反復可能な処理手順が必要

少数の画像のみを扱う場合、または各画像のレイアウトを個別に調整する必要がある場合には、これは適さない可能性があります。

クイックスタート

最も直接的な実行方法:

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite`

実行前に必須:

GEMINI_API_KEY
google-genai
Pillow

依存関係をインストールします。

`1`	`.\.venv\Scripts\python.exe -m pip install google-genai pillow`

環境変数を設定します。

`1`	`$env:GEMINI_API_KEY="your_api_key"`

出力ルール

デフォルトの出力:

透明な背景 PNG
1024x1024 キャンバス
身幅820px
センターボディ
小さなノイズもクリーンアップされます

つまり、これは単なるスクリプトの暗記ではなく、製品イメージを整理するスクリプトのようなものです。

主なパラメータの説明

一般的に使用されるパラメータ:

--model デフォルト gemini-2.5-flash-image
--canvas-size 出力正方形キャンバスサイズ、デフォルト 1024
--target-width 本体の表示幅、デフォルトは 820
--min-component-pixels このピクセル数より小さい透明なフラグメントは削除されます (デフォルトは 500)
--overwrite 出力ファイルがすでに存在する場合は、出力ファイルを直接上書きします

例えば：

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" ".\input" ".\output" --canvas-size 1280 --target-width 960 --overwrite`

処理の流れ

処理フローは簡単です。

ジェミニのカットアウト
明るい背景のエッジをクリーンアップ
ノイズの小さな断片を除去する
縦長画像を横長画像に変換
ターゲットの幅に合わせて拡大縮小する
均一なサイズの透明なキャンバスの中央に配置します。

通常の切り抜きスクリプトとの違い

通常の暗記スクリプトと比較して、次の問題もさらに処理します。

主な方向性は統一されています
均一なボディサイズ
均一なキャンバスサイズ
小さな破片やノイズのクリーンアップ
結果はマテリアルライブラリに直接入れるのに適しています。

SKILL.md ソースコード

SKILL.md の完全なソースコードは以下に保持されており、内容は変更されていません。

---
name: product-cutout-normalize
description: Run a reusable Gemini product-image pipeline that removes backgrounds, preserves the full subject, rotates tall products to a horizontal orientation, centers them on a 1024x1024 transparent canvas, and normalizes the visible subject width to 820px. Use when the user wants a repeatable cutout-and-normalize workflow for product photos or asks to batch-process product images into standardized square PNG assets.
---

# Product Cutout Normalize

Use this skill when product photos need the same deterministic finishing pipeline:

- Gemini cutout from the original photo
- border cleanup to transparent
- preserve the full subject
- rotate to horizontal when the subject is taller than it is wide
- center on a `1024x1024` transparent canvas
- normalize the visible subject width to `820px`

## Quick Start

Run the bundled script:

```powershell
& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite
```

Required environment:

- `GEMINI_API_KEY`
- `google-genai`
- `Pillow`

## Workflow

1. Confirm the request matches this standard pipeline. If the user asks for a different canvas size, subject width, or layout rule, pass explicit flags instead of changing the script.
2. Run the bundled script on the input directory.
3. If a result looks misaligned, inspect the alpha bounding box and small detached artifacts first; this pipeline already removes tiny alpha components by default.
4. Report the exact input and output directories used, plus any non-default flags.

## Script

Primary entry point:

- `scripts/run_pipeline.py`

Key flags:

- `--model`: Gemini image model, default `gemini-2.5-flash-image`
- `--canvas-size`: output square size, default `1024`
- `--target-width`: visible subject width after normalization, default `820`
- `--min-component-pixels`: remove detached alpha specks smaller than this, default `500`
- `--overwrite`: replace existing outputs in the destination directory

## Repo Integration

If the current project already has [`scripts/nano_banana_cutout.py`](/c:/Work/my_shop/scripts/nano_banana_cutout.py), prefer that repo script when the user wants the same pipeline inside this repository. Use the bundled skill script when the task is cross-project reuse or when you want the workflow to stay self-contained inside the skill.

スクリプト/run_pipeline.py ソースコード

scripts/run_pipeline.py の完全なソースコードは以下に保持されており、内容は変更されていません。

from __future__ import annotations

import argparse
import os
from collections import deque
from pathlib import Path

from PIL import Image

try:
    from google import genai
except ImportError as exc:  # pragma: no cover
    raise SystemExit(
        "Missing dependency: google-genai. Install it with "
        r"'.\.venv\Scripts\python.exe -m pip install google-genai'."
    ) from exc


PROMPT = (
    "Remove the entire background from this product photo and return only the product "
    "on a fully transparent background as a PNG. Keep the full product intact, preserve "
    "thin cable details, clean the inner loops and holes, and do not add any new objects "
    "or shadows."
)
DEFAULT_CANVAS_SIZE = 1024
DEFAULT_TARGET_WIDTH = 820
DEFAULT_MIN_COMPONENT_PIXELS = 500
SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp"}


def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35


def to_pil_image(image_obj) -> Image.Image:
    if isinstance(image_obj, Image.Image):
        return image_obj
    pil_image = getattr(image_obj, "_pil_image", None)
    if isinstance(pil_image, Image.Image):
        return pil_image
    as_pil = getattr(image_obj, "pil_image", None)
    if isinstance(as_pil, Image.Image):
        return as_pil
    raise TypeError(f"Unsupported image object type: {type(image_obj)!r}")


def make_transparent_from_borders(image: Image.Image) -> Image.Image:
    rgba = image.convert("RGBA")
    width, height = rgba.size
    pixels = rgba.load()

    visited: set[tuple[int, int]] = set()
    queue: deque[tuple[int, int]] = deque()

    def push_if_bg(x: int, y: int) -> None:
        if (x, y) in visited:
            return
        r, g, b, _ = pixels[x, y]
        if is_light_background_pixel(r, g, b):
            visited.add((x, y))
            queue.append((x, y))

    for x in range(width):
        push_if_bg(x, 0)
        push_if_bg(x, height - 1)
    for y in range(height):
        push_if_bg(0, y)
        push_if_bg(width - 1, y)

    while queue:
        x, y = queue.popleft()
        for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
            if 0 <= nx < width and 0 <= ny < height:
                push_if_bg(nx, ny)

    for x, y in visited:
        pixels[x, y] = (0, 0, 0, 0)

    return rgba


def remove_small_components(image: Image.Image, min_component_pixels: int) -> Image.Image:
    if min_component_pixels <= 0:
        return image

    rgba = image.convert("RGBA")
    alpha = rgba.getchannel("A")
    width, height = rgba.size
    alpha_pixels = alpha.load()
    rgba_pixels = rgba.load()
    visited: set[tuple[int, int]] = set()

    for y in range(height):
        for x in range(width):
            if alpha_pixels[x, y] == 0 or (x, y) in visited:
                continue

            queue: deque[tuple[int, int]] = deque([(x, y)])
            visited.add((x, y))
            component: list[tuple[int, int]] = []

            while queue:
                cx, cy = queue.popleft()
                component.append((cx, cy))
                for nx, ny in ((cx - 1, cy), (cx + 1, cy), (cx, cy - 1), (cx, cy + 1)):
                    if 0 <= nx < width and 0 <= ny < height:
                        if alpha_pixels[nx, ny] == 0 or (nx, ny) in visited:
                            continue
                        visited.add((nx, ny))
                        queue.append((nx, ny))

            if len(component) < min_component_pixels:
                for px, py in component:
                    r, g, b, _ = rgba_pixels[px, py]
                    rgba_pixels[px, py] = (r, g, b, 0)

    return rgba


def normalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
) -> Image.Image:
    rgba = image.convert("RGBA")
    bbox = rgba.getchannel("A").getbbox()
    if bbox is None:
        return Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))

    subject = rgba.crop(bbox)
    if subject.height > subject.width:
        subject = subject.rotate(-90, expand=True, resample=Image.Resampling.BICUBIC)
        rotated_bbox = subject.getchannel("A").getbbox()
        if rotated_bbox is not None:
            subject = subject.crop(rotated_bbox)

    scale = target_width / subject.width
    subject = subject.resize(
        (target_width, max(1, int(round(subject.height * scale)))),
        Image.Resampling.LANCZOS,
    )

    canvas = Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))
    offset_x = (canvas_size - subject.width) // 2
    offset_y = (canvas_size - subject.height) // 2
    canvas.alpha_composite(subject, (offset_x, offset_y))
    return canvas


def finalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> Image.Image:
    transparent = make_transparent_from_borders(image)
    cleaned = remove_small_components(transparent, min_component_pixels)
    return normalize_product_image(cleaned, canvas_size=canvas_size, target_width=target_width)


def save_first_image_part(
    response,
    dst: Path,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    parts = getattr(response, "parts", None)
    if parts is None and getattr(response, "candidates", None):
        parts = response.candidates[0].content.parts

    if not parts:
        raise RuntimeError("Model returned no content parts.")

    for part in parts:
        inline_data = getattr(part, "inline_data", None)
        if inline_data is None and isinstance(part, dict):
            inline_data = part.get("inline_data")

        if inline_data is None:
            continue

        if hasattr(part, "as_image"):
            image = to_pil_image(part.as_image())
            dst.parent.mkdir(parents=True, exist_ok=True)
            finalize_product_image(
                image,
                canvas_size=canvas_size,
                target_width=target_width,
                min_component_pixels=min_component_pixels,
            ).save(dst)
            return

        data = getattr(inline_data, "data", None)
        if data:
            dst.parent.mkdir(parents=True, exist_ok=True)
            with open(dst, "wb") as handle:
                handle.write(data)
            with Image.open(dst) as image:
                processed = finalize_product_image(
                    image,
                    canvas_size=canvas_size,
                    target_width=target_width,
                    min_component_pixels=min_component_pixels,
                )
                processed.save(dst.with_suffix(".png"))
            if dst.suffix.lower() != ".png":
                dst.unlink(missing_ok=True)
            return

    raise RuntimeError("Model returned text only and no edited image.")


def process_image(
    src: Path,
    dst: Path,
    client,
    model: str,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    with Image.open(src).convert("RGBA") as image:
        response = client.models.generate_content(
            model=model,
            contents=[PROMPT, image],
        )

    save_first_image_part(
        response,
        dst,
        canvas_size=canvas_size,
        target_width=target_width,
        min_component_pixels=min_component_pixels,
    )


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Cut out product images with Gemini and normalize them to square transparent PNGs."
    )
    parser.add_argument("input_dir", type=Path)
    parser.add_argument("output_dir", type=Path)
    parser.add_argument("--model", default="gemini-2.5-flash-image")
    parser.add_argument("--canvas-size", type=int, default=DEFAULT_CANVAS_SIZE)
    parser.add_argument("--target-width", type=int, default=DEFAULT_TARGET_WIDTH)
    parser.add_argument("--min-component-pixels", type=int, default=DEFAULT_MIN_COMPONENT_PIXELS)
    parser.add_argument("--overwrite", action="store_true")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise SystemExit("Missing GEMINI_API_KEY environment variable.")
    if not args.input_dir.is_dir():
        raise SystemExit(f"Input directory does not exist: {args.input_dir}")
    if args.canvas_size <= 0:
        raise SystemExit("--canvas-size must be positive.")
    if args.target_width <= 0 or args.target_width > args.canvas_size:
        raise SystemExit("--target-width must be positive and no larger than --canvas-size.")
    if args.min_component_pixels < 0:
        raise SystemExit("--min-component-pixels must be >= 0.")

    args.output_dir.mkdir(parents=True, exist_ok=True)
    client = genai.Client(api_key=api_key)

    for src in sorted(args.input_dir.iterdir()):
        if not src.is_file() or src.suffix.lower() not in SUPPORTED_EXTENSIONS:
            continue
        dst = args.output_dir / f"{src.stem}.png"
        if dst.exists() and not args.overwrite:
            print(f"skip {dst}")
            continue
        process_image(
            src,
            dst,
            client,
            args.model,
            canvas_size=args.canvas_size,
            target_width=args.target_width,
            min_component_pixels=args.min_component_pixels,
        )
        print(dst)


if __name__ == "__main__":
    main()

添付ファイルをダウンロード: product-cutout-normalize.7z

Google Nano Bananaを呼び出して画像を切り出す方法

Thu, 09 Apr 2026 20:10:48 +0800

この記事では、実用的な Python スクリプトを使用して、Google の Nano Banana 画像編集機能を呼び出して商品画像を切り出す方法を示します。

この現在の実装の目標は明確です。

カタログから製品画像を読み取る
Google 画像モデルを呼び出して背景の削除を実行します。
返された画像に対してローカルの透明な背景のクリーニングを再度実行します
最終出力は透明な下部 PNG

白い背景の製品画像、ヘッドフォンの画像、および配線図面のバッチがすでにあり、電子商取引で使用できる透明な背景画像をすばやく生成したい場合、この方法は非常に簡単です。

このコードは何をするのか

このスクリプトは主に 4 つの部分に分かれています。

「背景を削除し、被写体を保持し、影を追加しない」ことをモデルに知らせるプロンプトワードを定義します。
google-genai の画像生成インターフェイスを呼び出します。
モデル応答から画像結果を抽出する
次に、ローカルロジックを使用してエッジの明るい背景を透明に変換し、残留エッジを減らします。

つまり、単にモデルに画像を投げただけでは終わりではなく、「モデル編集＋ローカル後処理」を繋ぎ合わせて完成するのです。

走る前の準備

最初に依存関係をインストールします。

`1`	`.\.venv\Scripts\python.exe -m pip install google-genai pillow`

GEMINI_API_KEYの取得方法

GEMINI_API_KEY は、Gemini API を呼び出すときに使用されるキーです。 Google の公式クイックスタートによると、キーをまだ持っていない場合は、Google AI Studio で直接作成できます。

入手手順は以下の通りです。

Google AIスタジオを開きます。
Google アカウントにサインインします。
Get API key または API keys ページを見つけます。
新しい API キーを作成します。
生成されたキーをコピーします。
スクリプトが読み取ることができるように、これをローカル環境変数に構成します。

ページ上に使用可能なプロジェクトがない場合は、通常、最初にプロジェクトの初期化を完了してから、[API キー] ページに戻ってキーを作成する必要があります。

キーを取得したら、環境変数を構成します。

`1`	`$env:GEMINI_API_KEY="your_api_key"`

cmd を使用している場合は、次のように記述できます。

`1`	`set GEMINI_API_KEY=your_api_key`

GEMINI_API_KEY と GOOGLE_API_KEY を同時に設定した場合、実際の動作では通常 GOOGLE_API_KEY が最初に読み込まれるため、混乱を避けるために 1 つだけを保持することをお勧めします。

ディレクトリ構造の例

スクリプトは 2 つのパラメータを受け取ります。

input_dir: 画像ディレクトリに入る
output_dir: 出力画像ディレクトリ

例えば：

images/
  product1.jpg
  product2.png

output/

走り方

スクリプトファイル名がcutout.pyで、実行方法が次のとおりであるとします。

`1`	`.\.venv\Scripts\python.exe .\cutout.py .\images .\output`

モデルを変更したい場合は、パラメーターを明示的に渡すこともできます。

`1`	`.\.venv\Scripts\python.exe .\cutout.py .\images .\output --model gemini-2.5-flash-image`

スクリプトは、入力ディレクトリ内のファイルを次の形式でループします。

.jpg
.jpeg
.png
.webp

処理が完了すると、同じ名前の透過的な PNG ファイルが出力ディレクトリに生成されます。

コア呼び出しプロセス

実際に Google Nano Banana を呼び出すキーコードは次のとおりです。

response = client.models.generate_content(
    model=model,
    contents=[PROMPT, image],
)

ここでは 2 つのコンテンツが渡されます。

テキストプロンプトの単語 PROMPT
ワンピース PIL.Image

プロンプトの内容は、製品画像全体の背景を削除し、本体のみを残し、いくつかの点を強調するようモデルに依頼することです。

完全な製品を保管する
細いワイヤーとケーブルの詳細を保持
内部の空洞と環状領域をきれいにします
新しいオブジェクトを追加しないでください
影を追加しないでください

この種のプロンプトワードは、カットアウトの品質、特にヘッドフォンケーブル、透明なエッジ、中空領域などの細部に大きな影響を与えます。

なぜローカルで後処理を行う必要があるのでしょうか?

モデルが結果を返した後、スクリプトは直接保存されませんが、make_transparent_from_borders(image) が再度実行されます。

このステップの考え方は次のとおりです。

画像の周囲のエッジから始まる明るい背景ピクセルを見つけます
幅優先検索を使用して、接続されているすべての明るい色の領域をマークします。
最後に、これらの領域を透明に変更します。

これを行う利点は、残っている白いエッジ、明るい灰色の背景、および不十分にきれいなエッジ領域をさらに除去できることです。

「背景かどうか」の判断条件は以下の通りです。

def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35

簡単な理解は次のとおりです。

全体的に色が明るいので
3 つの RGB チャネルの差が大きすぎることはありません

商品画像の背景が白地やライトグレー地、単色に近いものを加工する場合に適しています。

完全なソースコード

現在の完全なソースコードは、直接の再利用や二次的な変更を容易にするために以下に保持されています。

from __future__ import annotations

import argparse
import os
from pathlib import Path
from collections import deque

from PIL import Image

try:
    from google import genai
except ImportError as exc:  # pragma: no cover
    raise SystemExit(
        "Missing dependency: google-genai. Install it with "
        r"'.\.venv\Scripts\python.exe -m pip install google-genai'."
    ) from exc


PROMPT = (
    "Remove the entire background from this product photo and return only the product "
    "on a fully transparent background as a PNG. Keep the full product intact, preserve "
    "thin cable details, clean the inner loops and holes, and do not add any new objects "
    "or shadows."
)


def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35


def to_pil_image(image_obj) -> Image.Image:
    if isinstance(image_obj, Image.Image):
        return image_obj
    pil_image = getattr(image_obj, "_pil_image", None)
    if isinstance(pil_image, Image.Image):
        return pil_image
    as_pil = getattr(image_obj, "pil_image", None)
    if isinstance(as_pil, Image.Image):
        return as_pil
    raise TypeError(f"Unsupported image object type: {type(image_obj)!r}")


def make_transparent_from_borders(image: Image.Image) -> Image.Image:
    rgba = image.convert("RGBA")
    width, height = rgba.size
    pixels = rgba.load()

    visited: set[tuple[int, int]] = set()
    queue: deque[tuple[int, int]] = deque()

    def push_if_bg(x: int, y: int) -> None:
        if (x, y) in visited:
            return
        r, g, b, _ = pixels[x, y]
        if is_light_background_pixel(r, g, b):
            visited.add((x, y))
            queue.append((x, y))

    for x in range(width):
        push_if_bg(x, 0)
        push_if_bg(x, height - 1)
    for y in range(height):
        push_if_bg(0, y)
        push_if_bg(width - 1, y)

    while queue:
        x, y = queue.popleft()
        for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
            if 0 <= nx < width and 0 <= ny < height:
                push_if_bg(nx, ny)

    for x, y in visited:
        pixels[x, y] = (0, 0, 0, 0)

    return rgba


def save_first_image_part(response, dst: Path) -> None:
    parts = getattr(response, "parts", None)
    if parts is None and getattr(response, "candidates", None):
        parts = response.candidates[0].content.parts

    if not parts:
        raise RuntimeError("Model returned no content parts.")

    for part in parts:
        inline_data = getattr(part, "inline_data", None)
        if inline_data is None and isinstance(part, dict):
            inline_data = part.get("inline_data")

        if inline_data is None:
            continue

        if hasattr(part, "as_image"):
            image = to_pil_image(part.as_image())
            dst.parent.mkdir(parents=True, exist_ok=True)
            make_transparent_from_borders(image).save(dst)
            return

        data = getattr(inline_data, "data", None)
        mime_type = getattr(inline_data, "mime_type", "")
        if data:
            dst.parent.mkdir(parents=True, exist_ok=True)
            with open(dst, "wb") as handle:
                handle.write(data)
            with Image.open(dst) as img:
                processed = make_transparent_from_borders(img)
                processed.save(dst.with_suffix(".png"))
            if dst.suffix.lower() != ".png":
                dst.unlink(missing_ok=True)
            return

    raise RuntimeError("Model returned text only and no edited image.")


def process_image(src: Path, dst: Path, client, model: str) -> None:
    with Image.open(src).convert("RGBA") as image:
        response = client.models.generate_content(
            model=model,
            contents=[PROMPT, image],
        )
    save_first_image_part(response, dst)


def main() -> None:
    parser = argparse.ArgumentParser(description="Use Nano Banana / Gemini image editing to cut out product images.")
    parser.add_argument("input_dir", type=Path)
    parser.add_argument("output_dir", type=Path)
    parser.add_argument("--model", default="gemini-2.5-flash-image")
    args = parser.parse_args()

    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise SystemExit("Missing GEMINI_API_KEY environment variable.")

    client = genai.Client(api_key=api_key)
    exts = {".jpg", ".jpeg", ".png", ".webp"}

    for src in sorted(args.input_dir.iterdir()):
        if not src.is_file() or src.suffix.lower() not in exts:
            continue
        dst = args.output_dir / f"{src.stem}.png"
        process_image(src, dst, client, args.model)
        print(dst)


if __name__ == "__main__":
    main()

最適化を続けるのに適した場所

このスクリプトを大量生産に引き続き使用する予定がある場合は、後でこれらの機能を追加し続けることができます。

単一の画像エラーが報告された後にバッチ全体が中断されるのを避けるために、失敗の再試行が追加されました。
ログを記録して、処理に失敗した画像を特定しやすくします
さまざまなバックグラウンドしきい値に合わせて構成可能
サブディレクトリの再帰的スキャンをサポート
元の画像と結果画像の比較プレビューを追加しました

まとめ

「Google Nano Banana を呼び出して画像を切り出す方法」をすぐに理解したい場合は、実際には 3 つの主要な手順があります。

google-genai および Pillow をインストールする
GEMINI_API_KEY を設定します
client.models.generate_content() を使用してプロンプトの言葉と画像を渡します

このコードの価値は、モデルを呼び出すだけでなく、製品画像の切り抜きタスクで直接使用するのに適した透明な背景の後処理も追加することです。

Python はそれぞれ zip 形式と 7z 形式を使用して、パスワード付きでフォルダーを圧縮します

Sun, 09 Feb 2025 00:00:00 +0000

zip形式の圧縮

import pyzipper

    with pyzipper.AESZipFile(dest+'.zip', "w", encryption=pyzipper.WZ_AES) as zf:
        zf.setpassword(b"password")
        for file in os.listdir(dest):
            fullfile = os.path.join(dest,file)
            zf.write(fullfile, file)

import pyzipper vs import zipfile
pyzipper と zipfileapi は基本的に同じです
zipfile は解凍時のパスワードの使用のみをサポートしており、パスワード付きの圧縮パッケージの作成はサポートしていません。 pyzipper は、パスワード付きの圧縮パッケージの作成をサポートしています。
zf.write(path1, path2)
path1: 圧縮するファイルのパス
path2: 圧縮後のzipファイル内のパス
pyzipper.AESZipFile
パスワード設定暗号化=pyzipper.WZ_AES AES パスワード zf.setpassword(b"password") パスワードを設定します

7z形式の圧縮

import py7zr

    with py7zr.SevenZipFile(dest + '.7z', 'w', password='password') as archive:
        archive.writeall(dest, '')

archive.writeall(path1, path2)
path1 圧縮するファイルのパス。ディレクトリ全体を指定できます。
path2 は圧縮後の 7z ファイル内のパス、’’ はルートディレクトリを意味します
パスワードを設定する
password=‘password’

美しいスープとPythonを使用してキーワード、HTMLメタ属性の説明を取得します

Sun, 03 Apr 2022 00:00:00 +0000

間違ったアプローチ

私は最初に次の方法を使用しましたが、常に失敗しました。

1
2

title = soup.find("meta", name="description")
title = soup.find("meta", name="keywords")

正しい方法

美しいスープでは、メタタグを取得するために name=<…> の代わりに property=<…> を使用する必要があります。必要なものを取得するための最終コードは次のとおりです。

#获取description
md_desc = soup.find('head').find('meta', attrs={'name': 'description'})['content']

#获取keywords
md_keywords = soup.find('head').find('meta', attrs={'name': 'keywords'})['content']

別の方法

2 つの検索メソッドを通じて

1
2
3

meta = soup.findall("meta")
title = meta.find(name="description")
image = meta.find(name="keywords")

update-alternatives を使用して Ubuntu に複数の Python 環境をインストールおよび管理する

Thu, 17 Dec 2020 00:00:00 +0000

複数のバージョンの Python をインストールする

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.6
sudo apt-get install python3.7
sudo apt-get install python3.8

このマシンにどの Python がインストールされているかを確認します

knightli@ubuntu:/etc/alternatives$ ls -larth `which python`*
lrwxrwxrwx 1 root root   58 Feb 17  2020 /usr/bin/pythontex -> ../share/texlive/texmf-dist/scripts/pythontex/pythontex.py
lrwxrwxrwx 1 root root   16 Mar 13  2020 /usr/bin/python3-config -> python3.8-config
lrwxrwxrwx 1 root root    9 Mar 13  2020 /usr/bin/python2 -> python2.7
-rwxr-xr-x 1 root root  388 Mar 27  2020 /usr/bin/python3-pasteurize
-rwxr-xr-x 1 root root  384 Mar 27  2020 /usr/bin/python3-futurize
lrwxrwxrwx 1 root root    7 Apr 15  2020 /usr/bin/python -> python2
lrwxrwxrwx 1 root root   33 Jul 28 05:59 /usr/bin/python3.8-config -> x86_64-linux-gnu-python3.8-config
-rwxr-xr-x 1 root root 5.3M Jul 28 05:59 /usr/bin/,python3.8
-rwxr-xr-x 1 root root 3.5M Aug  4 04:16 /usr/bin/python2.7
-rwxr-xr-x 2 root root 4.3M Aug 17 16:45 /usr/bin/python3.6m
-rwxr-xr-x 2 root root 4.3M Aug 17 16:45 /usr/bin/python3.6
-rwxr-xr-x 2 root root 5.3M Aug 17 19:07 /usr/bin/python3.7m
-rwxr-xr-x 2 root root 5.3M Aug 17 19:07 /usr/bin/python3.7
lrwxrwxrwx 1 root root   25 Dec 16 19:39 /usr/bin/python3 -> /etc/alternatives/python3

上記からわかるように、python2.7、python3.6、python3.7、python3.8の合計4つのバージョンがインストールされています。

update-alternatives を使用した Python の複数バージョンの管理

代替案はPythonプロジェクトをインストールします

knightli@ubuntu:/etc/alternatives$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python2.7 1
update-alternatives: using /usr/bin/python2.7 to provide /usr/bin/python (python) in auto mode
knightli@ubuntu:/etc/alternatives$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.6 2
update-alternatives: using /usr/bin/python3.6 to provide /usr/bin/python (python) in auto mode
knightli@ubuntu:/etc/alternatives$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.7 3
update-alternatives: using /usr/bin/python3.7 to provide /usr/bin/python (python) in auto mode
knightli@ubuntu:/etc/alternatives$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.8 4
update-alternatives: using /usr/bin/python3.8 to provide /usr/bin/python (python) in auto mode

追加した後、alternatives –list を使用して、インストールされている Python を一覧表示できます。

knightli@ubuntu:/etc/alternatives$ sudo update-alternatives --list python
/usr/bin/python2.7
/usr/bin/python3.6
/usr/bin/python3.7
/usr/bin/python3.8

代替の –config スイッチを使用する

knightli@ubuntu:/etc/alternatives$ sudo update-alternatives --config python
There are 4 choices for the alternative python (providing /usr/bin/python).

  Selection    Path                Priority   Status
------------------------------------------------------------
* 0            /usr/bin/python3.8   4         auto mode
  1            /usr/bin/python2.7   1         manual mode
  2            /usr/bin/python3.6   2         manual mode
  3            /usr/bin/python3.7   3         manual mode
  4            /usr/bin/python3.8   4         manual mode

Press <enter> to keep the current choice[*], or type selection number: 3
update-alternatives: using /usr/bin/python3.7 to provide /usr/bin/python (python) in manual mode
knightli@ubuntu:/etc/alternatives$ python -V
Python 3.7.9

ピップの使用

「python -m pip install xxx」を使用して、対応するバージョンの pip をインストールします。

Anaconda を使用して Windows で Python 環境を管理する

Sat, 05 Dec 2020 00:00:00 +0000

アナコンダをインストールする

ダウンロードアドレス https://www.anaconda.com/products/individual を一番下までスクロールします。

アナコンダの使用

ウィンドウの下で Anaconda Powershell プロンプト (Anaconda3) または Anaconda プロンプト (Anaconda3) を開きます

Python環境を見る conda info –env すべての Python 環境を表示できます。現在の環境を表すためにその前に「*」があります。
Python環境を作成する conda create –name python35 python=3.5
python3.5 環境の作成を表し、python35 という名前を付けました。
Python環境の管理と使用 conda activate python35 python35 という名前の環境をアクティブ化します。

Python on KnightLiブログ

uv インストールガイド：macOS、Linux、Windows、pipx、Homebrew、WinGet の選び方

すばやく選ぶ

macOS と Linux：公式インストーラー

Windows：PowerShell インストーラー

pipx でインストールする

Homebrew、MacPorts、WinGet、Scoop

Docker、GitHub Releases、Cargo

uv をアップグレードする

shell 補完を有効にする

uv をアンインストールする

インストール後に最初にすること

私のおすすめ

関連リンク

faster-whisper：より高速な Whisper 文字起こしエンジン

何を解決するのか

インストール

基本的な使い方

CPU と GPU の選び方

バッチ文字起こし

VAD と単語単位のタイムスタンプ

モデルの選び方

向いている用途

デプロイ時のすすめ方

まとめ

Google LangExtract：LLM で長文から構造化データを抽出する

何を解決するのか

LangExtract の特徴

1. 例で抽出形式を制約する

2. 抽出結果を原文へ対応付けられる

3. 長文ドキュメントを扱える

4. 可視化チェックを支援する

どんなときに使うべきか

基本的なインストール

基本的な使い方

使うときの注意点

正規表現や従来 NLP との違い

どんな開発者に向いているか

参考

最後に

rembgプロジェクト整理：ローカル画像背景除去ツール

01 インストール方法

02 CLI サブコマンド

03 フォルダーの一括処理

04 Python ライブラリとして使う

05 HTTP サーバーを起動する

06 Docker 実行

07 モデル選択

08 向いている場面

09 使い方のおすすめ

10 短い判断

関連リンク

codex-quota 実践ガイド：コマンドをそのまま使う Local・Web・Docker 運用

このプロジェクトは何をするか

先にアカウント認証情報を準備する

Local CLI の使い方（元コマンドを維持）

CLI オプション説明（README 準拠）

Web Dashboard の使い方（元コマンドを維持）

HTTP エンドポイント（自動化向け）

Docker の使い方（元コマンドを維持）

Docker Compose の使い方（元コマンドを維持）

運用のヒント

Codex クォータ使用統計

やるべきことに適した

最も重要なインプット

返された結果の見方

よくある質問

参考リンク

コード

eコマース商品画像の切り抜きと標準化されたエージェントスキルを共有する

このスキルはどのような問題を解決しますか?

該当するシナリオ

クイックスタート

出力ルール

主なパラメータの説明

処理の流れ

通常の切り抜きスクリプトとの違い

SKILL.md ソースコード

スクリプト/run_pipeline.py ソース コード

Google Nano Bananaを呼び出して画像を切り出す方法

スクリプト/run_pipeline.py ソースコード