実行プログラムと拡張機能
Craneとは？LLM・OCR・音声モデルをRust製ローカルAPIで動かす
チャットモデルは一つのPython環境、OCRは別のライブラリ、音声認識はさらに別の導入手順となると、環境管理に時間を取られます。CraneはHugging Face Candleを使うRust推論プロジェクトです。テキストモデルとOCR・ASR・TTSの例を一つのリポジトリに置き、crane-serveでローカルAPIとして接続できます。まず小さなQwen3.5モデルでチャット経路を確認し、必要なモデルを加えていく方法で始められます。このガイドではリポジトリの版を固定してビルドし、サーバーを自分の端末内に限定して、アプリから同じAPIを呼び出します。
要点
- 01
- CraneはCandleベースのRustプロジェクトで、テキスト・画像・音声処理をアプリやHTTP APIにつなぎます。
- 02
- 公式のQwen/Qwen3.5-0.8Bファイルでチャットサーバーを確認し、クライアントにはhttp://127.0.0.1:8080/v1とモデル名crane-localを設定します。
- 03
- Bonsai 2のPrism GGUF経路はCPU・NVIDIA CUDA向けと案内されています。プロジェクト全体のMetal対応とモデル別の実行対応は分けて考えます。
モデル処理ごとに別のPython環境を管理する手間
チャットサーバーは仮想環境で動いているのに、OCRパッケージを足すと依存関係が衝突し、音声認識のデモは別のPythonバージョンを要求する。そんな状況を考えてみてください。困るのはモデルより、処理ごとに分かれた実行環境です。CraneはRustとCandleを中心に、テキスト推論、画像入力、OCR、音声処理を一つのプロジェクトで管理するアプローチです。
Rustはコンパイル時に多くの誤りを見つけ、実行ファイルとして配布しやすい言語です。CandleはRustでテンソル演算やモデル部品を提供するため、Craneではアプリのコードと推論エンジンを同じ言語環境に置けます。これは開発・運用構成上の利点であり、どのモデルも自動的に速くなるという約束ではありません。
Crane・Ollama・MLXは役割が異なる
Ollamaはモデルの取得とローカルAPIの利用を簡単にします。MLXはApple Silicon向けの機械学習フレームワークで、oMLXなどが利用します。CraneはCandleのRust製モデル実装と複数の実行経路をまとめます。Rustアプリへの推論組み込みや、同じサーバープログラムをモデル別に使いたい場合の選択肢です。基本構成では1プロセスに1モデルを読み込みます。チャットと音声を併用するなら、必要なサーバーを別々のポートで起動します。
Craneのcrane-serveにモデルを指定し、既存のプログラムからOpenAI形式のチャットリクエストを送れます。デスクトップアプリの便利機能を置き換えるというより、アプリとモデルの間に自分で扱えるサーバー層を置く選択です。MacでMetalを使えるというプロジェクトの説明が、すべてのモデルのMetal実行を意味するわけではありません。後述するBonsai 2のように、チェックポイントごとに対応デバイスが案内されています。
リポジトリの版を固定してサーバーをビルドする
以下は2026年9月23日に確認したCraneのコミットを対象にした手順です。リポジトリを取得してそのコミットに切り替えると、後日のmain更新でコマンドや対応モデルが変わる影響を抑えられます。Rustツールチェーンを用意し、macOSではXcode Command Line Tools、NVIDIA CUDA向けにビルドするLinux端末では対応するCUDA toolkitを準備します。
以下のビルドコマンドは、端末に合う一つだけを実行します。MacはMetal・Accelerate、NVIDIA GPU搭載LinuxはCUDA、GPUなしで試す場合はCPUを選びます。モデルの重みはビルドに含まれないため、次の手順で別途取得します。公式install.shも選択を補助しますが、ここでは有効にする機能が分かるようCargoコマンドを直接使います。
git clone https://github.com/lucasjinreal/Crane.git
cd Crane
git checkout --detach 99a60887bdca16b4852b7bc953ca03c1df374e88cargo build --release -p crane-serve --features "metal,accelerate"cargo build --release -p crane-serve --features cudacargo build --release -p crane-serve
小さなモデルで先にチャット経路を確認する
初回実行では公式Hugging FaceリポジトリQwen/Qwen3.5-0.8Bを使います。CraneのREADMEはQwen 3.5 0.8Bを対応モデルとして挙げ、モデルカードには同じIDのsafetensorsリポジトリとライセンスが掲載されています。このチェックポイントには画像エンコーダーが含まれるため、テキスト会話だけを試す場合はcrane-serveの--text-onlyで画像部分を外します。
モデルはHugging Face CLIで取得します。uvがあれば以下のuvx hfを使えます。ツール用の隔離環境はuvが管理するので、自分で仮想環境を作る必要はありません。uvがなければ、下のCLI導入案内から環境に合う方法を選びます。取得後はモデルのフォルダーに設定・トークナイザー・重みのファイルがそろっているか確認しましょう。
uvx hf download Qwen/Qwen3.5-0.8B --local-dir models/Qwen3.5-0.8Bサーバーを127.0.0.1だけで待ち受ける
モデルを取得したらcrane-serveを起動します。--model-name crane-localはAPIリクエストで使う名前、--context 4096はこの試行でのコンテキスト上限です。--host 127.0.0.1を指定すると同じ端末上のクライアントだけが接続できます。Craneのhost既定値は0.0.0.0なので、このオプションを省かないでください。
サーバーが起動したらターミナルのアドレスを確認します。組み込み画面が自動で開かない場合は、ブラウザーでhttp://127.0.0.1:8080/にアクセスします。--uiはCrane内蔵のブラウザー画面を提供します。テキスト専用モデルを読み込んだら、短い質問から始めて応答が最後まで届くか見てください。
./target/release/crane-serve --model-path models/Qwen3.5-0.8B --model-type qwen3_5_vl --text-only --model-name crane-local --host 127.0.0.1 --port 8080 --context 4096 --uiAPIクライアントから同じサーバーを呼び出す
HTTPを直接呼び出すと、サーバーとアプリ間の接続を切り分けて確認できます。curl -Nはストリーミング出力をバッファせず表示します。リクエストのmodelは起動時に付けたcrane-localと一致させます。対応するQwenテンプレートではchat_template_kwargs.enable_thinkingで思考モードを無効にできます。
OpenAI互換アプリにはbase URL http://127.0.0.1:8080/v1とモデル名crane-localを設定します。上の例はAPI認証を有効にしないローカル専用構成です。API key欄が必須ならlocalなどの仮文字列を使えますが、サーバーを保護するパスワードにはなりません。接続できたら普段使う言語の質問や短いコードの説明を試してみましょう。
curl -N http://127.0.0.1:8080/v1/chat/completions -H 'Content-Type: application/json' -d '{"model":"crane-local","messages":[{"role":"user","content":"Say hello in one short sentence."}],"stream":true,"max_tokens":256,"temperature":0,"chat_template_kwargs":{"enable_thinking":false}}'チャットの後にOCR・ASR・TTSをつなぐ
チャットが動いたら、次に使う処理に合わせたモデル種別でサーバーを起動し直します。CraneのリポジトリにはPaddleOCR系、Qwen3-ASR、Qwen3-TTSなどがあり、crane-serve文書には音声文字起こし・音声生成の経路も記載されています。音声サーバーはチャットとモデル種別や入力が異なるため、READMEの該当箇所にあるオプションとAPI形式を使い、サンプル一つで接続しましょう。
実際のファイルや業務内容を送る前に、短く機密性のない入力で結果を見ます。OCRでは写真の文字を読み取れるか、ASRでは韓国語音声を書き起こせるか、TTSでは必要な言語を発話できるかを確かめます。処理ごとに別モデルが必要でも、アプリから接続するサーバーの形式は再利用できます。
Bonsai 2に切り替えると何が変わるか
Bonsai 2のPrism配布版は、PTQ1_0またはPQ2_0の三値重みを含むGGUFファイルです。Craneは専用のGGUFタイプを識別し、対象の重みにTernaryLinear実行経路を使うよう追加されました。ダウンロード時には一般的なQ4 GGUFではなく、指定されたBonsai 2 Prismファイルを選びます。
公式の対応記録では、このモデルの実行先としてCPUとNVIDIA CUDAが挙げられています。Qwen3.5のMetal経路とは条件が異なるため、MacでCraneをビルドしてもBonsai 2が同じGPU加速を得るとは限りません。27Bというパラメータ数だけでメモリを見積もらず、選んだPrismファイルのサイズとコンテキスト4096での空きメモリを確認します。
./target/release/crane-serve \
--model-path /absolute/path/Ternary-Bonsai-2-27B-PTQ1_0.gguf \
--model-name bonsai-local --host 127.0.0.1 --port 8080 \
--context 4096 --ui今の実行環境と条件をそろえて比べる
このガイドではCraneの実測は行っていません。自分の端末ではモデル読み込みとウォームアップを測定から分け、同じリクエストを3回測って中央値を記録します。初回応答までの時間、その後の生成速度、全体の完了時間を分けると、入力処理と回答生成のどちらが変わったか分かります。
同じ質問でも片方だけ思考モードが有効だったり、出力上限が違ったりすれば公平には比べられません。モデル・量子化・文脈長・出力上限をそろえ、キャッシュのない新規リクエストと会話の続きを分けます。MLXとGGUFなど形式の違いも記録しましょう。速くても重要な内容を落とすなら、乗り換える理由には不十分です。環境管理が減り、日々の作業をきちんと終えられるかが判断の軸です。
