Início Rápido

Conceder Acesso no Nível da Tenancy

Para permitir que um grupo de usuários gerencie todos os recursos do serviço Generative AI na tenancy:

allow group <your-group-name> to manage generative-ai-family 
in tenancy

Conceder Acesso no Nível do Compartimento

Para definir o escopo do acesso a um compartimento específico:

allow group <your-group-name> to manage generative-ai-family 
in compartment <your-compartment-name>

Depois que essas permissões estiverem em vigor, você estará pronto para criar o primeiro projeto.

Localizar o OCID da Chave de API

Para definir o escopo das permissões para uma chave de API específica, você precisa do seu OCID.

Na Console:

1. Navegue até a página da lista Chaves de API.
2. Selecione a chave da API criada.
3. Copie o OCID (geralmente começa com ocid1.generativeaiapikey...)

Conceder Permissão à Chave de API

Crie uma política do serviço IAM para permitir que a chave da API chame a API de Respostas:

allow group <your-group-name> 
to manage generative-ai-response in tenancy where ALL 
{request.principal.type='generativeaiapikey', 
request.principal.id='<your-api-key-OCID>'}

Esta política permite que as solicitações autenticadas com a chave de API especificada acessem a API de Respostas, mantendo o acesso com escopo e controlado.

URL Base 🔗

Use o seguinte URL base para acessar a API de Respostas do OCI:

https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1

Substitua <region> pelo identificador de região apropriado (por exemplo, us-chicago-1).

Suporte a SDK 🔗

A API de Respostas do OCI é compatível com o OpenAI SDK, que é recomendado para interagir com o serviço. Ele é suportado em muitas linguagens, incluindo Python, Java, TypeScript, Go e .NET.

Você também pode usá-lo com frameworks de agentes populares, como LangChain, LlamaIndex e OpenAI Agents SDK.

Quando Usar a Autenticação do IAM

Considere o uso da autenticação IAM quando:

• Executando aplicativos em serviços do OCI (por exemplo, Functions ou OKE)
• Evitando credenciais de longa duração, como chaves de API
• Impondo controle de acesso refinado por meio de políticas do IAM

Instalar a Biblioteca de Autenticação do OCI IAM

Instale a biblioteca oci-genai-auth, que fornece utilitários auxiliares para integrar a autenticação do OCI IAM com o OpenAI SDK:

pip install oci-genai-auth

Esta biblioteca inclui os seguintes ajudantes de autenticação:

• OciSessionAuth (para desenvolvimento local)
• OciUserPrincipalAuth
• OciInstancePrincipalAuth
• OciResourcePrincipalAuth (para ambientes gerenciados pelo OCI)

Configurar o cliente OpenAI

Ao usar a autenticação do IAM, inicialize o cliente OpenAI com um cliente HTTP personalizado e um handler de autenticação. O valor api_key é "not used" nesse caso.

Exemplo: Desenvolvimento Local (OciSessionAuth)

Use essa abordagem ao executar código localmente (por exemplo, em um laptop usando um perfil da CLI do OCI):

from openai import OpenAI
from oci_openai import OciSessionAuth
import httpx

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",  # update region if needed
    api_key="not-used",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",  # project OCID created earlier
    http_client=httpx.Client(auth=OciSessionAuth(profile_name="DEFAULT"))  # update profile if needed
)

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

print(response.output_text)

Exemplo: Ambientes Gerenciados do OCI (OciResourcePrincipalAuth)

Use essa abordagem ao executar em serviços do OCI, como OCI Functions ou OCI Container Engine for Kubernetes (OKE):

Se estiver Usando a Autenticação do OCI IAM

Se você tiver adicionado as políticas em Pré-requisito: Configurar Permissões do Serviço IAM, ignore esta etapa.

Para permitir que um grupo de usuários chame a API de Respostas, adicione a seguinte política:

allow group <your-group-name> 
to manage generative-ai-response in tenancy

Se Usando Autenticação de Chave de API do Serviço Generative AI

Ao usar a autenticação de chave de API, outra política é necessária para autorizar solicitações feitas com a chave de API. Se você tiver adicionado as políticas em 3. Adicionar Permissão à Chave de API, ignore esta etapa.

Para conceder acesso a uma chave de API específica:

