Invocare un modello con l’API Chat Completions OpenAI - Amazon Bedrock
Regioni e modelli supportatiPrerequisitiCreare un completamento di chatIncludere un guardrail in un completamento di chat

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Invocare un modello con l’API Chat Completions OpenAI

Per eseguire l’inferenza del modello, è possibile utilizzare l’API Create chat completion OpenAI con i modelli Amazon Bedrock.

L’API Create chat completion può essere chiamata nei modi seguenti:

  • Effettuare una richiesta HTTP con un endpoint di runtime Amazon Bedrock.

  • Utilizzare una richiesta OpenAI SDK con un endpoint di runtime Amazon Bedrock.

Per ulteriori informazioni, scegli un argomento:

Regioni e modelli supportati per l’API Chat Completions OpenAI

L’API Create chat completion può essere utilizzata con tutti i modelli OpenAI supportati in Amazon Bedrock e nelle Regioni AWS che li supportano. Per ulteriori informazioni sulle Regioni e sui modelli supportati, consulta Modelli di fondazione supportati in Amazon Bedrock.

Prerequisiti per utilizzare l’API Chat Completions

Per visualizzare i prerequisiti per l’utilizzo dell’API Chat Completions, scegli la scheda relativa al metodo che preferisci, quindi segui la procedura:

OpenAI SDK

  • Autenticazione: OpenAI SDK supporta solo l’autenticazione con una chiave API Amazon Bedrock. Genera una chiave API Amazon Bedrock per autenticare la tua richiesta. Per ulteriori informazioni sulle chiavi API Amazon Bedrock e su come generarle, consulta Generare chiavi API Amazon Bedrock per autenticarsi facilmente nell’API Amazon Bedrock.

  • Endpoint: trova l’endpoint corrispondente alla Regione AWS da utilizzare negli endpoint e nelle quote di runtime Amazon Bedrock. Se utilizzi un SDK AWS, potrebbe essere sufficiente specificare solo il codice della Regione e non tutto l’endpoint durante la configurazione del client.

  • Installa OpenAI SDK: per ulteriori informazioni, consulta Librerie nella documentazione OpenAI.

HTTP request

Creare un completamento di chat

Per i dettagli sull’API Create chat completion, consulta le risorse seguenti nella documentazione OpenAI:

Nota

Amazon Bedrock attualmente non supporta le altre operazioni dell’API Chat Completions OpenAI.

Per le modalità di utilizzo dell’API Create chat completion OpenAI, scegli la scheda relativa al metodo che preferisci, quindi segui la procedura:

OpenAI SDK (Python)

Per creare un completamento di chat con un SDK OpenAI, esegui queste operazioni:

  1. Importa il componente SDK OpenAI e configura il client con i seguenti campi:

    • base_url: anteponi l’endpoint di runtime Amazon Bedrock a /openai/v1, come nel seguente formato:

      https://${bedrock-runtime-endpoint}/openai/v1

    • api_key: specifica una chiave API Amazon Bedrock.

    • default_headers: se è necessario includere intestazioni, includile come coppie chiave-valore in questo oggetto. In alternativa, puoi specificare le intestazioni in extra_headers quando effettui una chiamata API specifica.

  2. Utilizza il metodo chat.completions.create() con il client e specifica almeno model e messages nel corpo della richiesta.

L’esempio seguente chiama l’API Create chat completion in us-west-2. Sostituisci $AWS_BEARER_TOKEN_BEDROCK con la chiave API effettiva.

from openai import OpenAI

client = OpenAI(
    base_url="https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1", 
    api_key="$AWS_BEARER_TOKEN_BEDROCK" # Replace with actual API key
)

