Detección de modelos con el SDK de Python y la API de REST
Explore el catálogo de modelos de OCI Generative AI, filtre modelos para su aplicación e inspeccione los metadatos del modelo con solicitudes REST y SDK de Python firmados.
Descripción general
La API de detección de modelos reúne los identificadores de modelo, las capacidades, la compatibilidad de API, los parámetros de configuración y la disponibilidad regional. Utilice estos metadatos para seleccionar modelos para un asistente de chat, una aplicación de búsqueda o un flujo de trabajo multimodal antes de escribir una solicitud de inferencia.
Las aplicaciones pueden consultar el catálogo para crear interfaces de selección de modelos y refrescar las opciones disponibles. La información del ciclo de vida regional le ayuda a planificar actualizaciones y evaluar sustituciones informadas.
| Metadatos | Qué informa | Cómo usarlo |
|---|---|---|
| Identidad y proveedor | Identificadores de modelo e información del proveedor. | Busque un proveedor y copie un ID de modelo exacto. |
| Tareas y modalidades | Capacidades de modelo y tipos de entrada a salida soportados. | Identifique candidatos para flujos de trabajo de chat, incrustaciones, repetición o multimodales. |
| Compatibilidad con API | Capacidades de API de inferencia informadas para el modelo. | Seleccione una API que admita el modelo. |
| Disponibilidad Regional | Dominios, regiones y modos de servicio bajo demanda o dedicados. | Busque candidatos para su ubicación de despliegue y modo de servicio. |
| Acceso alojado o proxy | Clasificación de acceso del modelo. | Revise la documentación de despliegue y manejo de datos adecuada. |
| Parámetros | Nombres, tipos, rangos, valores por defecto y descripciones informados. | Cree formularios de configuración y compruebe los valores de los metadatos devueltos. |
| Ciclo de vida | Fechas de desuso y baja por región y modo de servicio, más sustituciones cuando se proporcionan. | Identifique los despliegues afectados y evalúe a los candidatos para la migración. |
| Filtros | ID de modelo, dominio, región, capacidad, capacidad de API, modo de servicio, tipo de acceso y estado del ciclo de vida. | Cree un selector de modelos específico o automatice las búsquedas en el catálogo. |
Los modelos individuales pueden no rellenar todos los campos. La detección le ayuda a seleccionar y configurar modelos. No llama a la inferencia, otorga acceso ni compara la calidad del modelo. Valide un modelo seleccionado y cualquier sustitución sugerida con la carga de trabajo de la aplicación.
En este tutorial, se autenticará con una sesión de OCI IAM, se realizará la detección de consultas con el SDK de Python, se enviará la misma solicitud a través de REST y se probarán diez ejemplos prácticos. También aprenderá a mostrar los modelos que ya se han importado al compartimento.
La operación es ListModelDiscovery. Es distinto de
list_models(), list_imported_models() y el punto final /models compatible con OpenAI. El envío de una solicitud de descubrimiento a Chicago no restringe los resultados del catálogo a Chicago. Utilice un filtro region para seleccionar la región del catálogo.Antes de empezar
Para completar este tutorial, necesita:
- Una cuenta de OCI y un compartimento en el que puede inspeccionar modelos.
ListModelDiscoverynecesitaGENERATIVE_AI_MODEL_INSPECT. Consulte Permisos de modelo. - Para los ejemplos de modelos importados, permiso para inspeccionar los modelos importados en el compartimento seleccionado y un recurso importado existente que buscar. Consulte Permisos de modelo importados.
- Python 3.11 o posterior,
uvy una CLI de OCI instalada. Los comandos utilizan un shell compatible con Bash en macOS, Linux o el subsistema Windows para Linux. - Un explorador para la autenticación de sesión de la CLI de OCI y el acceso al punto final del servicio. Estos ejemplos utilizan el medio oeste de EE. UU. (Chicago) en el dominio comercial OC1.
En los ejemplos se utiliza la firma de solicitudes de OCI IAM con un token de sesión y su clave privada. Una clave de API de OCI Generative AI es una credencial independiente y no sustituye al firmante utilizado aquí.
1. Preparación del entorno e inicio de sesión
2. Detección de consultas con el SDK de Python
En este ejemplo se encuentran los modelos de chat bajo demanda actuales en la región seleccionada. Sigue la paginación e imprime los ID de modelo, los proveedores y las capacidades. Las funciones auxiliares se reutilizan en ejemplos posteriores.
3. Llamada directa a la API de REST de detección
Una solicitud directa expone el método HTTP, la ruta de acceso, los parámetros de consulta y las cabeceras de respuesta. Llama a la misma operación de detección que el SDK. La solicitud aún necesita autorización de OCI IAM.
GET /20231130/modelDiscovery?compartmentId=<your-compartment-ocid>4. Preparación de ejemplos prácticos
Seleccionar filtros del catálogo devuelto
Antes de seleccionar filtros, inspeccione los valores informados para los modelos de su región:
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())))Cada recuento es el número de entradas de modelo devueltas asociadas a un valor. Un modelo puede contribuir a varios valores de capacidad o disponibilidad. Los recuentos reflejan los filtros de consulta.
| Argumento SDK | Ejemplo o finalidad |
|---|---|
region, realm | Listas de identificadores de región o valores de dominio. Utilizar los valores notificados por el catálogo. |
model_id | Un identificador de modelo exacto. |
capability | Una lista como ["CHAT"], ["TEXT_EMBEDDINGS"] o ["TEXT_RERANK"]. |
api_capability | Lista de identificadores de API informados por el catálogo. |
serving_mode | ["ON_DEMAND"] o ["DEDICATED"]. |
model_access | ["HOSTED"] o ["PROXY"]. |
is_deprecated | False excluye los modelos en desuso. |
is_on_demand_retired, is_dedicated_retired | Utilice False para el modo de servicio cuyos modelos dados de baja desea excluir. |
page, limit | Token de paginación y tamaño de página solicitado. El ejemplo sigue a opc-next-page hasta que se recuperan todas las páginas. |
Utilice search_models() para la coincidencia de subcadena local después de recuperar todas las páginas. La búsqueda no es un parámetro de ListModelDiscovery. Revise la referencia de operación para obtener el glosario de filtro completo.
Diez ejemplos prácticos de Python
1. Examinar modelos en ambos modos de servicio
Filtre por la región de despliegue deseada. Si se omite serving_mode, los modelos bajo demanda y dedicados serán elegibles.
catalog = fetch(region=[region])
show(catalog)2. Buscar modelos por nombre parcial o proveedor
Busque los metadatos devueltos localmente. Cada término separado por espacios debe coincidir con un campo apto para búsqueda. La coincidencia ignora las mayúsculas y minúsculas y la puntuación. El filtro model_id del servicio requiere un identificador exacto.
catalog = fetch(region=[region])
show(search_models(catalog, "grok"))Cambie el término de búsqueda a un profesional asistencial o familia de modelos en los resultados.
3. Buscar modelos de chat a demanda actuales
Excluya los modelos en desuso y los modelos retirados para la prestación bajo demanda.
show(fetch(
region=[region],
capability=["CHAT"],
serving_mode=["ON_DEMAND"],
is_deprecated=False,
is_on_demand_retired=False,
))4. Buscar modelos para servicios dedicados
Aplique el filtro de jubilación para una porción dedicada. Esta consulta busca en el catálogo de detección. Para mostrar los recursos que ha importado, utilice el ejemplo 8.
show(fetch(
region=[region],
serving_mode=["DEDICATED"],
is_deprecated=False,
is_dedicated_retired=False,
))5. Buscar modelos de inserción y cambio de nombre
Consultar cada capacidad por separado. La detección utiliza TEXT_EMBEDDINGS y TEXT_RERANK. Los recursos de modelo importados utilizan un vocabulario de capacidad diferente, incluidos EMBEDDING y RERANK.
for capability in ("TEXT_EMBEDDINGS", "TEXT_RERANK"):
print("\nCapability:", capability)
show(fetch(region=[region], capability=[capability]))6. Búsqueda de modelos de proxy con una capacidad de API informada
Lea los identificadores de API devueltos por el catálogo y, a continuación, copie un valor para filtrar los modelos de proxy. Revise las notas de llamada externa y el manejo de datos para un modelo seleccionado.
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. Inspeccionar parámetros de modelo y detalles de ciclo de vida
Copie un identificador de modelo exacto de los resultados. Inspeccione las entradas de disponibilidad completas para mantener cada región asociada a sus modos de servicio, fechas de ciclo de vida y sustituciones informadas.
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))Un campo puede estar vacío o no se puede informar. Evalúe cualquier sustitución sugerida con la aplicación antes de migrar.
8. Búsqueda de un modelo Qwen importado
Utilice source="imported" para consultar las importaciones existentes en el compartimento y la región de cliente. En este ejemplo se busca un modelo 35B de Qwen 3.6. Devuelve una coincidencia solo si ha importado un modelo coincidente y puede inspeccionar ese recurso. Consulte Compatible Qwen 3.6 Models para conocer la compatibilidad de las importaciones.
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"))El OCID devuelto identifica el recurso de modelo importado. Un estado de recurso ACTIVE no establece que se haya desplegado un punto final de inferencia. Para conocer los pasos de despliegue, consulte Gestión de modelos importados.
9. Comparación de Detección con Recursos Importados
Compare los dos orígenes cuando un modelo aparezca en el inventario importado pero no en la detección. Los resultados de la detección y los recursos importados en el compartimento responden a diferentes preguntas.
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"))Si los resultados importados están vacíos, compruebe el compartimento, la región de cliente y los permisos. La consulta de modelo importado no explora otros compartimentos ni regiones.
10. Exportar modelos importados coincidentes
Escriba los metadatos completos para los recursos importados seleccionados en un archivo JSON local.
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")Verificación del resultado y resolución de problemas
Una solicitud correcta devuelve metadatos de modelo o una lista vacía cuando no hay ninguna entrada que coincida. Revise los identificadores, las capacidades, los parámetros y la disponibilidad antes de crear una solicitud de inferencia.
| Síntoma | Qué comprobar |
|---|---|
El SDK no tiene ningún método list_model_discovery. | Actualice oci en el entorno virtual activo y repita la comprobación del método. |
| Una solicitud firmada devuelve HTTP 401. | Valide o vuelva a crear la sesión de CLI, compruebe el perfil seleccionado y reinicie Python para que lea el nuevo token. |
| El servicio informa un error de autorización. | Compruebe los permisos de IAM y el OCID del compartimento. El inventario importado necesita permiso para inspeccionar los recursos del modelo importado. |
| Un filtro de ID de modelo exacto no devuelve ningún resultado. | Busque o busque localmente primero y, a continuación, copie un identificador de la respuesta. Compruebe los filtros de región y ciclo de vida. |
| La respuesta incluye disponibilidad fuera de la región de punto final. | Defina el filtro region de detección de forma explícita e inspeccione cada entrada de disponibilidad. La región de punto final por sí sola no limita los resultados del catálogo. |
| No se devolvió un modelo importado. | Compruebe la región, el compartimento, los permisos y el nombre mostrado del recurso del cliente. Use list_imported_models() para el inventario importado. |
| Solo se devuelve una parte del catálogo. | Siga a opc-next-page. Los ejemplos de Python de esta página recuperan todas las páginas. |
| La solicitud de REST falla mientras el SDK se realiza correctamente. | Utilice el mismo perfil y compartimento. Compruebe el punto final de gestión, la ruta de acceso y los nombres de consulta camelCase y, a continuación, revise el estado y el ID de solicitud. |
Para conocer el comando de la CLI generado, consulte list-model-discovery. Para conocer los recursos importados, consulte ListImportedModels. Para conocer los campos de metadatos devueltos por la detección, consulte ModelDiscovery.