allow group <your-group-name> 
to manage generative-ai-response in tenancy 
where ALL {request.principal.type='generativeaiapikey', 
request.principal.id='<your-api-key-OCID>'}

Para acesso mais amplo (por exemplo, durante o teste), você pode usar uma política mais geral:

allow any-user 
to manage generative-ai-family in tenancy 
where ALL {request.principal.type='generativeaiapikey', 
request.principal.id='<your-api-key-OCID>'}

Essas políticas garantem que as solicitações, autenticadas por meio de chaves de API ou do IAM, sejam autorizadas a acessar recursos do OCI Generative AI.

Modelos Hospedados de Terceiros

A OCI Generative AI fornece acesso a modelos de provedores de terceiros. Especifique o modelo usando seu nome totalmente qualificado:

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

Modelos sob Demanda

Os modelos sob demanda são hospedados e gerenciados pela OCI e estão disponíveis sem a necessidade de infraestrutura dedicada:

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Write a one-sentence explanation of what a database is."
)

Clusters de IA Dedicados (Modo Dedicado)

Para cargas de trabalho de produção que exigem isolamento ou desempenho previsível, você pode implantar modelos em um cluster de IA dedicado. Nesse caso, use o OCID do ponto final do cluster como o identificador do modelo:

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

Transmitir Todos os Eventos

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)

Saída de Texto Somente de Fluxo (Tokens Delta)

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)

O streaming é especialmente útil para aplicativos interativos nos quais você deseja exibir respostas aos usuários à medida que elas são geradas.

Integração com Ferramentas de Observabilidade 🔗

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 plataformas de observabilidade.

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

O exemplo a seguir mostra como usar o Langfuse para rastrear e monitorar chamadas de API de Respostas.

Etapa 1: Instalar o Langfuse SDK

pip install langfuse

Etapa 2: Configurar Variáveis de Ambiente

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"

Etapa 3: Instrumentalizar o Cliente OpenAI

Importe o cliente OpenAI do Langfuse SDK. O código existente permanece inalterado, 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.us-ashburn-1.oci.oraclecloud.com/openai/v1",
    api_key=os.getenv("OCI_GENAI_API_KEY"),
    project=os.getenv("OCI_GENAI_PROJECT_ID"),
)

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

print(response.output_text)

Essa integração fornece visibilidade de ponta a ponta das chamadas de API sem exigir alterações significativas no código do aplicativo.

Entrada de imagem como URL de dados codificados em Base64

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="openai.gpt-oss-120b",
    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)

Entrada de Imagem como URL Acessível à Internet

response = client.responses.create(
    model="openai.gpt-oss-120b",
    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)

Substitua o "image_url" por um URL de imagem válido.

Entrada do Arquivo como ID do Arquivo

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)

Entrada de Arquivo como URL Acessível à Internet

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)

Esforço de raciocínio

import json

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

print(response.output_text)

Saída do Resumo do Motivo

Se você estiver criando um chatbot, habilitar resumos de raciocínio pode ajudar os usuários a entender melhor como o modelo chegou a um resultado. Durante o streaming, os usuários também podem ver tokens de raciocínio enquanto o modelo está pensando.

import json

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

print(response.output_text)

O que isso permite

As ferramentas de função são úteis quando o aplicativo precisa manter o controle da execução e, ao mesmo tempo, permitir que o modelo decida quando informações externas são necessárias.

Os casos de uso típicos incluem:

• Procurando eventos do calendário
• Recuperando dados da inscrição
• Chamando APIs internas ou externas
• Execução de cálculos ou lógica de negócios

Essa abordagem oferece flexibilidade ao mesmo tempo em que mantém o caminho de execução dentro do aplicativo.

Fluxo de Execução 🔗

Uma interação típica da ferramenta de função funciona desta forma:

1. O cliente envia uma solicitação que inclui uma ou mais definições de ferramentas.
2. O modelo decide se uma dessas ferramentas é necessária.
3. Se uma ferramenta for necessária, o modelo retornará o nome da ferramenta e os argumentos.
4. O aplicativo executa a ferramenta e prepara o resultado.
5. O aplicativo envia esse resultado de volta em uma solicitação de acompanhamento.
6. O modelo usa esse resultado para concluir a resposta.

Opções de Controle de Estado 🔗

Há duas maneiras comuns de gerenciar o estado nessas solicitações:

