Início Rápido

Antes de criar um projeto ou chamar a API de Respostas do OCI, certifique-se de que as permissões necessárias do IAM estejam em vigor.

A API de Respostas do OCI suporta dois métodos de autenticação. Você pode usar qualquer uma das opções.

• Chaves de API do OCI Generative AI

  Autentique e alcance os modelos e pontos finais com chaves de API específicas do serviço Generative AI compatíveis com OpenAI. Use esta opção para teste e desenvolvimento inicial.

• Autenticação baseada no OCI IAM

  Autentique e alcance os modelos e pontos finais usando solicitações de API assinadas. Recomendamos essa opção para cargas de trabalho de produção e ambientes gerenciados pela OCI. Considere o uso da autenticação IAM quando você:

  • Execute aplicativos em serviços do OCI, como Functions ou Oracle Kubernetes Engine (OKE)
  • Deseja evitar chaves de API de longa duração
  • Precisa de controle de acesso centralizado por meio do OCI IAM

Instale o OpenAI SDK oficial.

Python

pip install openai

Para outros idiomas, consulte a página Bibliotecas OpenAI.

A API de Respostas da OCI é a principal API para criar aplicações agênticas de IA empresarial na OCI Generative AI. Ele permite que você envie solicitações de modelo, use ferramentas e gerencie o contexto da conversa por meio de uma única API.

Use a API de Respostas para:

• Execute fluxos de trabalho simples de inferência de etapa única ou de agente de várias etapas
• Ativar ou desativar argumentos, dependendo do caso de uso
• Integre ferramentas gerenciadas pela plataforma ou do lado do cliente
• Gerenciar o estado da conversa no serviço ou no cliente

A API OCI Responses usa uma interface compatível com OpenAI. As solicitações usam a mesma sintaxe no estilo OpenAI, mas são enviadas para o OCI Generative AI e autenticadas com credenciais do OCI, como chaves de API do OCI Generative AI ou autenticação baseada no OCI IAM.

O cliente recomendado é o OpenAI SDK. Suporta linguagens como Python, Java, TypeScript, Go e .NET. Você também pode usá-lo com frameworks como LangChain, LlamaIndex e OpenAI Agents SDK.

Use o seguinte URL base:

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

Substitua ${region} pela sua região do OCI, por exemplo, us-chicago-1.

Para a API de Respostas, use o seguinte caminho de ponto final:

/responses

Você pode usar a API de Respostas do OCI para chamar diferentes tipos de modelos disponíveis nas regiões suportadas pelo OCI Generative AI. Para obter uma lista de modelos e regiões suportados, consulte Modelos e Regiões do Agente.

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."
)

Selecione um modelo em uma região disponível, com o modo disponível que melhor se adapta às suas necessidades de desempenho, custo e controle.

Os exemplos a seguir mostram como chamar a API de Respostas usando Python. Se a solicitação retornar uma explicação, a API de Respostas do OCI estará funcionando corretamente.

Se você encontrar problemas ao chamar a API, ativar o registro em log de depuração pode ajudar na solução de problemas. Os logs de depuração exibem as solicitações e respostas HTTP brutas, incluindo o opc-request-id, que é útil ao trabalhar com o suporte da Oracle.

Você pode fazer referência a esse ID de solicitação ao relatar problemas para ajudar a identificar e diagnosticar problemas mais rapidamente.

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(
    ...
)

A API de Respostas do OCI suporta streaming, onde você pode receber saídas de modelo de forma incremental à medida que os tokens são gerados.

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)

Os controles de raciocínio permitem ajustar quanto esforço o modelo usa antes de produzir uma resposta. Isso é útil quando você quer priorizar velocidade, profundidade ou um equilíbrio de ambos.

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)

Use saídas estruturadas quando quiser que o modelo retorne dados em um formato previsível, em vez de texto de formato livre. Isso é útil para extrair campos de entrada não estruturada, transmitir resultados para outros sistemas ou mostrar valores específicos em uma IU. Na API de Respostas do OCI, você define um esquema e faz parsing da resposta em relação a ele, o que torna a saída mais consistente e fácil para os aplicativos usarem. Saídas estruturadas correspondem a um esquema fornecido, enquanto um modo JSON só garante JSON válido.

