> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OGX

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

OGX は、以下の 2 つの主要コンポーネントで構成されています。

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

## 前提条件

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

* [SambaCloud アカウント](https://cloud.sambanova.ai?utm_source=ogx\&utm_medium=external\&utm_campaign=cloud_signup)
* [SambaNova API キー](https://cloud.sambanova.ai/apis?utm_source=ogx\&utm_medium=external\&utm_campaign=cloud_signup)
* Python 3.12 以上がインストールされたマシン

## セットアップ

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

<Steps>
  <Step title="Python 仮想環境のセットアップ">
    ```bash theme={}
    python -m venv .venv
    source .venv/bin/activate
    ```
  </Step>

  <Step title="必要な依存パッケージのインストール">
    ```bash theme={}
    pip install uv
    uv pip install "ogx[starter]"
    ```
  </Step>

  <Step title="必要な環境変数のエクスポートとサーバーの起動">
    ```bash theme={}
    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.` と表示して終了します。
  </Step>
</Steps>

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

```bash theme={}
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 クライアントのインストール

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

```bash theme={}
pip install ogx-client
```

## サンプルコード

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

```python theme={}
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 連携リポジトリ](https://github.com/sambanova/integrations/tree/main/ogx) をご覧ください。

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

<AccordionGroup>
  <Accordion title="TLS required">
    TLS が設定されていない場合、サーバーは起動を拒否します。

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

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

  <Accordion title="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 コンソール](https://cloud.sambanova.ai/apis?utm_source=ogx\&utm_medium=external\&utm_campaign=cloud_signup)の有効なキーと一致していることを確認してください。
  </Accordion>

  <Accordion title="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 より古いことが原因です。
  </Accordion>

  <Accordion title="ポートが使用中でサーバーが起動時に終了する">
    別のプロセスが `$OGX_PORT` を使用しています。該当プロセスを特定し、停止するか、空いているポートを選択してください。

    ```bash theme={}
    lsof -i :$OGX_PORT
    export OGX_PORT=8322
    ```

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

## 参考情報

以下の内容については、[OGX ドキュメント](https://ogx-ai.github.io/docs) をご参照ください。

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