KoboldCpp 詳細解説：PythonでローカルLLMを動かす最強ツール！

技術解説
AI生成GGUFKoboldCppPythonローカルLLM

llama.cppベースの高機能AIテキスト生成ソフトウェア

はじめに：KoboldCppとは？ 🤔

KoboldCppは、元々KoboldAIに触発されて開発された、GGUF（旧GGML）形式の大規模言語モデル（LLM）を簡単に実行するためのソフトウェアです。開発元はConcedoで、llama.cppをベースに構築されています。

KoboldCppの最大の特徴は、単一ファイルで実行可能であり、複雑なインストール作業や外部ライブラリの依存関係なしに、手軽にローカル環境でAIによるテキスト生成を始められる点です。CPUのみでも動作しますが、GPU（NVIDIA CUDA, AMD ROCm, Apple Metal）を活用した高速化にも対応しています。

さらに、オリジナルのKoboldAIやKoboldAI Liteが持つ高機能なWeb UI（永続的なストーリー管理、編集ツール、メモリ機能、キャラクター設定など）に加え、画像生成（Stable Diffusion等）、音声認識（Whisper）、音声合成（OuteTTS）といった多様な機能も統合されています。また、KoboldAI API、OpenAI API、Ollama APIなど、様々な互換APIエンドポイントを提供しており、他のアプリケーションとの連携も容易です。

💡 ポイント: KoboldCppは、llama.cppのパワーとKoboldAIの使いやすさを融合し、さらに多くの機能を追加したオールインワン・ソリューションと言えるでしょう。

KoboldCppの主な特徴 ✨

KoboldCppが多くのユーザーに支持される理由は、その豊富な機能にあります。

  • 簡単なセットアップ: Windows向けにはkoboldcpp.exeという単一の実行ファイルが提供されており、ダウンロードして実行するだけで、複雑なインストールは不要です。LinuxやmacOS向けにもビルドスクリプトやバイナリが提供されています。
  • 幅広いモデルサポート: GGUF形式（および旧GGML形式）の主要な大規模言語モデルに対応しています。Hugging Faceなどで公開されている多くのモデルを利用可能です。
  • ハードウェアアクセラレーション:
    • NVIDIA GPU (CUDA / cuBLAS)
    • AMD GPU (ROCm / HIPBLAS)
    • Intel GPU (OpenCL / SYCL via CLBlast)
    • Apple Silicon (Metal)
    • CPU (OpenBLAS, AVX2など)
    GPUにモデルの一部または全体をオフロードすることで、推論速度を大幅に向上させることができます。
  • 高機能Web UI: KoboldAI Liteに基づいた洗練されたWebインターフェースを提供します。
    • 永続的なストーリー管理と編集機能
    • メモリ、ワールド情報、著者ノート機能
    • キャラクター設定、シナリオ管理
    • 多様な保存形式
  • マルチモーダル機能:
    • 画像生成 (Stable Diffusion 1.5/XL/3, FLUX)
    • 音声認識 (Whisper)
    • 音声合成 (OuteTTS)
    • 画像からのテキスト生成（例: Gemma3 Vision）
  • 豊富なAPI互換性:
    • KoboldCpp API (独自拡張含む)
    • OpenAI API互換エンドポイント (/v1)
    • Ollama API互換エンドポイント
    • その他 (A1111/Forge, ComfyUI, Whisper, XTTSなど)
    これにより、SillyTavernや各種プログラミング言語（Pythonなど）から簡単に連携できます。
  • クロスプラットフォーム: Windows, Linux, macOSで動作します。Android (Termux) でのコンパイル・実行も可能です。
  • クラウド実行環境: Google ColabやRunPodなどのクラウドGPUサービスで簡単に試せる公式テンプレートも提供されています。
  • ライセンス: KoboldCpp自体のコードは主にAGPL v3.0ライセンスですが、ベースとなっているllama.cppはMITライセンスです。

GGUFモデルについて

KoboldCppはGGUF形式のモデルファイルを使用します。これはGGML形式の後継であり、メタデータの保存や拡張性に優れています。モデルファイル自体はKoboldCppには含まれていないため、別途ダウンロードする必要があります。
代表的な配布元としては、TheBloke氏のHugging Faceリポジトリなどが有名です。Hugging Faceで “GGUF” と検索すれば、多数の互換モデルが見つかります。

