Oracle Cloud Infrastructure-Dokumentation

API-Schlüssel

OCI Generative AI-API-Schlüssel sind sichere Zugangsdaten-Token, mit denen Aufrufer authentifiziert und der Zugriff auf große Sprachmodelle autorisiert wird, die vom OCI Generative AI-Service gehostet werden.

API-Schlüssel

Ein OCI Generative AI-API-Schlüssel ist ein Secret Token (eine Zeichenfolge), das für den OCI Generative AI-Service spezifisch ist. Sie können einen API-Schlüssel generieren und damit auf die großen Sprachmodelle zugreifen, die vom Service gehostet werden.

Dieser API-Schlüssel unterscheidet sich von einem OCI-IAM-API-Schlüssel, der ein Public/Private-Key-Paar verwendet, um allgemeinen OCI-Mandantenzugriff bereitzustellen.

Funktionsweise des API-Schlüssels

Jeder OCI Generative AI-API-Schlüssel enthält zwei separate Secrets, wie key-one und key-two. Beide Geheimnisse sind einzigartige Zeichenfolgen.

  • Sie erstellen den API-Schlüssel über den Generative AI-Service und benennen und legen Ablaufdaten für die beiden Secrets fest.
  • Jedes Secret bietet die gleiche Zugriffsebene und ist mit demselben API-Schlüssel verknüpft. Sie können jedes Secret austauschbar in Anwendungen verwenden.
  • Wenn Ihre Anwendung einen OCI Generative AI-Modellendpunkt aufruft, nehmen Sie entweder ein Secret in den Autorisierungsheader auf.
Wichtig

Der API-Schlüssel muss sich in derselben Region wie das Modell befinden, mit dem Sie ihn verwenden möchten.

So verwenden Sie den API-Schlüssel

Sie können OCI Generative AI-API-Schlüssel generieren und mit ihnen auf große Sprachmodellendpunkte zugreifen, die vom Generative AI-Service mit der REST-API oder dem nativen openai-SDK gehostet werden. Im Folgenden werden die Schritte zur Verwendung der API-Schlüssel beschrieben.

  1. Erstellen Sie in OCI Generative AI einen API-Schlüssel in einer unterstützten Region für das gewünschte Modell.
  2. Fügen Sie in OCI IAM API-Schlüsselberechtigungen hinzu.
  3. Verwenden Sie diesen Schlüssel, wenn Sie ein unterstütztes Modell in einer unterstützten Region über die folgenden Optionen aufrufen:

Unterstützte Models

Modelle für Chatabschlüsse-API
Modelle für die Antwort-API
Wichtig

Externe Aufrufe von xAI Grok-Modellen

Die xAI Grok-Modelle werden in einem OCI-Data Center in einem Mandanten gehostet, der für xAI bereitgestellt wird. Die xAI Grok-Modelle, auf die über den OCI Generative AI-Service zugegriffen werden kann, werden von xAI verwaltet.

API-Schlüssel mit REST-API verwenden

Sie können die API-Schlüssel in Headern der REST-API und curl verwenden. Hier sind die Endpunkte, die Sie für die REST-API verwenden können.

Unterstützte Endpunkte

Chatabschlüsse
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/chat/completions
Antworten
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1/responses

Beispiel mit curl:

curl 
--location 'https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1/chat/completions' \
--header 'Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
"model": "xai.grok-4",
"messages": [
    {
    "role": "user",
    "content": "What's the capital of France?"
    }
]
}'

API-Schlüssel mit OpenAI-SDKs verwenden

Sie können die API-Schlüssel mit dem SDK OpenAI verwenden. Hier sind die Endpunkte, die Sie für das OpenAI-SDK verwenden können.

Unterstützte Endpunkte

Geben Sie base_url als 
https://inference.generativeai.<region-identifier>.oci.oraclecloud.com/20231130/actions/v1
Chatabschlüsse
Verwenden Sie diese Methode: client.chat.completions.create
Antworten
Verwenden Sie diese Methode: client.responses.create
Beispiel
from openai import OpenAI
import os

API_KEY=os.getenv("OPENAI_API_KEY")

print(API_KEY)

client = OpenAI(
    api_key=API_KEY,
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1"
)

# Responses API
response = client.responses.create(
    model="openai.gpt-oss-120b",
    # model="xai.grok-3",
    # meta models are not supported with the Responses API
    input="Write a one-sentence bedtime story about a unicorn."
)
print(response)