Objeto fortemente digitado é um objeto cujos campos e tipos de dados são definidos com antecedência. Por exemplo, se um esquema disser que customer_name deve ser uma string e priority deve ser um dos seguintes "low", "medium" ou "high", o resultado analisado seguirá essa estrutura. Isso facilita o trabalho do código com a resposta de forma segura e previsível. A API de Respostas do OCI suporta isso, permitindo que você defina um esquema e faça parsing da saída do modelo em objetos fortemente digitados.

Essa abordagem é útil na integração com sistemas downstream, na aplicação da consistência ou na extração de campos específicos da entrada de linguagem natural.

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)

Exemplo de saída:

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'
)

A API de Respostas do OCI suporta modelos que aceitam entradas multimodais. Você pode combinar texto com imagens, arquivos e controles de raciocínio para oferecer suporte a fluxos de trabalho mais ricos, como análise de documentos, compreensão de imagens e respostas de modelos mais deliberadas.

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)

Quando você adiciona a ferramenta Pesquisa de Arquivos à API Respostas, o modelo pode recuperar conteúdo de arquivos armazenados em um armazenamento de vetores durante a geração da resposta. Isso é útil quando você deseja que as respostas reflitam os documentos fornecidos, em vez de depender apenas do conhecimento integrado do modelo.

Ao criar armazenamentos de vetores e adicionar arquivos a eles, você ativa a pesquisa baseada em semântica e palavra-chave em seus dados. Isso amplia o conhecimento integrado do modelo com seu conteúdo personalizado e ajuda a produzir respostas mais precisas e sensíveis ao contexto.

Como a Pesquisa de Arquivos é tratada pelo serviço, seu aplicativo não precisa implementar seu próprio pipeline de recuperação.

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)

Use o Code Interpreter para permitir que o modelo grave e execute código Python em um contêiner seguro e isolado. Esta ferramenta é útil para cálculos, análise de dados, processamento de arquivos e outras tarefas pesadas em computação.

Como o código é executado em um ambiente isolado sem acesso externo à rede, o Code Interpreter é uma boa opção quando o fluxo de trabalho precisa de computação ou processamento de arquivos em uma configuração controlada.

Use Chamada de Função para permitir que o modelo solicite dados ou ações do seu aplicativo durante um workflow de API de Respostas. Isso é útil quando o modelo precisa de informações ou operações que não estão disponíveis no próprio prompt, como dados de calendário, estado do aplicativo interno ou o resultado de uma operação personalizada.

Com este padrão, o modelo não executa a função diretamente. Em vez disso, ele retorna o nome da função e os argumentos, seu aplicativo executa a função e, em seguida, seu aplicativo envia a saída da função de volta para que o modelo possa continuar e produzir a resposta voltada para o usuário.

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" }
    ]
  }
}

As ferramentas MCP (Model Context Protocol) são funções executáveis ou recursos que os modelos de IA podem usar para interagir com sistemas externos. Use o MCP Calling no OCI Generative AI para permitir que um modelo acesse ferramentas executáveis expostas por um servidor MCP remoto durante uma solicitação de API de Respostas. Essas ferramentas podem fornecer acesso a sistemas externos, como API, bancos de dados, sistemas de arquivos ou pontos finais de aplicativos. A OCI Generative AI se comunica diretamente com servidores MCP remotos como parte do fluxo de trabalho de solicitação.

Use a Pesquisa SQL (NL2SQL) para converter solicitações de linguagem natural em SQL validada para dados empresariais na OCI Generative AI.

O NL2SQL ajuda os Enterprise AI Agents a trabalhar com dados corporativos federados sem mover ou duplicar os dados subjacentes. Ele usa uma camada de enriquecimento semântico para mapear termos de negócios para tabelas de banco de dados, colunas e junções e, em seguida, gera SQL com base na entrada de linguagem natural.

Antes de usar o NL2SQL, você deve ter:

• Um banco de dados de origem, como o Oracle Autonomous Database
• Duas conexões DBTools:
  • Conexão de Aprimoramento
  • Conexão de Consulta
• Permissões do IAM para Armazenamentos Semânticos, NL2SQL, Database Tools e segredos
• Autenticação do OCI IAM configurada para APIs de serviço do OCI usadas neste início rápido

Antes de criar um Armazenamento Semântico, crie o banco de dados de origem e as conexões DBTools necessárias.

