クイック・スタート

プロジェクトを作成するか、OCIレスポンスAPIをコールする前に、必要なIAM権限が設定されていることを確認してください。

OCIレスポンスAPIでは、2つの認証方法がサポートされています。いずれのオプションも使用できます。

• OCI生成AI APIキー

  OpenAI互換の生成AIサービス固有のAPIキーを使用して、モデルとエンドポイントを認証し、アクセスします。このオプションは、テストおよび早期開発に使用します。

• OCI IAMベースの認証

  署名付きAPIリクエストを使用して、モデルおよびエンドポイントを認証し、アクセスします。このオプションは、本番ワークロードおよびOCI管理環境にお薦めします。次の場合は、IAM認証の使用を検討してください:

  • FunctionsやOracle Kubernetes Engine (OKE)などのOCIサービスでのアプリケーションの実行
  • 長期間のAPIキーを回避したい
  • OCI IAMによる一元的なアクセス制御が必要

公式のOpenAI SDKをインストールします。

Python

pip install openai

その他の言語については、OpenAIライブラリ・ページを参照してください。

OCI Responses APIは、OCI Generative AIでエンタープライズAIエージェント・アプリケーションを構築するための主要なAPIです。これにより、モデル・リクエストの送信、ツールの使用、および単一のAPIを介した会話コンテキストの管理が可能になります。

レスポンスAPIを使用して、次のことを行います。

• シンプルで単一ステップの推論またはマルチステップのエージェント・ワークフローを実行
• ユース・ケースに応じて推論を有効または無効にします。
• プラットフォーム管理ツールまたはクライアント側ツールの統合
• サービス内またはクライアント内の会話状態の管理

OCI Responses APIは、OpenAI互換インタフェースを使用します。リクエストは同じOpenAIスタイルの構文を使用しますが、これらはOCI生成AIに送信され、OCI生成AI APIキーやOCI IAMベースの認証などのOCI資格証明で認証されます。

推奨されるクライアントは、OpenAI SDKです。Python、Java、TypeScript、Go、.NETなどの言語をサポートしています。また、LangChain、LlamaIndex、OpenAI Agents SDKなどのフレームワークでも使用できます。

次のベースURLを使用します。

ベースURL: https://inference.generativeai.${region}.oci.oraclecloud.com/openai/v1

${region}をOCIリージョン(us-chicago-1など)に置き換えます。

レスポンスAPIでは、次のエンドポイント・パスを使用します:

/responses

OCI Responses APIを使用して、OCI Generative AIでサポートされているリージョンで使用可能な様々なタイプのモデルをコールできます。サポートされているモデルおよびリージョンのリストは、エージェント・モデルおよびリージョンを参照してください。

response = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    input="Write a one-sentence explanation of what a database is."
)

response = client.responses.create(
    model="google.gemini-2.5-pro",
    input="Write a one-sentence explanation of what a database is."
)

response = client.responses.create(
    model="<dedicated-ai-cluster-endpoint-ocid>",
    input="Write a one-sentence explanation of what a database is."
)

使用可能なリージョンでモデルを選択し、パフォーマンス、コストおよびコントロールの要件に最も適した使用可能なモードにします。

次の例は、Pythonを使用してResponses APIをコールする方法を示しています。リクエストから説明が返された場合、OCIレスポンスAPIは正常に動作しています。

APIのコール時に問題が発生した場合は、デバッグ・ロギングを有効にすると、トラブルシューティングに役立ちます。デバッグ・ログには、RAW HTTPリクエストおよびレスポンス(opc-request-idなど)が表示されます。これは、Oracleサポートの使用時に役立ちます。

問題をレポートする際にこのリクエストIDを参照して、問題をより迅速に識別および診断できます。

from openai import OpenAI
import logging

logger = logging.getLogger("openai")
logger.setLevel(logging.DEBUG)
logger.addHandler(logging.StreamHandler())

# Create and use the OpenAI client as usual
client = OpenAI(
    ...
)

OCI Responses APIはストリーミングをサポートしており、トークンが生成されるとモデル出力を段階的に受信できます。

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data.",
    stream=True
)

for event in response_stream:
    print(event)

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data.",
    stream=True
)

for event in response_stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

推論コントロールを使用すると、応答を生成する前にモデルが使用する労力を調整できます。これは、速度、深さ、または両方のバランスに優先順位を付ける場合に役立ちます。

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Solve 18 * (4 + 2).",
    reasoning={"effort": "medium"},
    store=False,
)