インストール方法 💻

KoboldCppのインストールは非常に簡単です。

Windows (推奨)

  1. GitHubリリースページから最新のkoboldcpp.exe (CUDAサポートが必要な場合) または koboldcpp_nocuda.exe (CUDA不要の場合、ファイルサイズが小さい) をダウンロードします。
  2. ダウンロードした.exeファイルをダブルクリックして実行します。
  3. 初回起動時にGUIウィンドウが表示されるので、使用するGGUFモデルファイルを選択し、必要に応じて設定（GPUレイヤー数など）を調整して「Launch」ボタンをクリックします。

これだけでWeb UIが起動し、ブラウザ (通常は http://localhost:5001) でアクセスできるようになります。

Linux

Linuxではいくつかの方法があります。

  • Precompiled Binary: リリースページにLinux向けのPyInstallerバイナリ (例: koboldcpp-linux-x64) があれば、それをダウンロードし、実行権限を与えて実行します。 
    chmod +x koboldcpp-linux-x64
./koboldcpp-linux-x64
  • Automated Compiler Script (koboldcpp.sh): ソースコードからビルドする場合、提供されているスクリプトを使うと依存関係の解決とビルドを自動で行えます（conda環境を使用）。 
    git clone https://github.com/LostRuins/koboldcpp.git
cd koboldcpp
./koboldcpp.sh # GUIを起動 (X11が必要)
# または ./koboldcpp.sh dist でPyInstallerバイナリを生成
  • Manual Compilation (make): 依存関係（build-essential, python3-dev, 必要に応じてlibopenblas-dev, libclblast-dev, NVIDIA CUDA Toolkitなど）を手動でインストールし、makeコマンドでコンパイルします。 
    git clone https://github.com/LostRuins/koboldcpp.git
cd koboldcpp
make # 基本的なビルド
# make LLAMA_CUBLAS=1 # CUDAサポート付きビルド
# make LLAMA_CLBLAST=1 # CLBlastサポート付きビルド
    コンパイル後、Pythonスクリプトを実行します。 
    python koboldcpp.py --model /path/to/your_model.gguf
  • Arch Linux (AUR): AURヘルパーを使ってインストールできます。 
    yay -S koboldcpp

macOS

  1. GitHubリリースページからmacOS用 (ARM64/Apple Silicon) のバイナリ (例: koboldcpp-mac-arm64) をダウンロードします。
  2. ターミナルを開き、ダウンロードしたファイルに実行権限を付与します。 
    chmod +x /path/to/koboldcpp-mac-arm64
  3. バイナリを実行します。 
    /path/to/koboldcpp-mac-arm64
    GUIが表示されるので、モデルを選択して起動します。
  4. Manual Compilation (make): Linuxと同様に、ソースからコンパイルすることも可能です。Metal GPUサポートを有効にする場合は、Xcode Command Line Toolsをインストールした後、make LLAMA_METAL=1 を実行します。

Android (Termux)

Termuxを使えばAndroidデバイス上でもKoboldCppをコンパイルして実行できます。

  1. F-DroidからTermuxをインストールし、起動します。
  2. リポジトリを更新し、必要なパッケージをインストールします。 
    pkg update && pkg upgrade
pkg install git wget python build-essential
  3. KoboldCppのリポジトリをクローンします。 
    git clone https://github.com/LostRuins/koboldcpp.git
cd koboldcpp
  4. コンパイルします。 
    make
  5. モデルファイルをダウンロードし、Pythonスクリプトを実行します。 
    python koboldcpp.py --model /path/to/your_model.gguf --host 0.0.0.0 --port 8000
    （--host 0.0.0.0 をつけると、同じネットワーク内の他のデバイスからもアクセスできます）

注意点

  • Windowsで初回実行時にセキュリティ警告が表示される場合があります。「詳細情報」→「実行」を選択してください。
  • ソースからコンパイルする場合、環境によっては追加のライブラリや設定が必要になることがあります。エラーメッセージをよく確認してください。
  • GPUアクセラレーションを利用するには、対応するドライバやツールキット（CUDA Toolkitなど）が正しくインストールされている必要があります。

基本的な使い方 🚀

KoboldCppは、実行ファイル (koboldcpp.exe や ./koboldcpp など) を実行すると、まず設定用のGUIウィンドウが起動します（コマンドラインから直接起動する場合を除く）。

GUIからの起動

  1. Model: 「Browse」ボタンで、使用したいGGUFモデルファイルを選択します。
  2. Presets: モデルの種類や用途に応じた推奨設定プリセットを選択できます。よくわからない場合は、モデル名に含まれる情報（例: “Mistral”, “Llama 3″）に近いものを選ぶと良いでしょう。
  3. GPU Layers: GPUにオフロードするモデルのレイヤー数を指定します。「Max」ボタンを押すと、VRAMに収まる最大レイヤー数が自動で設定されることが多いですが、メモリ不足エラーが出る場合は少しずつ減らしてみてください。GPUを使わない場合は0のままにします。
  4. Context Size: モデルが一度に処理できるテキストの最大長（トークン数）を設定します。モデルがサポートする最大値や、使用するメモリ量に応じて調整します。
  5. Use CuBLAS / Use ROCm / Use Metal: 対応するGPUアクセラレーションを有効にする場合にチェックを入れます。
  6. Launch: 設定が完了したら、「Launch」ボタンをクリックします。コンソールウィンドウが表示され、モデルの読み込みが始まります。完了すると、Web UIにアクセスするためのURL (通常 http://localhost:5001) が表示されます。

コマンドラインからの起動

より詳細な設定を行いたい場合や、自動化したい場合はコマンドライン引数が便利です。--helpオプションで利用可能な全ての引数を確認できます。 

# 基本的な起動 (モデルファイルを指定)
./koboldcpp --model /path/to/my_model.gguf

# ポート番号を指定して起動
./koboldcpp --model model.gguf --port 8080

# CUDAを使ってGPUレイヤーを40層オフロード、コンテキストサイズを8192に設定
./koboldcpp --model model.gguf --usecublas --gpulayers 40 --contextsize 8192

# ROCmを使ってGPUレイヤーをすべてオフロード (Auto)
./koboldcpp --model model.gguf --useroem --gpulayers auto

# Metalを使ってGPUレイヤーを30層オフロード (macOS)
./koboldcpp-mac-arm64 --model model.gguf --usemetal --gpulayers 30

# 利用可能な全オプションを表示
./koboldcpp --help

よく使われるオプション:

オプション 説明
--model <filepath> 使用するGGUFモデルファイルのパスを指定します。
--port <number> Webサーバーが使用するポート番号を指定します (デフォルト: 5001)。
--host <ip_address> WebサーバーがバインドするIPアドレスを指定します (デフォルト: localhost)。他のデバイスからアクセスさせたい場合は 0.0.0.0 を指定します。
--gpulayers <number|auto> GPUにオフロードするレイヤー数を指定します。auto で自動設定を試みます。
--usecublas NVIDIA GPU (CUDA) アクセラレーションを有効にします。
--useroem AMD GPU (ROCm) アクセラレーションを有効にします。
--useclblast [PlatformID] [DeviceID] OpenCL (CLBlast) アクセラレーションを有効にします。プラットフォームIDとデバイスIDをオプションで指定できます。
--usemetal Apple Metal アクセラレーションを有効にします (macOS)。
--contextsize <number> コンテキストサイズ（トークン数）を指定します。
--threads <number> CPUで使用するスレッド数を指定します。
--stream ストリーミング出力を有効にします (現在は非推奨、UI側で設定)。
--launch 起動時に自動的にブラウザでWeb UIを開きます。
--highpriority プロセスを高優先度で実行します (Windows)。
--chatcompletionsadapter <filename.json|AdapterName> OpenAI互換API (/v1) で使用するインストラクトテンプレートのアダプターを指定します (例: ChatML.json)。AutoGuess.jsonで自動推測も可能です。

API連携とPythonでの利用 🐍

KoboldCppの強力な機能の一つが、外部アプリケーションやスクリプトから利用できるAPIです。特にOpenAI互換APIエンドポイント (/v1) が提供されているため、多くの既存ツールやライブラリ（openai Pythonライブラリなど）を流用して簡単に連携できます。

APIエンドポイント

  • KoboldAI互換API: http://localhost:5001/api/ 以下に、従来のKoboldAIと互換性のあるエンドポイントがあります。
  • OpenAI互換API: http://localhost:5001/v1/ 以下に、OpenAIのAPI仕様に準拠したエンドポイントがあります。チャット補完 (/v1/chat/completions) などが利用可能です。
  • KoboldCpp拡張API: http://localhost:5001/api/extra/ 以下に、KoboldCpp独自の機能（モデル情報取得、トークンカウント、Whisper連携など）のためのエンドポイントがあります。
  • APIドキュメント: 起動後、http://localhost:5001/api にアクセスすると、利用可能な全APIエンドポイントのSwagger UIドキュメントが表示され、そこから直接APIを試すこともできます。

PythonからOpenAI互換APIを利用する例

openaiライブラリを使って、ローカルで実行中のKoboldCppにテキスト生成をリクエストする簡単な例です。

# openaiライブラリをインストール: pip install openai
import openai

# KoboldCppのAPIエンドポイントを指定
# ローカルでポート5001で動作していると仮定
client = openai.OpenAI(
    base_url="http://localhost:5001/v1",
    api_key="sk-no-key-required" # KoboldCppではAPIキーは不要
)

try:
    completion = client.chat.completions.create(
        model="koboldcpp/dummy-model", # モデル名は必須だが、KoboldCpp側でロードされているモデルが使われる
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "KoboldCppについて日本語で簡単に説明してください。"}
        ],
        max_tokens=150,  # 生成する最大トークン数
        temperature=0.7, # 温度 (ランダム性)
        # stream=True # ストリーミングで受け取る場合
    )

    # --- ストリーミングなしの場合 ---
    print(completion.choices[0].message.content)

    # --- ストリーミングありの場合 ---
    # for chunk in completion:
    #     if chunk.choices[0].delta.content is not None:
    #         print(chunk.choices[0].delta.content, end="")
    # print()

