コードインタプリタ

コード・インタプリタを使用して、モデルがセキュアで分離されたコンテナでPythonコードを記述して実行できるようにします。このツールは、計算、データ分析、ファイル処理、およびその他の計算負荷の高いタスクに役立ちます。

ノート

OCIコード・インタプリタ・ツールは、OCI OpenAI互換エンドポイントとともにResponses APIで使用されるOpenAIコード・インタプリタ・ツールと同じ形式を使用します。構文およびリクエストの詳細は、OpenAIドキュメントのコード・インタプリタに関するトピックを参照してください。

ヒント

プロンプトで、コード・インタプリタをpythonツールとして参照します。例: Use the python tool to solve the problem.

コードは外部ネットワーク・アクセスのない分離された環境で実行されるため、制御された設定でワークフローに計算またはファイル処理が必要な場合、コード・インタプリタは適切なオプションです。

Code Intepreterの使用

これを初めて使用する場合は、コード・インタプリタをモデルの一時的なPythonワークスペースと考えてください。

次のようなタスクに使用できます。

数学の問題の解決
アップロードされたファイルの分析
データのクリーニングまたは変換
チャートまたは表の作成
ログや処理されたデータセットなどの出力ファイルの生成

実行環境

Python環境には、Pandas、Matplotlib、SciPyなどの420以上のプリインストールされたライブラリが含まれているため、多くの一般的なタスクは追加の設定なしで機能します。

コードはサンドボックス・コンテナ内で実行されます。このコンテナは、Pythonが実行され、アップロードされたファイル、生成されたファイルおよび一時作業データがセッション中に格納される作業環境です。

コンテナ・メモリー制限

コード・インタプリタ・コンテナは、テナンシ当たり64 GBの共有メモリー・プールを使用します。

サポートされているコンテナ・サイズは、次のとおりです。

1 GB
4 GB
16 GB
64 GB

この共有制限は、複数のコンテナに分割できます。たとえば、次のものをサポートできます。

64個の1 GBコンテナ
16個の4 GBコンテナ
16 GBコンテナ×4
1つの64 GBコンテナ

容量を増やす必要がある場合は、サービスリクエストを送信できます。

コンテナ失効

コンテナは、20分間非アクティブ後に期限切れになります。

これは、マルチステップ・フローを構築するタイミングを知ることが重要です。

期限切れのコンテナは再利用できません
新しいコンテナを作成する必要があります
必要に応じてファイルを再度アップロードする必要があります
Python変数やPythonオブジェクトなどのインメモリー状態は失われます

そのため、コンテナを一時的な作業環境として扱うのが最善です。

例

コード・インタプリタを使用するには、"type": "code_interpreter"を使用してtoolsプロパティにツール定義を追加します。

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    tools=[
        {
            "type": "code_interpreter",
            "container": {"type": "auto"}
        }
    ],
    instructions="Use the python tool to solve the problem and explain the result.",
    input="Find the value of (18 / 3) + 7 * 2."
)

print(response.output_text)

この例では、pythonツールはコード・インタプリタです。

コード・インタプリタのコンテナ

コード・インタプリタ・ツールにはコンテナ・オブジェクトが必要です。コンテナは、モデルがPythonコードを実行する分離された環境です。

コンテナは次のものを保持できます。

アップロード済ファイル
モデルによって作成されたファイル
実行中の一時作業データ

コード・インタプリタを使用する場合は、次の2つのコンテナ・モードのいずれかを使用できます。

自動: OCI Generative AIは、現在のコンテキストでコンテナをプロビジョニングまたは再利用します。
コンテナOCID: コンテナを自分で作成し、メモリー・サイズを定義して、OCIDを指定します。

どちらのオプションでも、コンテナはOCI Generative AIで作成および管理されます。これらのコンテナで実行されるコードは、OCI生成AIテナンシでも実行されます。

ノート

OCIコード・インタプリタ・ツールは、OCI OpenAI互換エンドポイントとともにResponses APIで使用されるOpenAIコード・インタプリタ・ツールと同じ形式を使用します。構文およびリクエストの詳細は、Containers for Code IntepretersおよびOpenAI Containers APIのドキュメントを参照してください。