# Completion API
response = client.chat.completions.create(
    # model="openai.gpt-oss-120b",
    # model="meta.llama-3.3-70b-instruct",
    model="xai.grok-3",
    messages=[{
        "role": "user", 
        "content": "Write a one-sentence bedtime story about a unicorn."
        }
    ]
)
print(response)
Referenz
Oracle GitHub-Repository

Unterstützte Regionen

Regionen

Bei OpenAI-SDKs sind die unterstützten OCI-Regionen, die mit API-Schlüsseln verwendet werden können, auf Folgendes beschränkt:

  • Germany Central (Frankfurt)
  • India South (Hyderabad)
  • Japan Central (Osaka)
  • US East (Ashburn)
  • US Midwest (Chicago)
  • US West (Phoenix)

Um die verwendbaren Regionen eines Modells für das OCI OpenAI-Package zu bestätigen, führen Sie die folgenden Aufgaben aus.

  1. Öffnen Sie die Karte des Modells in der Dokumentation zur generativen KI:
  2. Beachten Sie die für dieses Modell aufgeführten Regionen.
  3. Wählen Sie eine Region für das Modell aus, die sowohl in den verfügbaren Regionen des Modells als auch in den vorherigen sechs OCI OpenAI-Regionen angezeigt wird.
  4. Prüfen Sie, ob das Modell in dem von Ihnen benötigten Modus verfügbar ist (On-Demand oder dediziert).

    Für den Zugriff auf Modelle im dedizierten Modus werden öffentliche und private Endpunkte unterstützt.

Schlüssel drehen oder ersetzen

Um einen OCI Generative AI-API-Schlüssel zu rotieren, können Sie seinen Status in der OCI-Konsole oder mit dem Vorgang SetApiKeyState mit der API ändern. Die folgenden Schritte sind ausgeführt:

  1. Aktivieren Sie das Standby Secret. Aktivieren Sie das nicht verwendete Secret (z.B. key-two), und aktualisieren Sie Ihre Anwendungen so, dass es verwendet wird.
  2. Prüfen Sie den Failover. Bestätigen Sie, dass Anforderungen mit dem neu aktivierten Secret authentifiziert werden und dass Workloads ohne Unterbrechung fortgesetzt werden.
  3. Entziehen oder deaktivieren Sie das erste Secret.
    • Wenn Sie ein Leck vermuten oder es Zeit ist, das erste Secret zurückzuziehen, widerrufen Sie es. Nachdem die Änderung propagiert wurde, werden die Anforderungen, die das entzogene Secret verwenden, abgelehnt. Wenn Sie ein Geheimnis entziehen, wird es dauerhaft deaktiviert, und die Aktion kann nicht rückgängig gemacht werden.
    • Wenn Sie das erste Secret wiederverwenden möchten, deaktivieren Sie es. Nachdem die Änderung propagiert wurde, werden die Anforderungen, die das deaktivierte Secret verwenden, abgelehnt, bis Sie es erneut aktivieren.
    Tipp

    Deaktivieren Sie ein Geheimnis für eine kurzfristige Aussetzung oder Untersuchung. Entziehen Sie ein Secret, wenn es kompromittiert wurde oder wenn Sie es dauerhaft einstellen müssen.

Die Schritte zum Ausführen dieser Aufgaben finden Sie unter API-Schlüssel verwalten.

Wichtig

Kopieren Sie neue oder neu generierte Secrets sofort und speichern Sie sie sicher. Sie erscheinen nur einmal.

Best Practices

Speichern Sie OCI Generative AI-API-Schlüssel-Secrets immer in einem genehmigten Secrets-Manager. Schreiben Sie sie niemals zur Quellkontrolle fest, oder betten Sie sie in clientseitigen Code ein.

  • Verwenden Sie das Zwei-Secret-Setup für eine reibungslose Rotation ohne Ausfallzeiten, und legen Sie Ablaufzeiten fest, um Schlüssel regelmäßig zu aktualisieren.
  • Beschränken Sie den Zugriff auf Schlüssel mit Compartments und Policys mit den geringsten Berechtigungen.
  • Überwachen Sie die Nutzung, richten Sie Warnungen ein, und drehen Sie die Tasten sofort, wenn Sie verdächtige Aktivitäten erkennen.

API-Schlüssel verwalten

Nachdem Sie die IAM-Berechtigung für die OCI Generative AI-API-Schlüsselressource erhalten haben, können Sie API-Schlüssel mit den folgenden Vorgängen verwalten:

Beispiele auf GitHub

Eine praktische Erfahrung finden Sie in den Beispielen im Oracle GitHub-Repository.