except openai.APIConnectionError as e:
    print(f"KoboldCppへの接続に失敗しました: {e}")
except openai.APIStatusError as e:
    print(f"APIエラーが発生しました: Status Code {e.status_code}, Response: {e.response}")
except Exception as e:
    print(f"予期せぬエラーが発生しました: {e}")
💡 ポイント: base_urlをKoboldCppのアドレス (http://localhost:5001/v1) に設定し、api_keyにはダミーの文字列を指定するだけで、openaiライブラリがそのまま利用できます。modelパラメータは必須ですが、KoboldCpp側で現在ロードされているモデルが使用されるため、中身は任意です。

PythonからKoboldCpp拡張APIを利用する例 (requests)

より直接的にAPIを叩きたい場合は、requestsライブラリなどを使います。KoboldCpp独自のエンドポイントを使う場合に便利です。

# requestsライブラリをインストール: pip install requests
import requests
import json

kobold_url = "http://localhost:5001"

# 例1: 現在ロードされているモデル名を取得 (/api/extra/model)
try:
    response = requests.get(f"{kobold_url}/api/extra/model")
    response.raise_for_status() # エラーチェック
    model_info = response.json()
    print(f"現在のモデル: {model_info.get('result', '取得失敗')}")
except requests.exceptions.RequestException as e:
    print(f"モデル情報の取得に失敗しました: {e}")

# 例2: テキストのトークン数をカウント (/api/extra/tokencount)
try:
    text_to_count = "これはトークン数を数えるテストです。"
    payload = {"prompt": text_to_count}
    response = requests.post(f"{kobold_url}/api/extra/tokencount", json=payload)
    response.raise_for_status()
    token_count_info = response.json()
    print(f"'{text_to_count}' のトークン数: {token_count_info.get('result', {}).get('value', '取得失敗')}")
except requests.exceptions.RequestException as e:
    print(f"トークン数のカウントに失敗しました: {e}")

# 例3: KoboldAI互換のテキスト生成 (/api/v1/generate - POST)
try:
    payload = {
        "prompt": "昔々あるところに、",
        "max_context_length": 1024, # 必要に応じて調整
        "max_length": 50,
        "temperature": 0.8,
        "top_p": 0.9,
    }
    response = requests.post(f"{kobold_url}/api/v1/generate", json=payload)
    response.raise_for_status()
    generation_result = response.json()
    print(f"生成結果:\n{generation_result.get('results', [{}])[0].get('text', '生成失敗')}")

except requests.exceptions.RequestException as e:
    print(f"テキスト生成に失敗しました: {e}")

これらのAPIを利用することで、PythonスクリプトからローカルLLMの機能を活用した様々なアプリケーション（チャットボット、テキスト要約ツール、コード生成支援など）を開発することが可能です。

最近では、より簡単にPythonからKoboldCpp APIを利用するためのヘルパーライブラリやサンプルコードもコミュニティによって開発されています（例: Redditの初心者向けガイドなど）。

ユースケースと可能性 💡

KoboldCppは、その手軽さと高機能性から、様々な用途で活用されています。

  • クリエイティブライティング支援: 小説、物語、キャラクターの対話などをAIに生成させる。KoboldAI由来のUIは特にこの用途に適しています。
  • ローカルチャットボット: OpenAI APIなどに依存せず、プライベートな環境で動作するチャットボットを構築する。
  • プログラミング支援: コード生成やデバッグの補助として利用する（例: MPT-30B-Chatなどのコーディング特化モデルを使用）。
  • テキスト要約・翻訳: 長文の要約や、簡単な翻訳タスクに利用する。
  • 教育・研究: LLMの挙動をローカル環境で手軽に試したり、特定のタスク向けにファインチューニングされたモデルを動かしたりする。
  • オフライン環境での利用: インターネット接続がない環境でもAIテキスト生成機能を利用する。
  • API連携によるカスタムアプリ開発: Pythonや他の言語からAPIを叩き、独自のAI搭載アプリケーションを開発する。
🚀 KoboldCppを使えば、高価なクラウドサービスや複雑な環境構築なしに、最新のLLM技術を自分のPCで手軽に試し、活用することができます。

最近のアップデート情報 (例) 📰

KoboldCppは活発に開発が続けられており、頻繁に新機能の追加や改善が行われています。以下は最近のリリース (v1.86.2 – 2024年頃) で見られたようなアップデートの例です。

  • Gemma 3 Vision サポート: Googleの新しいマルチモーダルモデルGemma 3のGGUF版とVision mmprojファイルの読み込みに対応し、画像入力が可能に。
  • API改善: OpenAI API互換エンドポイントのfinish_reasonの値やツール呼び出しの挙動を修正。
  • ハードウェアサポート改善: 古いCUDA Compute Capability 3.7 (NVIDIA K80など) のサポートを再有効化。CLBlastのVRAM検出に関するバグ修正。
  • Colab連携強化: Google Colabで使用時にGoogle Driveへストーリーを保存するオプションを追加。
  • 画像生成機能強化: 生成画像にパラメータメタデータを埋め込み。LoRAをURLからダウンロードして適用可能に。
  • パフォーマンス向上: 量子化KVキャッシュ (--quantkv) とコンテキストシフトの併用が可能に (Flash Attention有効時)。
  • UI/UX改善: Kobold Lite UIのアップデート、サイドパネルモードの改善、インストラクトテンプレートを自動取得するプリセットKoboldCppAutomaticの追加。
  • 新オプション追加: デフォルトの最大生成トークン数を制御する--defaultgenamount、BOSトークンを自動使用しない--nobostokenなど。

最新の情報や詳細な変更履歴は、GitHubリリースページで確認することをお勧めします。

まとめ 🎉

KoboldCppは、llama.cppの強力な推論エンジンとKoboldAIの洗練されたUI/機能を組み合わせ、さらに独自の拡張を加えた、非常にパワフルかつ使いやすいローカルLLM実行環境です。

単一ファイルで動作する手軽さ、幅広いモデルとハードウェアへの対応、豊富な機能、そしてOpenAI互換APIによる高い拡張性を備えており、初心者から開発者まで、多くのユーザーにとって魅力的な選択肢となっています。

ローカル環境でLLMを試してみたい方、プライベートなAIチャットボットを構築したい方、Python等でAI機能を活用したアプリケーションを開発したい方は、ぜひKoboldCppを試してみてはいかがでしょうか。きっとその手軽さと多機能性に驚くはずです！😊

コメント

タイトルとURLをコピーしました