• Estado gerenciado pelo serviço: Recomendado para a maioria dos casos de uso. A solicitação de acompanhamento inclui previous_response_id e o serviço rastreia a troca anterior.
• Estado gerenciado pelo cliente: O aplicativo mantém todo o histórico de interações e envia o contexto acumulado com cada solicitação.

Definir uma ferramenta de funções

O exemplo a seguir define uma ferramenta que recupera eventos de calendário para uma data especificada.

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

Inclua esse array tools na solicitação client.responses.create().

Exemplo: Estado Gerenciado pelo Serviço

Neste padrão, a primeira solicitação permite que o modelo decida se a ferramenta é necessária. A segunda solicitação envia o resultado da ferramenta de volta e faz referência à resposta anterior.

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)

Exemplo: Estado Gerenciado pelo Serviço

Nesse padrão, o aplicativo mantém a troca completa e a reenvia com a solicitação de acompanhamento.

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)

Ferramentas de função são uma opção forte quando o aplicativo deve permanecer responsável pela execução, controle de acesso e lógica de integração, enquanto ainda permite que o modelo solicite as informações de que precisa.

Quando Usar a Ferramenta MCP

Use a ferramenta MCP quando o modelo precisar de acesso a recursos externos hospedados em um servidor MCP.

Essa abordagem é útil quando você deseja:

• O serviço para se comunicar diretamente com o servidor MCP
• Menos etapas de orquestração no lado do cliente
• Latência menor do que um padrão de ferramenta executado pelo cliente
• Acesso a recursos expostos por meio de um servidor MCP remoto

A ferramenta MCP faz parte do conjunto de ferramentas da OCI Generative AI e pode ser usada junto com outras ferramentas suportadas.

Suporte de Transporte

A chamada MCP remota usa HTTP Streamable.

Definir uma ferramenta MCP

Adicione a definição do servidor MCP no campo tools da solicitação.

response_stream = client.responses.create(
    model="xai.grok-code-fast-1",
    tools=[
        {
            "type": "mcp",
            "server_label": "calendar",
            "server_description": "An MCP server that retrieves calendar events for a specified date.",
            "server_url": "https://example.com/mcp",
            "require_approval": "never",
        },
    ],
    input="What events are scheduled for 2026-04-02?",
    stream=True,
)

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

Este exemplo transmite a resposta e imprime o texto à medida que é gerado.

Restringir as Ferramentas Expostas pelo Servidor MCP

Se o servidor MCP remoto expor mais ferramentas do que o aplicativo precisa, você poderá restringir o conjunto disponível usando allowed_tools.

response_stream = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_label": "calendar",
            "server_description": "An MCP server that retrieves calendar events for a specified date.",
            "server_url": "https://example.com/mcp",
            "require_approval": "never",
            "allowed_tools": ["get_events"],
        },
    ],
    input="Show the calendar events for 2026-02-02.",
    stream=True,
    store=False,
)

Fornecer Autenticação ao Servidor MCP

response_stream = client.responses.create(
    model="xai.grok-4-1-fast-reasoning",
    tools=[
        {
            "type": "mcp",
            "server_label": "calendar",
            "server_url": "https://calendar.example.com/mcp",
            "authorization": "$CALENDAR_OAUTH_ACCESS_TOKEN"
        },
    ],
    input="List my meetings for 2026-02-02.",
    stream=True,
    store=False,
)

Informe apenas o valor do token. Não inclua o prefixo Bearer. O OCI envia o token pelo TLS como parte da solicitação e não o decodifica, inspeciona, armazena ou registra.

Hospedagem de Servidor MCP

A OCI Generative AI também fornece hospedagem de servidor MCP para ajudar a implementar e dimensionar servidores MCP.

A ferramenta MCP é uma boa opção quando você deseja que a OCI Generative AI trabalhe diretamente com um servidor MCP remoto durante a execução da solicitação, sem exigir que o aplicativo cliente trate cada etapa da ferramenta em si.

Prepare uma loja de vetores

Antes de usar a Pesquisa de Arquivos, crie um armazenamento de vetores e adicione os arquivos aos quais você deseja que o modelo faça referência. O OCI Generative AI suporta vários padrões de tratamento de arquivos por meio de APIs que seguem o estilo de API OpenAI Files.