print(response.output_text)

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Solve 18 * (4 + 2).",
    reasoning={"summary": "auto"},
    store=False,
)

print(response.output_text)

モデルで自由形式テキストではなく予測可能な形式でデータを返す場合は、構造化出力を使用します。これは、非構造化入力からフィールドを抽出したり、結果を他のシステムに渡したり、UIに特定の値を表示する場合に便利です。OCIレスポンスAPIでは、スキーマを定義し、それに対するレスポンスを解析することで、アプリケーションの出力の一貫性と使いやすさを向上させます。構造化出力は指定されたスキーマと一致しますが、JSONモードでは有効なJSONのみが保証されます。

強い型指定オブジェクトは、フィールドとデータ型が事前に定義されているオブジェクトです。たとえば、スキーマでcustomer_nameが文字列である必要があり、priorityが"low"、"medium"または"high"のいずれかである必要がある場合、解析された結果はその構造に従います。これにより、コードがレスポンスを安全かつ予測可能な方法で処理しやすくなります。OCIレスポンスAPIでは、スキーマを定義し、モデル出力を強く型指定されたオブジェクトに解析できるようにすることで、これをサポートしています。

このアプローチは、ダウンストリーム・システムとの統合、一貫性の強制、または自然言語入力から特定のフィールドの抽出を行う場合に役立ちます。

from pydantic import BaseModel
from typing import Literal

class SupportRequest(BaseModel):
    customer_name: str
    product: str
    issue_summary: str
    priority: Literal["low", "medium", "high"]
    requested_action: str

response = client.responses.parse(
    model="<supported-model-id>",
    input=[
        {"role": "system", "content": "Extract the support request into the schema."},
        {
            "role": "user",
            "content": (
                "Sarah Johnson from Example Company says the mobile inventory app "
                "crashes whenever she scans more than 20 items in one session. "
                "This is delaying warehouse processing, and she wants a fix as soon as possible."
            ),
        },
    ],
    text_format=SupportRequest,
)

support_request = response.output_parsed
print(support_request)

出力例:

SupportRequest(
customer_name='Sarah Johnson', 
product='mobile inventory app', 
issue_summary='App crashes whenever she scans more than 20 items in one session.', 
priority='high', 
requested_action='Provide a fix as soon as possible'
)

OCIレスポンスAPIは、マルチモーダル入力を受け入れるモデルをサポートしています。テキストをイメージ、ファイル、推論コントロールと組み合せて、ドキュメント分析、イメージの理解、より慎重なモデル・レスポンスなどのより豊富なワークフローをサポートできます。

import base64

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

base64_image = encode_image("/path/to/image.png")

response = client.responses.create(
    model="google.gemini-2.5-pro",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe the main objects in this image."},
                {
                    "type": "input_image",
                    "image_url": f"data:image/jpeg;base64,{base64_image}",
                    "detail": "high",
                },
            ],
        }
    ],
)

print(response.output_text)

response = client.responses.create(
    model="google.gemini-2.5-pro",
    store=False,
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Describe the scene shown in this image."},
                {
                    "type": "input_image",
                    "image_url": "https://example.photos/id/123",
                },
            ],
        }
    ],
)

print(response.output_text)

file = client.files.create(
    file=open("<path-to-file>", "rb"),
    purpose="user_data"
)

response = client.responses.create(
    model="google.gemini-2.5-pro",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "file_id": file.id,
                },
                {
                    "type": "input_text",
                    "text": "Summarize this document.",
                },
            ]
        }
    ]
)

print(response.output_text)

response = client.responses.create(
    model="google.gemini-2.5-flash",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Summarize this file."},
                {
                    "type": "input_file",
                    "file_url": "https://www.example.com/letters/example-letter.pdf",
                },
            ],
        }
    ],
)

print(response.output_text)

レスポンスAPIにファイル検索ツールを追加すると、モデルはレスポンス生成時にベクトル・ストアに格納されているファイルからコンテンツを取得できます。これは、モデルの組込みナレッジのみに依存するのではなく、指定したドキュメントにレスポンスが反映されるようにする場合に便利です。

ベクトル・ストアを作成し、それらにファイルを追加することで、データ全体でセマンティックおよびキーワードベースの検索を有効にします。これにより、モデルの組込みナレッジがカスタム・コンテンツで拡張され、より正確でコンテキスト対応の回答を生成できます。

ファイル検索はサービスによって処理されるため、アプリケーションは独自の取得パイプラインを実装する必要はありません。

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Summarize the main ideas covered in the documents in this vector store.",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["<vector_store_id>"]
        }
    ]
)