Você precisa das seguintes conexões:

Antes de criar um Armazenamento Semântico, configure as políticas do IAM necessárias.

Este QuickStart usa a autenticação do OCI IAM para a API de serviço do OCI que cria Lojas Semânticas, executa jobs de enriquecimento e gera SQL.

Configurar a autenticação do OCI IAM para a identidade que assina solicitações. Os exemplos nesta seção usam o OCI Python SDK e BaseClient.

Você pode autenticar usando:

• Um arquivo de configuração do OCI e chaves de assinatura de API
• Um signatário de token de segurança

Os exemplos a seguir usam SecurityTokenSigner, mas você também pode usar um signatário de configuração padrão da OCI se isso se adequar melhor ao seu ambiente.

Tópicos Relacionados

• Arquivo de Configuração do SDK e da CLI
• Solicitar Assinaturas
• SDK do Python do Assinante

Para Automação, se você tiver selecionado Nenhum em vez de Na criação, poderá executar o enriquecimento após a criação do armazenamento semântico. Execute esta etapa se você tiver ignorado a opção Na criação.

O processo de enriquecimento lê metadados de esquema, como tabelas e colunas, do banco de dados conectado. A OCI Generative AI usa esses metadados para ajudar a gerar o SQL.

Para acionar o enriquecimento manualmente, chame a API GenerateEnrichmentJob.

Você também pode gerenciar jobs de enriquecimento usando a seguinte API:

• ListEnrichmentJobs
• GetEnrichmentJob
• CancelEnrichmentJob

O NL2SQL usa APIs de serviço do OCI em vez dos caminhos /openai/v1 compatíveis com o OCI OpenAI.

Depois que o Armazenamento Semântico estiver pronto e o enriquecimento tiver sido concluído, chame a API NL2SQL para gerar SQL com base em linguagem natural.

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))

Use os dados de rastreamento de resposta incorporados na API de Respostas do OCI para entender como uma solicitação foi processada. Para uma observabilidade mais profunda, você também pode integrar a API de Respostas da OCI com plataformas externas de observabilidade, como Langfuse.

Este QuickStart mostra como inspecionar os detalhes da execução retornados pela API de Respostas e como rastrear solicitações usando o Langfuse.

Antes de começar, você deve ter:

• Um projeto de IA Generativa da OCI
• Autenticação configurada para a API de Respostas do OCI
• O OpenAI SDK instalado
• Um cliente de API do OCI Responses em funcionamento

(Opcional) Para integrar com o Langfuse, você precisa de uma conta e credenciais do Langfuse.

Quando você chama a API de Respostas do OCI, a resposta inclui um campo output. Este campo é uma matriz de itens que descreve o que ocorreu durante a solicitação.

Cada item representa uma etapa na execução e pode incluir diferentes tipos, como:

• message
• file_search_call
• mcp_call

Esses itens de saída fornecem visibilidade de como a solicitação foi processada. Você pode usá-los para:

• Depurar e entender o comportamento do modelo
• Exibir etapas de execução em uma interface do usuário
• Crie observabilidade personalizada ou fluxos de trabalho de registro

Por exemplo, depois de enviar uma solicitação, você pode inspecionar o campo 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)

Para obter informações mais detalhadas, como rastreamentos de latência, custo e execução, você pode integrar a API de Respostas da OCI a uma plataforma de observabilidade.

Uma opção é a Langfuse, uma plataforma de engenharia de LLM de código aberto que ajuda os desenvolvedores a depurar, monitorar e melhorar aplicativos LLM. Langfuse fornece observabilidade de ponta a ponta para rastrear ações do agente, suporta controle de versão de prompt e ajuda a avaliar saídas do modelo. Ele se integra a frameworks populares, como OpenAI, LangChain e LlamaIndex.

Instale o Langfuse SDK:

pip install langfuse

Defina as variáveis de ambiente Langfuse e OCI necessárias:

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"

Importe o cliente OpenAI do Langfuse SDK. O código de solicitação existente permanece o mesmo, mas as solicitações são rastreadas automaticamente.

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"),
)

Depois de instrumentar o cliente, envie uma solicitação de API de Respostas como de costume. O Langfuse rastreia automaticamente a solicitação.

Exemplo:

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)