OpenHandsでオープンソースモデルを使用するガイド

概要

このドキュメントは、OpenHandsでオープンソースの大規模言語モデル（LLM）を無料で使用する方法を体系的に説明します。2025年7月時点の最新モデルと設定方法を網羅しています。

背景と動機

現状の課題

解決策

Ollama、Groq、Google AI Studioなどを活用し、最新の高品質オープンソースモデルを無料で利用可能にする。

2025年7月時点の最新オープンソースモデル

1. Llama 3.1シリーズ（Meta - 2024年7月リリース）

2. Gemma 2シリーズ（Google - 2024年6月リリース）

3. Qwen2.5シリーズ（Alibaba - 2024年9月リリース）

4. DeepSeek-V2.5（2024年11月リリース）

5. Mistral最新モデル（2024年12月）

6. コード特化最新モデル

セットアップ方法

重要な注意事項

ローカルCLIインストール版では環境変数は使用できません。 必ず以下のいずれかの方法を使用してください：

  1. 初回起動時の対話的設定
  2. ~/.openhands/settings.jsonファイルの事前作成
  3. /settingsコマンドでの設定変更

環境変数はDockerでの実行時のみ有効です。

方法1: Ollama（完全ローカル・推奨）

インストール（2025年7月最新版）

# Linux/Mac/WSL
curl -fsSL https://ollama.com/install.sh | sh

# Windows (PowerShell管理者権限)
# winget install Ollama.Ollama

最新モデルの準備

# 2025年7月時点のおすすめモデル
ollama pull llama3.1:8b        # Llama 3.1 8B（最新・推奨）
ollama pull gemma2:9b          # Gemma 2 9B
ollama pull qwen2.5:7b         # Qwen 2.5 7B
ollama pull deepseek-coder-v2  # コード特化
ollama pull mistral:7b-v0.3    # Mistral最新版

# インストール済みモデルの確認
ollama list

OpenHandsでの設定

方法A: 設定ファイルを事前作成（推奨・ウィザードをスキップ）

~/.openhands/settings.jsonを作成：

{
  "llm_model": "ollama/llama3.1:8b",
  "llm_api_key": "ollama",
  "llm_base_url": "http://localhost:11434",
  "agent": "CodeActAgent",
  "language": "ja",
  "enable_default_condenser": true,
  "enable_sound_notifications": false,
  "enable_proactive_conversation_starters": true
}

その後、OpenHandsを起動：

openhands

方法B: 対話的設定（初回のみ）

openhands
# → "Select another provider" を選択
# → Provider: ollama
# → Model: llama3.1:8b
# → Base URL: http://localhost:11434
# → API Key: （空欄でEnter）

方法C: Docker実行（環境変数使用可）

docker run -it --rm \
  -e LLM_PROVIDER="ollama" \
  -e LLM_MODEL="llama3.1:8b" \
  -e LLM_BASE_URL="http://host.docker.internal:11434" \
  -v $(pwd):/workspace \
  ghcr.io/all-hands-ai/openhands:latest

方法2: Groq Cloud（無料枠・超高速）

2025年7月時点の利用可能モデル

無料枠（2025年7月時点）

OpenHandsでの設定

方法A: 設定ファイルを事前作成（推奨）

~/.openhands/settings.json：

{
  "llm_model": "groq/llama-3.1-70b-versatile",
  "llm_api_key": "gsk_あなたのAPIキー",
  "llm_base_url": null,
  "agent": "CodeActAgent"
}

方法B: Docker実行

docker run -it --rm \
  -e LLM_PROVIDER="groq" \
  -e LLM_MODEL="llama-3.1-70b-versatile" \
  -e LLM_API_KEY="gsk_..." \
  -v $(pwd):/workspace \
  ghcr.io/all-hands-ai/openhands:latest

方法3: Together AI（新規追加・$25無料クレジット）

2025年7月時点の利用可能モデル

設定ファイル（~/.openhands/settings.json）

{
  "llm_model": "together/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo",
  "llm_api_key": "your-together-api-key",
  "llm_base_url": null,
  "agent": "CodeActAgent"
}

設定の変更方法

OpenHands実行中に設定を変更する場合：

/settings
# 対話的に設定を変更

2025年7月版 モデル選択ガイド

ユースケース別推奨モデル

ユースケース 推奨モデル 理由
汎用コーディング Llama 3.1 8B 最新、バランス良好
高度なコード生成 DeepSeek-Coder-V2.5 コード特化、最新
日本語含む開発 Qwen2.5 7B/32B 日本語性能最高
超高速応答 Groq + Llama 3.1 8B クラウド最速
長文コンテキスト Llama 3.1（128K対応） 大規模プロジェクト
低スペックPC Gemma 2 2B 超軽量、高効率

システム要件（2025年7月更新）

モデル 最小RAM 推奨RAM GPU VRAM
Gemma 2 2B 4GB 8GB 3GB
Llama 3.1 8B 16GB 32GB 10GB
Gemma 2 9B 16GB 32GB 12GB
Qwen2.5 7B 16GB 32GB 10GB
DeepSeek-Coder 6.7B 12GB 24GB 8GB
Llama 3.1 70B 64GB 128GB 80GB

実践的な使用例（2025年7月版）

例1: Next.js 14 App Router開発

設定ファイル準備（~/.openhands/config.toml）：