completion = client.chat.completions.create(
    model="openai.gpt-oss-20b-1:0",
    messages=[
        {
            "role": "developer",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
)

print(completion.choices[0].message)
HTTP request

Per creare un completamento della chat con una richiesta HTTP diretta, esegui queste operazioni:

  1. Specifica l’URL anteponendo l’endpoint di runtime Amazon Bedrock a /openai/v1/chat/completions, come nel seguente formato:

    https://${bedrock-runtime-endpoint}/openai/v1/chat/completions

  2. Specifica le credenziali AWS o una chiave API Amazon Bedrock nell’intestazione Authorization.

  3. Nel corpo della richiesta, specifica almeno model e messages nel corpo della richiesta.

L’esempio seguente utilizza il comando curl per chiamare l’API Create chat completion in us-west-2. Sostituisci $AWS_BEARER_TOKEN_BEDROCK con la chiave API effettiva.

curl -X POST https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
   -d '{
    "model": "openai.gpt-oss-20b-1:0",
    "messages": [
        {
            "role": "developer",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
}'

Includere un guardrail in un completamento di chat

Per includere misure di sicurezza nell’input e nelle risposte del modello, applica un guardrail quando esegui l’invocazione del modello includendo i seguenti parametri aggiuntivi come campi nel corpo della richiesta.

  • extra_headers: esegue il mapping a un oggetto contenente i seguenti campi, che specificano intestazioni aggiuntive nella richiesta:

    • X-Amzn-Bedrock-GuardrailIdentifier (obbligatorio): ID del guardrail.

    • X-Amzn-Bedrock-GuardrailVersion (obbligatorio): versione del guardrail.

    • X-Amzn-Bedrock-Trace (facoltativo): indica se abilitare o meno la traccia del guardrail.

  • extra_body: esegue il mapping a un oggetto. In tale oggetto è possibile includere il campo amazon-bedrock-guardrailConfig, che viene mappato a un oggetto contenente i campi seguenti:

Per ulteriori informazioni sui questi parametri in Guardrail per Amazon Bedrock, consulta Testare il guardrail.

Per esempi di utilizzo dei guardrail con Chat Completions OpenAI, scegli la scheda relativa al metodo che preferisci, quindi segui la procedura:

OpenAI SDK (Python)
import openai
from openai import OpenAIError

# Endpoint for Amazon Bedrock Runtime
bedrock_endpoint = "https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"

# Model ID
model_id = "openai.gpt-oss-20b-1:0"

# Replace with actual values
bedrock_api_key = "$AWS_BEARER_TOKEN_BEDROCK"
guardrail_id = "GR12345"
guardrail_version = "DRAFT"

client = openai.OpenAI(
    api_key=bedrock_api_key,
    base_url=bedrock_endpoint,
)

try:
    response = client.chat.completions.create(
        model=model_id,
        # Specify guardrail information in the header
        extra_headers={
            "X-Amzn-Bedrock-GuardrailIdentifier": guardrail_id,
            "X-Amzn-Bedrock-GuardrailVersion": guardrail_version,
            "X-Amzn-Bedrock-Trace": "ENABLED",
        },
        # Additional guardrail information can be specified in the body
        extra_body={
            "amazon-bedrock-guardrailConfig": {
                "tagSuffix": "xyz"  # Used for input tagging
            }
        },
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "assistant", 
                "content": "Hello! How can I help you today?"
            },
            {
                "role": "user",
                "content": "What is the weather like today?"
            }
        ]
    )

    request_id = response._request_id
    print(f"Request ID: {request_id}")
    print(response)
    
except OpenAIError as e:
    print(f"An error occurred: {e}")
    if hasattr(e, 'response') and e.response is not None:
        request_id = e.response.headers.get("x-request-id")
        print(f"Request ID: {request_id}")
OpenAI SDK (Java)
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponseFor;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

// Endpoint for Amazon Bedrock Runtime
String bedrockEndpoint = "http://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"

// Model ID
String modelId = "openai.gpt-oss-20b-1:0"

// Replace with actual values
String bedrockApiKey = "$AWS_BEARER_TOKEN_BEDROCK"
String guardrailId = "GR12345"
String guardrailVersion = "DRAFT"

OpenAIClient client = OpenAIOkHttpClient.builder()
        .apiKey(bedrockApiKey)
        .baseUrl(bedrockEndpoint)
        .build()

ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
        .addUserMessage("What is the temperature in Seattle?")
        .model(modelId)
        // Specify additional headers for the guardrail
        .putAdditionalHeader("X-Amzn-Bedrock-GuardrailIdentifier", guardrailId)
        .putAdditionalHeader("X-Amzn-Bedrock-GuardrailVersion", guardrailVersion)
        // Specify additional body parameters for the guardrail
        .putAdditionalBodyProperty(
                "amazon-bedrock-guardrailConfig",
                JsonValue.from(Map.of("tagSuffix", JsonValue.of("xyz"))) // Allows input tagging
        )
        .build();
        
HttpResponseFor<ChatCompletion> rawChatCompletionResponse =
        client.chat().completions().withRawResponse().create(request);

final ChatCompletion chatCompletion = rawChatCompletionResponse.parse();

System.out.println(chatCompletion);