print(response)

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

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

ファンクション・コールを使用して、レスポンスAPIワークフロー中にモデルがアプリケーションからデータまたはアクションをリクエストできるようにします。これは、カレンダ・データ、内部アプリケーションの状態、カスタム操作の結果など、プロンプト自体で使用できない情報または操作をモデルが必要とする場合に便利です。

このパターンでは、モデルは関数を直接実行しません。かわりに、関数名と引数が返され、アプリケーションによって関数が実行されてから、モデルを続行してユーザー対応の回答を生成できるように、アプリケーションが関数出力を返送します。

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

# Initial request
response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input="Show the calendar events for 2026-04-02.",
)

# Execute the requested function
tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        tool_outputs.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

# Follow-up request
final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=tool_outputs,
    previous_response_id=response.id,
)

print(final.output_text)

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

conversation = [
    {"role": "user", "content": "Show the calendar events for 2026-04-02."}
]

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input=conversation,
)

conversation += response.output

for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        conversation.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=conversation,
)

print(final.output_text)

"tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
        { "type": "function", "name": "get_calendar_events" },
        { "type": "function", "name": "purchase_tickets" }
    ]
  }
}

MCP (Model Context Protocol)ツールは、AIモデルが外部システムと対話するために使用できる実行可能関数または機能です。OCI生成AIでMCPコールを使用して、Responses APIリクエスト中にリモートMCPサーバーによって公開される実行可能ツールにモデルがアクセスできるようにします。これらのツールは、API、データベース、ファイル・システム、アプリケーション・エンドポイントなどの外部システムへのアクセスを提供できます。OCI Generative AIは、リクエスト・ワークフローの一環として、リモートMCPサーバーと直接通信します。

SQL検索(NL2SQL)を使用して、自然言語リクエストをOCI生成AIのエンタープライズ・データの検証済SQLに変換します。

NL2SQLは、エンタープライズAIエージェントが、基礎となるデータを移動または複製することなく、フェデレーテッド・エンタープライズ・データを操作するのに役立ちます。セマンティック・エンリッチメント・レイヤーを使用して、ビジネス用語をデータベース表、列および結合にマップし、自然言語入力からSQLを生成します。

NL2SQLを使用する前に、次のものが必要です。

• Oracle Autonomous Databaseなどのソース・データベース
• 2つのDBTools接続:
  • エンリッチメントの接続
  • クエリー接続
• セマンティック・ストア、NL2SQL、データベース・ツールおよびシークレットのIAM権限
• このクイックスタートで使用されるOCIサービスAPI用に構成されたOCI IAM認証

セマンティック・ストアを作成する前に、ソース・データベースおよび必要なDBTools接続を作成します。

次の接続が必要です。

セマンティック・ストアを作成する前に、必要なIAMポリシーを設定します。

このQuickStartでは、セマンティック・ストアの作成、エンリッチメント・ジョブの実行およびSQLの生成を行うOCIサービスAPIにOCI IAM認証を使用します。

リクエストに署名するアイデンティティのOCI IAM認証を設定します。この項の例では、OCI Python SDKおよびBaseClientを使用します。

次のものを使用して認証できます。

• OCI構成ファイルおよびAPI署名キー
• セキュリティ・トークン署名者

次の例では、SecurityTokenSignerを使用しますが、環境に適合する場合は、標準のOCI構成署名者を使用することもできます。

関連トピック

• SDKおよびCLIの構成ファイル
• 署名の要求
• 署名者Python SDK

「自動化」で、「作成時」のかわりに「なし」を選択した場合、セマンティック・ストアの作成後にエンリッチメントを実行できます。「作成時」オプションをスキップした場合は、このステップを実行します。

エンリッチメント・プロセスは、接続されたデータベースから表や列などのスキーマ・メタデータを読み取ります。OCI生成AIでは、このメタデータを使用してSQLを生成できます。

エンリッチメントを手動でトリガーするには、GenerateEnrichmentJob APIをコールします。

次のAPIを使用して、エンリッチメント・ジョブを管理することもできます。

• ListEnrichmentJobs
• GetEnrichmentJob
• CancelEnrichmentJob

NL2SQLでは、OCI OpenAI互換の/openai/v1パスではなく、OCIサービスAPIを使用します。

セマンティック・ストアの準備が完了し、エンリッチメントが完了したら、NL2SQL APIをコールして自然言語からSQLを生成します。

import json
import oci
from oci.base_client import BaseClient