Exemplo

Para disponibilizar a Pesquisa de Arquivos em uma solicitação, adicione uma entrada de ferramenta com type: "file_search" e forneça o ID do armazenamento de vetores.

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)

Para que você pode usá-lo

Se você estiver usando esse recurso pela primeira vez, será útil pensar no Code Interpreter como um espaço de trabalho temporário do Python para o modelo.

Você pode usá-lo para tarefas como:

• resolvendo problemas matemáticos
• analisando arquivos carregados
• limpando ou transformando dados
• criando gráficos ou tabelas
• gerando arquivos de saída, como logs, ou conjuntos de dados processados

Ambiente de Execução

O ambiente Python inclui mais de 420 bibliotecas pré-instaladas, por isso muitas tarefas comuns funcionam sem configuração extra.

O código é executado dentro de um contêiner. Esse contêiner é o ambiente de trabalho em que o Python é executado e em que os arquivos são armazenados durante a sessão.

Limites de memória do contêiner

Os contêineres do Code Interpreter usam um pool de memória compartilhado de 64 GB por tenancy.

Os tamanhos de contêiner suportados são:

• 1 GB
• 4 GB
• 16 GB
• 64 GB

Esse limite compartilhado pode ser dividido em vários contêineres. Por exemplo, poderia suportar:

• sessenta e quatro recipientes de 1 GB
• dezesseis contêineres de 4 GB
• quatro contêineres de 16 GB
• um contêiner de 64 GB

Se você precisar de mais capacidade, poderá enviar uma solicitação de serviço.

Expiração do Contêiner

Um contêiner expira após 20 minutos de inatividade.

Isso é importante saber quando criar fluxos com várias etapas:

• um contêiner expirado não pode ser reutilizado
• você deve criar um novo contêiner
• arquivos devem ser carregados novamente, se necessário
• estado na memória, como variáveis Python, é perdido

Por isso, é melhor tratar contêineres como ambientes de trabalho temporários.

Exemplo

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)

Contêineres para o Code Interpreter

O Code Interpreter precisa de um contêiner. O container é o ambiente isolado no qual o modelo executa o código Python.

Um contêiner pode conter:

• arquivos transferidos por upload
• arquivos criados pelo modelo
• dados de trabalho temporário durante a execução

Ao usar o Code Interpreter, você pode atribuir um dos dois modos de contêiner:

• automático: o OCI Generative AI cria o contêiner para você e atribui automaticamente um tamanho de contêiner.
• OCID do construtor: Você mesmo cria o contêiner, define o tamanho do contêiner e fornece o OCID.

Para ambas as opções, os contêineres são criados e gerenciados no OCI Generative AI. O código executado nesses contêineres também é executado na tenancy do OCI Generative AI.

Modo Automático

No modo automático, o serviço cria o contêiner para você. Esta é a opção mais fácil e um bom ponto de partida para a maioria dos usuários.

Usar o modo automático quando:

• você deseja que o OCI Generative AI gerencie o contêiner
• você não precisa de controle direto sobre o ambiente
• você quer uma configuração mais simples

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

Modo Explícito

No modo explícito, você cria o contêiner primeiro e define o tamanho. Em seguida, você informa o ID do contêiner na solicitação.

Use o modo explícito quando quiser mais controle sobre as especificidades do contêiner, como o tamanho da memória.

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 average of 12, 18, 24, and 30."
)

print(response.output_text)

Arquivos no Code Interpreter

O Code Interpreter pode trabalhar com arquivos durante a vida útil do contêiner. O modelo pode ler arquivos que você fornece e também pode criar novos arquivos.

Isso é útil para workflows como:

• lendo um CSV ou PDF
• gerando um gráfico
• salvando saída processada
• criando logs ou relatórios

Persistência de Arquivo 🔗

Os arquivos criados ou alterados pela ferramenta python permanecem disponíveis no mesmo contêiner desde que o contêiner não tenha expirado.

Isso significa que o modelo pode se basear em trabalhos anteriores na mesma sessão. Por exemplo, ele pode:

1. ler um arquivo
2. analisá-lo
3. salvar um gráfico
4. usar esse gráfico posteriormente no mesmo contêiner

Quando o contêiner expirar, esse estado não estará mais disponível.

Fazendo Upload e Gerenciando Arquivos 🔗