自動モード

自動モードでは、サービスによってコンテナがプロビジョニングまたは再利用されます。これは最も簡単なオプションであり、ほとんどのユーザーにとって良い出発点です。

自動モードは次の場合に使用します。

OCI Generative AIでコンテナを管理したい
環境を直接制御する必要はありません。
より簡単な設定が必要

memory_limitは必要に応じて指定できます。指定しない場合、デフォルトは1 GBです。

response = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[{
        "type": "code_interpreter",
        "container": {
            "type": "auto",
            "memory_limit": "1g"
        }
    }],
    input="Use the python tool to calculate the mean, median, and standard deviation of 12, 18, 24, 30, and 42."
)

明示的モード

明示モードでは、最初にコンテナを作成し、サイズを設定します。次に、リクエストでコンテナIDを渡します。

メモリー・サイズなどのコンテナ設定をより詳細に制御する場合、または専用セッションを維持する場合は、明示モードを使用します。

container = client.containers.create(name="test-container", memory_limit="4g")

response = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[{
        "type": "code_interpreter",
        "container": container.id
    }],
    tool_choice="required",
    input="Use the python tool to calculate the mean, median, and standard deviation of 12, 18, 24, 30, and 42."
)

print(response.output_text)

コード・インタプリタ内のファイル

コード・インタプリタは、コンテナの存続期間中の動的ファイル相互作用をサポートします。モデルは、指定したファイルを読み取ることができ、新しいファイルを作成することもできます。

これは、次のようなワークフローに役立ちます。

CSVまたはPDFの読取り
チャートの生成
処理済出力の保存中
ログまたはレポートの作成

APIリファレンス: OpenAI Container Files APIのドキュメントおよびContainer Files API。

ファイルの永続性

pythonツールによって作成または更新されたファイルは、コンテナが期限切れになっていないかぎり、コードの実行後も同じコンテナに置かれます。

これは、モデルが同じセッションで以前の作業に基づいて構築できることを意味します。たとえば、次のことが可能です。

ファイルの読取り
解析する
チャートの保存
このチャートを後で同じコンテナで使用します

コンテナが期限切れになると、その状態は使用できなくなります。

ファイルのアップロードおよび管理

コンテナ・ファイルは、コンテナ・ファイルAPIを使用して管理できます。

一般的な操作は次のとおりです。

コンテナ・ファイルの作成: マルチパート・アップロードまたは既存の/v1/files IDを参照して、コンテナにファイルを追加します
コンテナ・ファイルのリスト: コンテナ内のファイルを表示します。
コンテナ・ファイルの削除: ファイルの削除
コンテナ・ファイル・コンテンツの取得: コンテナからファイルをダウンロードします

これにより、コンテナをモデルドリブン・コード実行の一時ワークスペースとして使用できます。

出力ファイルと引用

モデルでファイルが作成されると、それらのファイルはコンテナに格納され、レスポンスで注釈として返すことができます。

これらの注釈には、次のものを含めることができます。

container_id
file_id
filename

これらの値を使用して、生成されたファイルの内容を取得できます。

レスポンスには、生成されたファイルを識別するcontainer_file_citationオブジェクトを含めることができます。「コンテナ・ファイル・コンテンツの取得」操作を使用してファイルをダウンロードします。

OCIレスポンスAPIは、レスポンス、ファイル、コンテナ、コンテナ・ファイルなどの機能に対してOpenAI互換のエンドポイントをサポートします。関連するOpenAIドキュメントは、リクエスト構造、レスポンス形式および一般的なワークフローのリファレンスとして使用できます。これらのAPIをOCIで使用する場合、OCI生成AI推論エンドポイントにリクエストを送信し、OCI認証を使用し、リソースと実行はOpenAIテナンシではなくOCI生成AIに残ります。

ノート

OCIファイルAPIでは、OCI OpenAI互換エンドポイントを含むOpenAIファイルAPIと同じ形式が使用されます。構文およびリクエストの詳細は、OpenAI Files APIのドキュメントを参照してください。