vllm-mlx-expert

name	vllm-mlx-expert
description	vllm-mlx expert guidance — Apple Silicon native LLM inference server with MLX backend, OpenAI/Anthropic API, continuous batching, and model setup (LLM/VLM/Audio/Embeddings/Reasoning).

vllm-mlx Expert

Apple Silicon 向けの vLLM ライクな推論サーバー。MLX バックエンドで GPU 加速し、OpenAI / Anthropic 互換 API を提供する。

GitHub: https://github.com/waybarrios/vllm-mlx ローカルリポジトリ: /Users/zeero/dev/vllm-mlx

インストール

git clone https://github.com/waybarrios/vllm-mlx.git
cd vllm-mlx
uv pip install -e .        # uv 推奨

# オプション依存
pip install -e ".[vision]"   # 動画処理
pip install mlx-audio        # TTS/STT
pip install mlx-embeddings   # Embeddings

動作確認:

vllm-mlx --help
uname -m  # arm64 であること

サーバー起動

# 基本
vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit --port 8000

# Continuous Batching（高スループット・並列リクエスト向け）
vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit --port 8000 --continuous-batching

# API キー設定
vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit --port 8000 --api-key your-secret-key

# Reasoning モデル
vllm-mlx serve mlx-community/Qwen3-8B-4bit --reasoning-parser qwen3

# Embeddings 同時起動
vllm-mlx serve mlx-community/Llama-3.2-3B-Instruct-4bit \
  --embedding-model mlx-community/all-MiniLM-L6-v2-4bit

API 利用

OpenAI SDK

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Hello!"}],
)

Anthropic SDK / Claude Code

from anthropic import Anthropic
client = Anthropic(base_url="http://localhost:8000", api_key="not-needed")

response = client.messages.create(
    model="default",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello!"}]
)

Claude Code から接続:

export ANTHROPIC_BASE_URL=http://localhost:8000
export ANTHROPIC_API_KEY=not-needed
claude

モデルタイプ別ガイド

詳細は references/models.md を参照（モデル選択・VLM・Reasoning・Audio・Embeddings）。 サーバー詳細設定・MCP・パフォーマンスは references/server.md を参照。

コードベース構造

vllm_mlx/
├── server.py     # FastAPI サーバー（エントリポイント）
├── engine.py     # 推論エンジン抽象レイヤー
├── mllm.py       # マルチモーダル処理
└── models/       # モデル別ハンドラー

docs/
├── getting-started/   # インストール・クイックスタート
├── guides/            # 機能別ガイド
└── reference/         # CLI・設定リファレンス

トラブルシューティング

問題	対処
MLX not found	uname -m が arm64 か確認
OOM	より小さい量子化モデルに変更（例: 4bit → 3bit）
HuggingFace ダウンロード失敗	huggingface-cli login で認証
Gemma 3 VLM エラー	GEMMA3_SLIDING_WINDOW=8192 環境変数を設定
MLLM message null エラー	exclude_none=True が適用されているか確認（mllm.py）