Modelle mit dem Python-SDK und der REST-API ermitteln
Erkunden Sie den OCI Generative AI-Modellkatalog, filtern Sie Modelle für Ihre Anwendung, und prüfen Sie Modellmetadaten mit signierten Python-SDK- und REST-Anforderungen.
Überblick
Die Modell-Discovery-API vereint Modell-IDs, Funktionen, API-Kompatibilität, Konfigurationsparameter und regionale Verfügbarkeit. Verwenden Sie diese Metadaten, um Modelle für einen Chatassistenten, eine Suchanwendung oder einen multimodalen Workflow auszuwählen, bevor Sie eine Inferenzanforderung schreiben.
Anwendungen können den Katalog abfragen, um Modellauswahlschnittstellen zu erstellen und die verfügbaren Auswahlmöglichkeiten zu aktualisieren. Anhand regionaler Lebenszyklusinformationen können Sie Upgrades planen und gemeldete Ersetzungen bewerten.
| Metadaten | Was es berichtet | Verwendung |
|---|---|---|
| Identität und Provider | Modell-IDs und Lieferanteninformationen. | Suchen Sie einen Provider, und kopieren Sie eine genaue Modell-ID. |
| Aufgaben und Modalitäten | Modellfunktionen und unterstützte Input/Output-Typen. | Identifizieren Sie Kandidaten für Chat-, Einbettungs-, Rangier- oder multimodale Workflows. |
| API-Kompatibilität | Für das Modell gemeldete Inferenz-API-Funktionen. | Wählen Sie eine API aus, die vom Modell unterstützt wird. |
| regionale Verfügbarkeit | Realms, Regionen und On-Demand- oder dedizierte Bereitstellungsmodi. | Finden Sie Kandidaten für Ihren Bereitstellungsort und Bereitstellungsmodus. |
| Gehosteter oder Proxy-Zugriff | Die Zugriffsklassifizierung des Modells. | Prüfen Sie die entsprechende Dokumentation zum Deployment und zur Datenverarbeitung. |
| Parameter | Gemeldete Namen, Typen, Bereiche, Standardwerte und Beschreibungen | Erstellen Sie Konfigurationsformulare, und prüfen Sie Einstellungen anhand der zurückgegebenen Metadaten. |
| Lebenszyklus | Abschreibungs- und Abgangsdaten nach Region und Service-Modus sowie gegebenenfalls Ersetzungen. | Identifizieren Sie betroffene Deployments, und bewerten Sie Migrationskandidaten. |
| Filter | Modell-ID, Realm, Region, Funktion, API-Funktion, Bereitstellungsmodus, Zugriffstyp und Lebenszyklusstatus. | Erstellen Sie eine fokussierte Modellauswahl, oder automatisieren Sie Katalogsuchen. |
Einzelne Modelle füllen möglicherweise nicht alle Felder aus. Mit der Discovery können Sie Modelle auswählen und konfigurieren. Es ruft keine Inferenz, Zugriffsberechtigung oder Benchmarkmodellqualität auf. Validieren Sie ein ausgewähltes Modell und einen vorgeschlagenen Ersatz für die Workload Ihrer Anwendung.
In diesem Tutorial authentifizieren Sie sich bei einer OCI-IAM-Session, fragen die Discovery mit dem Python-SDK ab, senden dieselbe Anforderung über REST, und führen Sie zehn praktische Beispiele aus. Außerdem lernen Sie, wie Sie Modelle auflisten, die bereits in Ihr Compartment importiert wurden.
Der Vorgang lautet ListModelDiscovery. Sie unterscheidet sich von
list_models(), list_imported_models() und dem OpenAI-kompatiblen /models-Endpunkt. Das Senden einer Discovery-Anforderung an Chicago schränkt die Katalogergebnisse nicht auf Chicago ein. Verwenden Sie einen region-Filter, um die Katalogregion auszuwählen.Bevor Sie beginnen
Um dieses Tutorial abzuschließen, benötigen Sie:
- Ein OCI-Account und ein Compartment, in dem Sie Modelle prüfen können. Für
ListModelDiscoveryistGENERATIVE_AI_MODEL_INSPECTerforderlich. Siehe Modellberechtigungen. - Für die Beispiele für importierte Modelle können Sie importierte Modelle im ausgewählten Compartment prüfen und eine vorhandene importierte Ressource suchen. Siehe Importierte Modellberechtigungen.
- Python 3.11 oder höher,
uvund eine installierte OCI-CLI. Die Befehle verwenden eine Bash-kompatible Shell auf macOS, Linux oder Windows Subsystem für Linux. - Ein Browser für die OCI-CLI-Sessionauthentifizierung und den Zugriff auf den Serviceendpunkt. In diesen Beispielen wird US Midwest (Chicago) in der kommerziellen Realm OC1 verwendet.
In den Beispielen wird die OCI-IAM-Anforderungssignatur mit einem Sessiontoken und dessen Private Key verwendet. Ein OCI Generative AI-API-Schlüssel ist ein separater Zugangsdaten und ersetzt nicht den hier verwendeten Signaturgeber.
1. Umgebung vorbereiten und anmelden
2. Abfrageerkennung mit dem Python-SDK
In diesem Beispiel werden aktuelle On-Demand-Chatmodelle in der ausgewählten Region gesucht. Es folgt der Paginierung und druckt Modell-IDs, Anbieter und Funktionen. Die Helperfunktionen werden in späteren Beispielen wiederverwendet.
3. Discovery-REST-API direkt aufrufen
Eine direkte Anforderung stellt die HTTP-Methode, den Pfad, die Abfrageparameter und die Antwortheader bereit. Er ruft denselben Discovery-Vorgang auf wie das SDK. Für die Anforderung ist weiterhin eine OCI IAM-Autorisierung erforderlich.
GET /20231130/modelDiscovery?compartmentId=<your-compartment-ocid>4. Praktische Beispiele vorbereiten
Filter aus dem zurückgegebenen Katalog auswählen
Bevor Sie Filter auswählen, prüfen Sie die für die Modelle in Ihrer Region gemeldeten Werte:
catalog = fetch(region=[region])
for field in ("capabilities", "api_capability", "model_access", "vendor"):
counts = Counter()
for model in catalog:
values = model.get(field) or []
if isinstance(values, str):
values = [values]
counts.update(set(values))
print(field, dict(sorted(counts.items())))
for field in ("realm", "region", "serving_modes"):
counts = Counter()
for model in catalog:
values = set()
for availability in model.get("availability") or []:
value = availability.get(field)
if isinstance(value, list):
values.update(value)
elif value:
values.add(value)
counts.update(values)
print(field, dict(sorted(counts.items())))Jede Anzahl ist die Anzahl der zurückgegebenen Modelleinträge, die einem Wert zugeordnet sind. Ein Modell kann zu mehreren Funktions- oder Verfügbarkeitswerten beitragen. Die Anzahl entspricht den Abfragefiltern.
| SDK- Argument | Beispiel oder Zweck |
|---|---|
region, realm | Listen der Regions-IDs oder Realm-Werte. Vom Katalog gemeldete Werte verwenden |
model_id | Eine genaue Modell-ID. |
capability | Eine Liste wie ["CHAT"], ["TEXT_EMBEDDINGS"] oder ["TEXT_RERANK"]. |
api_capability | Eine Liste der API-IDs, die vom Katalog gemeldet werden. |
serving_mode | ["ON_DEMAND"] oder ["DEDICATED"]. |
model_access | ["HOSTED"] oder ["PROXY"]. |
is_deprecated | False schließt veraltete Modelle aus. |
is_on_demand_retired, is_dedicated_retired | Verwenden Sie False für den Bereitstellungsmodus, dessen stillgelegte Modelle Sie ausschließen möchten. |
page, limit | Paginierungstoken und angeforderte Seitengröße. Das Beispiel folgt auf opc-next-page, bis alle Seiten abgerufen werden. |
Verwenden Sie search_models(), um nach dem Abrufen aller Seiten eine Übereinstimmung mit lokalen Teilzeichenfolgen zu erhalten. Die Suche ist kein Parameter von ListModelDiscovery. Prüfen Sie die Arbeitsvorgangsreferenz für das vollständige Filtervokabular.
Zehn praktische Python-Beispiele
1. Modelle über beide Serviermodi hinweg durchsuchen
Filtern Sie nach der gewünschten Deployment-Region. Wenn Sie serving_mode auslassen, sind sowohl On-Demand- als auch dedizierte Modelle zulässig.
catalog = fetch(region=[region])
show(catalog)2. Modelle nach Teilname oder Lieferant suchen
Suchen Sie die zurückgegebenen Metadaten lokal. Jeder durch Leerzeichen getrennte Begriff muss mit einem durchsuchbaren Feld übereinstimmen. Beim Abgleich werden Groß-/Kleinschreibung und Satzzeichen ignoriert. Der model_id-Filter des Service erfordert eine genaue ID.
catalog = fetch(region=[region])
show(search_models(catalog, "grok"))Ändern Sie den Suchbegriff in den Ergebnissen in einen Mitarbeiter oder eine Modellfamilie.
3. Aktuelle On-Demand-Chatmodelle suchen
Schließen Sie veraltete Modelle und Modelle aus, die für On-Demand-Service eingestellt wurden.
show(fetch(
region=[region],
capability=["CHAT"],
serving_mode=["ON_DEMAND"],
is_deprecated=False,
is_on_demand_retired=False,
))4. Modelle für Dedicated Serving suchen
Wenden Sie den Ruhestandsfilter auf dedizierte Dienste an. Diese Abfrage durchsucht den Discovery-Katalog. Um die importierten Ressourcen aufzulisten, verwenden Sie Beispiel 8.
show(fetch(
region=[region],
serving_mode=["DEDICATED"],
is_deprecated=False,
is_dedicated_retired=False,
))5. Einbettungs- und Rangiermodelle suchen
Fragen Sie jede Funktion separat ab. Discovery verwendet TEXT_EMBEDDINGS und TEXT_RERANK. Importierte Modellressourcen verwenden ein anderes Funktionsvokabular, einschließlich EMBEDDING und RERANK.
for capability in ("TEXT_EMBEDDINGS", "TEXT_RERANK"):
print("\nCapability:", capability)
show(fetch(region=[region], capability=[capability]))6. Proxymodelle mit einer gemeldeten API-Funktion suchen
Lesen Sie die vom Katalog zurückgegebenen API-IDs, und kopieren Sie dann einen Wert, um die Proxymodelle zu filtern. Prüfen Sie die Hinweise zu externen Anrufen und die Datenverarbeitung für ein ausgewähltes Modell.
catalog = fetch(region=[region], model_access=["PROXY"])
api_values = sorted({
api for model in catalog for api in model.get("api_capability") or []
})
print(api_values)
if api_values:
api = input("Enter an API capability from the list: ").strip()
if api in api_values:
show(fetch(
region=[region],
model_access=["PROXY"],
api_capability=[api],
))
else:
print("Enter an exact value from the returned list.")
else:
print("No API capabilities were reported for these results.")7. Modellparameter und Lebenszyklusdetails prüfen
Kopieren Sie eine exakte Modellkennung aus Ihren Ergebnissen. Prüfen Sie die vollständigen Verfügbarkeitseinträge, um jede Region mit ihren Bereitstellungsmodi, Lebenszyklusdaten und gemeldeten Ersetzungen zu verknüpfen.
model_id = input("Enter an exact model ID from your results: ").strip()
for model in fetch(model_id=model_id):
print(model["model_id"])
for field in (
"api_capability", "modality_support", "parameters", "availability"
):
print(field)
print(json.dumps(model.get(field), indent=2, default=str))Ein Feld kann leer sein oder nicht gemeldet werden. Bewerten Sie alle vorgeschlagenen Ersetzungen mit Ihrer Anwendung, bevor Sie migrieren.
8. Importiertes Qwen-Modell suchen
Verwenden Sie source="imported", um vorhandene Importe in Ihrem Compartment und Ihrer Clientregion abzufragen. In diesem Beispiel wird nach einem Qwen 3.6 35B-Modell gesucht. Es gibt nur dann eine Übereinstimmung zurück, wenn Sie ein übereinstimmendes Modell importiert haben und diese Ressource prüfen können. Informationen zur Importkompatibilität finden Sie unter Kompatible Qwen 3.6-Modelle.
imports = fetch(source="imported")
selected = search_models(imports, "qwen 3.6 35B")
show(selected)
for model in selected:
print("Imported resource OCID:", model["id"])
print("Resource state:", model.get("lifecycle_state"))Die zurückgegebene OCID identifiziert die importierte Modellressource. Ein Ressourcenstatus ACTIVE stellt nicht fest, dass ein Inferenzendpunkt bereitgestellt wurde. Die Deployment-Schritte finden Sie unter Importierte Modelle verwalten.
9. Discovery mit importierten Ressourcen vergleichen
Vergleichen Sie die beiden Quellen, wenn ein Modell im importierten Bestand, aber nicht in der Erkennung angezeigt wird. Die Discovery-Ergebnisse und die in Ihr Compartment importierten Ressourcen beantworten verschiedene Fragen.
print("Discovery catalog for the selected region:")
show(search_models(fetch(region=[region]), "qwen"))
print("\nImported resources in this compartment and client region:")
show(search_models(fetch(source="imported"), "qwen"))Wenn importierte Ergebnisse leer sind, prüfen Sie das Compartment, die Clientregion und die Berechtigungen. Die Abfrage des importierten Modells scannt keine anderen Compartments oder Regionen.
10. Übereinstimmende importierte Modelle exportieren
Schreiben Sie die vollständigen Metadaten für ausgewählte importierte Ressourcen in eine lokale JSON-Datei.
selected = search_models(fetch(source="imported"), "qwen 3.6 35B")
Path("qwen-imports.json").write_text(
json.dumps({"items": selected}, indent=2, default=str),
encoding="utf-8",
)
print(f"Saved {len(selected)} matching resource(s) to qwen-imports.json")Ergebnis prüfen und Fehler beheben
Eine erfolgreiche Anforderung gibt Modellmetadaten oder eine leere Liste zurück, wenn keine Einträge übereinstimmen. Prüfen Sie IDs, Funktionen, Parameter und Verfügbarkeit, bevor Sie eine Inferenzanforderung erstellen.
| Symptom | Was zu überprüfen ist |
|---|---|
Das SDK enthält keine list_model_discovery-Methode. | Führen Sie ein Upgrade von oci in der aktiven virtuellen Umgebung durch, und wiederholen Sie die Methodenprüfung. |
| Eine signierte Anforderung gibt HTTP 401 zurück. | Validieren oder erstellen Sie die CLI-Session neu, prüfen Sie das ausgewählte Profil, und starten Sie Python neu, damit das neue Token gelesen wird. |
| Der Service meldet einen Autorisierungsfehler. | Prüfen Sie IAM-Berechtigungen und die Compartment-OCID. Importierter Bestand erfordert die Berechtigung zum Prüfen importierter Modellressourcen. |
| Ein exakter Modell-ID-Filter gibt keine Ergebnisse zurück. | Suchen oder suchen Sie zuerst lokal, und kopieren Sie dann eine ID aus der Antwort. Prüfen Sie die Regions- und Lebenszyklusfilter. |
| Die Antwort umfasst die Verfügbarkeit außerhalb der Endpunktregion. | Legen Sie den Discovery-Filter region explizit fest, und prüfen Sie jeden Verfügbarkeitseintrag. Die Endpunktregion allein schränkt keine Katalogergebnisse ein. |
| Es wurde kein importiertes Modell zurückgegeben. | Prüfen Sie die Region, das Compartment, die Berechtigungen und den Ressourcenanzeigenamen des Clients. Verwenden Sie list_imported_models() für importierten Bestand. |
| Es wird nur ein Teil des Katalogs zurückgegeben. | Folgen Sie opc-next-page. Die Python-Beispiele auf dieser Seite rufen alle Seiten ab. |
| Die REST-Anforderung ist nicht erfolgreich, während das SDK erfolgreich ist. | Verwenden Sie dasselbe Profil und Compartment. Prüfen Sie den Managementendpunkt, den Pfad und die Abfragenamen camelCase, und prüfen Sie dann den Status und die Anforderungs-ID. |
Der generierte CLI-Befehl finden Sie unter list-model-discovery. Informationen zu importierten Ressourcen finden Sie unter ListImportedModels. Die von der Discovery zurückgegebenen Metadatenfelder finden Sie unter ModelDiscovery.