Você pode gerenciar arquivos de contêiner por meio das APIs de arquivo de contêiner.

As operações comuns incluem:

• Criar Arquivo Contêiner: Adicione um arquivo ao contêiner
• Listar Arquivos de Contêiner: Exibir arquivos no contêiner
• Excluir Arquivo Contêiner: Remove um arquivo
• Recuperar Conteúdo do Arquivo Contêiner: Faça download de um arquivo do contêiner

Isso permite que você use o contêiner como um espaço de trabalho temporário para execução de código orientada por modelo.

Arquivos de Saída e Citações 🔗

Quando o modelo cria arquivos, esses arquivos são armazenados no contêiner e podem ser referenciados na resposta.

Essas referências incluem:

• container_id
• file_id
• filename

Você pode usar esses valores para recuperar o conteúdo do arquivo gerado.

A API de Respostas do OCI suporta pontos finais compatíveis com OpenAI para recursos como Respostas, Arquivos, Contêineres e Arquivos de Contêiner. Por isso, a documentação OpenAI relacionada pode ser usada como referência para estrutura de solicitação, formatos de resposta e fluxos de trabalho gerais. No entanto, ao usar essas APIs com a OCI, envie solicitações para os pontos finais de inferência da OCI Generative AI, use a autenticação da OCI e observe que os recursos e a execução permanecem na OCI Generative AI, não em uma tenancy OpenAI.

Pré-requisitos

Antes de usar a ferramenta NL2SQL, primeiro crie um banco de dados e configure as conexões de banco de dados necessárias.

Para obter mais informações, consulte:

• Clonar uma Instância do Autonomous AI Database
• Usando a Console do Oracle Cloud Infrastructure

Permissões para Lojas Semânticas

Acesso a Segredos

Conceda ao grupo acesso para ler os segredos usados pelo serviço Database Tools:

allow group <your-group-name> 
to read secret-family in compartment <your-compartment-name> 
where all {request.principal.type='generativeaisemanticstore'}

Acesso a Conexões do Serviço Database Tools

Conceda ao grupo acesso aos recursos necessários do Database Tools:

allow group <your-group-name> 
to use database-tools-family in compartment <compartment-name> 
where all {request.principal.type='generativeaisemanticstore'}

allow group <your-group-name> 
to read database-family in compartment <compartment-name> 
where all {request.principal.type='generativeaisemanticstore'}

allow group <your-group-name> 
to read autonomous-database-family in compartment <compartment-name> 
where all {request.principal.type='generativeaisemanticstore'}

Acesso a recursos de IA generativa

Se a política mais ampla abaixo já estiver em vigor, ela incluirá o acesso aos recursos de armazenamento semântico:

allow group <your-group-name> 
to manage generative-ai-family in tenancy

Se quiser restringir o acesso, use a seguinte política para permitir que o grupo crie e gerencie armazenamentos semânticos:

allow group <your-group-name> 
to manage generative-ai-semantic-store 
in compartment <your-compartment-name>

Se o grupo só precisar usar um armazenamento semântico existente e chamar NL2SQL, use estas políticas mais específicas:

allow group <your-group-name> 
to use generative-ai-semantic-store 
in compartment <your-compartment-name>

allow group <your-group-name> 
to manage generative-ai-nl2sql 
in compartment <your-compartment-name>

Encadeamento de Respostas

Com o encadeamento de respostas, cada nova resposta aponta para a anterior. Esta é uma opção simples quando você deseja levar o contexto adiante sem criar explicitamente um recurso de conversa.

# first turn
response1 = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Give me three ideas for a team offsite.",
)
print("Response 1:", response1.output_text)

# second turn
response2 = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Make the second idea more budget friendly.",
    previous_response_id=response1.id,
)
print("Response 2:", response2.output_text)

API de Conversas

# create a conversation
conversation = client.conversations.create(
    metadata={"topic": "demo"}
)
print("Conversation ID:", conversation.id)

# first turn
response1 = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Give me three ideas for a team offsite.",
    conversation=conversation.id,
)
print("Response 1:", response1.output_text)

# second turn
response2 = client.responses.create(
    model="openai.gpt-oss-120b",
    input="Make the second idea more budget friendly.",
    conversation=conversation.id,
)
print("Response 2:", response2.output_text)