[llm]
provider = "ollama"
model = "llama3.1:8b"
base_url = "http://localhost:11434"

使用例：

# OpenHands起動
openhands

# タスク例
> Create a Next.js 14 app with App Router, Server Components, and Tailwind CSS

例2: AI/MLパイプライン構築

Qwen2.5を使用（Python/MLに強い）：

[llm]
provider = "ollama"
model = "qwen2.5:7b"
base_url = "http://localhost:11434"

使用例：

openhands

# タスク例
> Build a machine learning pipeline with scikit-learn and pandas for data preprocessing

例3: マイクロサービスAPI開発

DeepSeek-Coder使用時：

# 実行中に設定変更
/settings
# → プロバイダー: ollama
# → モデル: deepseek-coder-v2

# タスク例
> Create a FastAPI microservice with async endpoints and Pydantic validation

例4: 複数プロジェクトでの使い分け

プロジェクトごとの設定ファイル：

# プロジェクト1用（Web開発）
mkdir -p ~/project1/.openhands
cat > ~/project1/.openhands/config.toml << EOF
[llm]
provider = "groq"
model = "llama-3.1-70b-versatile"
api_key = "gsk_..."
EOF

# プロジェクト2用（データ分析）
mkdir -p ~/project2/.openhands
cat > ~/project2/.openhands/config.toml << EOF
[llm]
provider = "ollama"
model = "qwen2.5:32b"
base_url = "http://localhost:11434"
EOF

# 各プロジェクトディレクトリで実行
cd ~/project1 && openhands  # Groqを使用
cd ~/project2 && openhands  # Ollamaを使用

パフォーマンス最適化（2025年版）

量子化オプション（メモリ削減）

# Q4量子化モデルの使用
ollama pull llama3.1:8b-q4_K_M  # 通常の1/4サイズ

# Q8量子化（品質重視）
ollama pull llama3.1:8b-q8_0

Flash Attention対応

# Flash Attention v2対応モデル
export OLLAMA_FLASH_ATTENTION=1

バッチ処理最適化

# ~/.openhands/config.toml
[performance]
batch_size = 8
max_concurrent_requests = 4
timeout = 300

トラブルシューティング（2025年版）

パフォーマンス問題の解決

極端に遅い処理速度（重要）

症状: OpenHandsでの応答が極端に遅い（30分ごとの出力など）
原因: コンテキスト長の設定ミス、スレッド数の未最適化
解決策:

  1. コンテキスト長の最適化（最重要） 
    # デフォルトの131072は遅すぎる
# 4096の倍数に設定
ollama run llama3.1:8b --context-size 24576
  2. スレッド数の最適化 
    # Ollama側で環境変数を設定
export OLLAMA_NUM_THREAD=20  # CPUコア数の80-90%
export OLLAMA_NUM_PARALLEL=2
export OLLAMA_MAX_LOADED_MODELS=1
   
# 永続的な設定（推奨）
sudo systemctl edit ollama.service

    systemdサービスファイルに追加：

    [Service]
Environment="OLLAMA_NUM_THREAD=20"
Environment="OLLAMA_NUM_PARALLEL=2"
Environment="OLLAMA_MAX_LOADED_MODELS=1"
  3. 量子化モデルの使用 
    # より高速な量子化モデル
ollama pull llama3.1:8b-q4_K_M
ollama pull gemma2:9b-q4_K_M
  4. OpenHands設定の最適化 
    {
  "llm_model": "ollama/llama3.1:8b-q4_K_M",
  "llm_api_key": "ollama",
  "llm_base_url": "http://localhost:11434",
  "max_iterations": 30
}

パフォーマンス診断コマンド

# CPU使用状況の詳細確認
htop  # または top -H

# Ollamaのステータス確認
ollama ps --verbose

# デバッグモード
OLLAMA_DEBUG=1 ollama serve

# GPU使用状況（NVIDIA）
watch -n 1 nvidia-smi

CUDA 12.x対応

# NVIDIA GPU最新ドライバー確認
nvidia-smi
# CUDA Version: 12.4以上推奨

# PyTorch 2.3+インストール
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

Apple Silicon最適化

# Metal Performance Shaders利用
export OLLAMA_METAL=1

# Unified Memory活用
export OLLAMA_UNIFIED_MEMORY=1

メモリ不足対策（最新）

# ページファイル/スワップ拡張
# Linux
sudo fallocate -l 32G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# モデルのアンロード
curl -X DELETE http://localhost:11434/api/models/llama3.1:8b

2025年の展望

今後リリース予定のモデル

技術トレンド

まとめ

2025年7月時点で、OpenHandsで使える高品質なオープンソースモデルは大幅に増加し、性能も向上しています。特に：

推奨構成（2025年7月版）：

  1. 標準開発環境: Ollama + Llama 3.1 8B（量子化モデル推奨）
  2. 日本語重視: Ollama + Qwen2.5 7B
  3. 高速クラウド: Groq + Llama 3.1 70B
  4. コード特化: Ollama + DeepSeek-Coder-V2.5

パフォーマンス最適化のポイント

  1. コンテキスト長: 24576（4096の倍数）に設定
  2. スレッド数: CPUコア数の80-90%をOLLAMA_NUM_THREADで設定
  3. 量子化モデル: q4_K_Mバリアントを使用
  4. 設定ファイル: OpenHandsのsettings.jsonで適切な設定

関連リンク

ライセンス情報