OGX

本ガイドでは、AI アプリケーションを構築するためのオープンソースの OpenAI 互換 API サーバーである OGX のセットアップと使用方法を解説します。OGX (旧称 Llama Stack) は、あらゆるモデル・あらゆるインフラで動作する標準化されたインターフェースを提供します。SambaNova ディストリビューションサーバーの起動、クライアントのインストール、初回のモデル推論の実行までを順番に説明します。 OGX は、以下の 2 つの主要コンポーネントで構成されています。

サーバー – 推論プロバイダーと API アダプターをホストする、稼働中のディストリビューション
クライアント – サーバーの API を利用し、ホストされたアダプターと対話するコンポーネント

前提条件

作業を始める前に、以下の環境を準備してください。

SambaCloud アカウント
SambaNova API キー
Python 3.12 以上がインストールされたマシン

セットアップ

オプション 1: uv でインストールして実行 (推奨)

Python 仮想環境のセットアップ

python -m venv .venv
source .venv/bin/activate

必要な依存パッケージのインストール

pip install uv
uv pip install "ogx[starter]"

必要な環境変数のエクスポートとサーバーの起動

export OGX_PORT=8321
export SAMBANOVA_API_KEY="your-api-key-here"

uv run ogx run starter --port $OGX_PORT --insecure

--insecure フラグは、ローカル開発向けに TLS を無効化します。このフラグを付けない場合、サーバーは TLS required: set tls_certfile/tls_keyfile in server config or pass '--insecure' to disable. と表示して終了します。

オプション 2: Docker で実行

export OGX_PORT=8321
export SAMBANOVA_API_KEY="your-api-key-here"

docker run -it \
  -p $OGX_PORT:$OGX_PORT \
  -v ~/.ogx:/root/.ogx \
  -e SAMBANOVA_API_KEY=$SAMBANOVA_API_KEY \
  ogxai/distribution-starter \
  --port $OGX_PORT \
  --insecure

OGX クライアントのインストール

どちらのオプションでも、以下の例を実行するにはクライアントが必要です。同じ環境または別の環境で、以下のコマンドを実行します。

pip install ogx-client

サンプルコード

以下の Python コードは基本的な使用方法を示しています。

from ogx_client import OgxClient

OGX_PORT = 8321
client = OgxClient(base_url=f"http://localhost:{OGX_PORT}")

# List all available models
models = client.models.list()
print("--- Available models: ---")
for m in models.data:
    print(f"- {m.id}")
print()

# Choose a model from the list
model = "sambanova/Meta-Llama-3.3-70B-Instruct"

# Run chat completion
response = client.chat.completions.create(
    model=model,
    messages=[
        {"role": "system", "content": "You are a friendly assistant."},
        {"role": "user", "content": "Write a two-sentence poem about llamas."},
    ],
)

print(response.choices[0].message.content)

このコードでは、接続、モデルの一覧表示、推論の実行という、クライアントとサーバー間の一連の流れを確認できます。 SambaNova ディストリビューションの LLM、Embedding、ツール、エージェントアダプターを用いたさまざまなユースケースについては、SambaNova OGX 連携リポジトリをご覧ください。

トラブルシューティング

TLS required

TLS が設定されていない場合、サーバーは起動を拒否します。

TLS required: set tls_certfile/tls_keyfile in server config or pass '--insecure' to disable.

上記のセットアップ手順のとおり、サーバーの起動コマンドに --insecure フラグを追加してください。共有環境や本番環境で実行する場合は、代わりに TLS 証明書を使用してください。

Incorrect API key provided

キーは SambaCloud に到達しましたが、拒否されました。

Incorrect API key provided: ... You can find your API key at https://cloud.sambanova.ai/apis

クライアントを実行している環境だけでなく、サーバーが動作している環境で SAMBANOVA_API_KEY がエクスポートされていること、そしてそのキーが SambaCloud コンソールの有効なキーと一致していることを確認してください。

Package 'ogx' requires a different Python

pip がインストール自体を拒否します。

ERROR: Package 'ogx' requires a different Python: 3.11.x not in '>=3.12'

ogx には Python 3.12 以降が必要です。python3.12 -m venv .venv のように、インタープリターを明示して仮想環境を作成してください。多くの場合、システムの python3 が 3.12 より古いことが原因です。

ポートが使用中でサーバーが起動時に終了する

別のプロセスが $OGX_PORT を使用しています。該当プロセスを特定し、停止するか、空いているポートを選択してください。

lsof -i :$OGX_PORT
export OGX_PORT=8322

uv run と docker run のどちらのコマンドも $OGX_PORT を参照するため、他に変更は不要です。

参考情報

以下の内容については、OGX ドキュメントをご参照ください。

基本概念の理解
サンプルアプリケーションの紹介
フレームワークの拡張・カスタマイズ方法

概要

開発者ツール

フレームワーク

インターフェースとローコード

データとインフラ

マルチモーダル

評価とモニタリング

前提条件

セットアップ

オプション 1: uv でインストールして実行 (推奨)

オプション 2: Docker で実行

OGX クライアントのインストール

サンプルコード

トラブルシューティング

参考情報

​前提条件

​セットアップ

​オプション 1: uv でインストールして実行 (推奨)

​オプション 2: Docker で実行

​OGX クライアントのインストール

​サンプルコード

​トラブルシューティング

​参考情報

前提条件

セットアップ

オプション 1: uv でインストールして実行 (推奨)

オプション 2: Docker で実行

OGX クライアントのインストール

サンプルコード

トラブルシューティング

参考情報