INFERENCE_BASE_URL = "https://inference.generativeai.<region>.oci.oraclecloud.com"
API_VERSION = "20260325"
SEMANTIC_STORE_ID = "ocid1.generativeaisemanticstore.oc1.xxx"

config = oci.config.from_file("~/.oci/config", "oc1")
signer = oci.auth.signers.SecurityTokenSigner(config)

client = BaseClient(
    service_endpoint=INFERENCE_BASE_URL,
    signer=signer,
    retry_strategy=None,
)

resource_path = (
    f"/{API_VERSION}/semanticStores/{SEMANTIC_STORE_ID}/actions/generateSqlFromNl"
)

body = {
    "displayName": "Generate SQL example",
    "description": "Generate SQL from natural language",
    "inputNaturalLanguageQuery": "Give me last week's order details."
}

resp = client.call_api(
    resource_path=resource_path,
    method="POST",
    header_params={"content-type": "application/json"},
    body=body,
)

print("HTTP status:", resp.status)
print("opc-request-id:", resp.headers.get("opc-request-id"))

data = resp.data
if isinstance(data, (bytes, str)):
    data = json.loads(data)

print(json.dumps(data, indent=2))

OCI Responses APIの組込みレスポンス・トレース・データを使用して、リクエストの処理方法を理解します。より詳細な可観測性のために、OCI Responses APIをLangfuseなどの外部可観測性プラットフォームと統合することもできます。

このQuickStartでは、Responses APIによって返された実行詳細を検査する方法と、Langfuseを使用してリクエストをトレースする方法を示します。

開始する前に、次のことが必要です:

• OCI Generative AIプロジェクト
• OCIレスポンスAPI用に構成された認証
• OpenAI SDKがインストールされている
• 動作中のOCIレスポンスAPIクライアント

(オプション) Langfuseと統合するには、Langfuseアカウントと資格証明が必要です。

OCIレスポンスAPIをコールすると、レスポンスにoutputフィールドが含まれます。このフィールドは、リクエスト中に発生した内容を説明するアイテムの配列です。

各項目は、実行のステップを表し、次のような様々なタイプを含めることができます。

• message
• file_search_call
• mcp_call

これらの出力アイテムにより、リクエストの処理方法が可視化されます。これらを使用して、次のことができます。

• モデル動作のデバッグと理解
• ユーザー・インタフェースでの実行ステップの表示
• カスタムの可観測性またはロギング・ワークフローの構築

たとえば、リクエストを送信した後、outputフィールドを検査できます。

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Explain the difference between structured and unstructured data."
)

for item in response.output:
    print(item.type)

レイテンシ、コスト、実行トレースなどのより深いインサイトを得るには、OCI Responses APIを可観測性プラットフォームと統合します。

1つのオプションはLangfuseです。これは、開発者がLLMアプリケーションをデバッグ、監視、改善するのに役立つオープンソースのLLMエンジニアリング・プラットフォームです。Langfuseは、エージェント・アクションをトレースするためのエンドツーエンドの可観測性を提供し、迅速なバージョニングをサポートし、モデル出力の評価を支援します。OpenAI、LangChain、LlamaIndexなどの一般的なフレームワークと統合されます。

Langfuse SDKをインストールします。

pip install langfuse

必要なLangfuseおよびOCI環境変数を設定します。

LANGFUSE_SECRET_KEY="sk-lf-xxxxxxxxx"
LANGFUSE_PUBLIC_KEY="pk-lf-xxxxxxxxx"
LANGFUSE_BASE_URL="https://us.cloud.langfuse.com"

# OCI Generative AI credentials
OCI_GENAI_API_KEY="sk-xxxxxxxxx"
OCI_GENAI_PROJECT_ID="ocid1.generativeaiproject.oc1.xxx"

Langfuse SDKからOpenAIクライアントをインポートします。既存のリクエスト・コードは同じままですが、リクエストは自動的にトレースされます。

import os
from langfuse.openai import OpenAI  # Import from Langfuse

client = OpenAI(
    base_url="https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1",
    api_key=os.getenv("OCI_GENAI_API_KEY"),
    project=os.getenv("OCI_GENAI_PROJECT_ID"),
)

クライアントをインストゥルメントした後、通常どおりResponses APIリクエストを送信します。Langfuseは自動的に要求をトレースします。

例:

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_label": "dmcp",
            "server_url": "https://mcp.example.com/mcp",
            "require_approval": "never",
        },
    ],
    input="Explain why tracing and observability are important in distributed systems."
)

print(response.output_text)