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.

MetadatosQué informaCómo usarlo
Identidad y proveedorIdentificadores de modelo e información del proveedor.Busque un proveedor y copie un ID de modelo exacto.
Tareas y modalidadesCapacidades de modelo y tipos de entrada a salida soportados.Identifique candidatos para flujos de trabajo de chat, incrustaciones, repetición o multimodales.
Compatibilidad con APICapacidades de API de inferencia informadas para el modelo.Seleccione una API que admita el modelo.
Disponibilidad RegionalDominios, regiones y modos de servicio bajo demanda o dedicados.Busque candidatos para su ubicación de despliegue y modo de servicio.
Acceso alojado o proxyClasificación de acceso del modelo.Revise la documentación de despliegue y manejo de datos adecuada.
ParámetrosNombres, tipos, rangos, valores por defecto y descripciones informados.Cree formularios de configuración y compruebe los valores de los metadatos devueltos.
Ciclo de vidaFechas 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.
FiltrosID 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.

Nota

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. ListModelDiscovery necesita GENERATIVE_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, uv y 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

  1. Cree y active un entorno virtual de Python e instale los paquetes:
    uv venv --python 3.11 .venv
    source .venv/bin/activate
    uv pip install --upgrade oci requests

    Si el entorno ya existe, actívelo antes de instalar o actualizar los paquetes.

  2. Compruebe que el SDK instalado proporciona el método de detección y que la CLI de OCI está disponible:
    python -c 'import oci; print(oci.__version__); print(hasattr(oci.generative_ai.GenerativeAiClient, "list_model_discovery"))'
    oci --version

    La comprobación del método debe imprimir True. Si imprime False, instale una versión de SDK que incluya list_model_discovery.

  3. Defina el perfil de ejemplo, la región de punto final y el compartimento para este shell:
    export OCI_DISCOVERY_PROFILE=GENAI_DISCOVERY
    export OCI_DISCOVERY_REGION=us-chicago-1
    export OCI_COMPARTMENT_ID='<your-compartment-ocid>'

    Sustituya el marcador de posición del compartimento por un compartimento al que pueda acceder. GENAI_DISCOVERY es el nombre de perfil de ejemplo. Los scripts leen estas variables de entorno sin utilizar un compartimento por defecto.

  4. Cree una sesión de CLI y complete el inicio de sesión del explorador:
    oci session authenticate \
      --profile-name "$OCI_DISCOVERY_PROFILE" \
      --region "$OCI_DISCOVERY_REGION"

    La CLI almacena el perfil en ~/.oci/config. Los ejemplos de Python cargan el token de sesión y la clave privada del perfil con SecurityTokenSigner. Cuando caduque la sesión, vuelva a autenticarse y reinicie el script o la sesión interactiva de Python. Consulte Autenticación basada en tokens para la CLI.

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.

  1. Guarde el siguiente código como model_discovery.py en el directorio de trabajo:
    """Query OCI Generative AI model metadata with an IAM session."""
    
    import os
    import re
    import unicodedata
    from pathlib import Path
    
    import oci
    
    
    def load_session():
        config = oci.config.from_file(
            profile_name=os.environ["OCI_DISCOVERY_PROFILE"]
        )
        config["region"] = os.environ["OCI_DISCOVERY_REGION"]
        token = Path(config["security_token_file"]).expanduser().read_text(
            encoding="utf-8"
        ).strip()
        private_key = oci.signer.load_private_key_from_file(
            str(Path(config["key_file"]).expanduser()),
            config.get("pass_phrase"),
        )
        signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
        return config, signer
    
    
    def make_client():
        config, signer = load_session()
        return oci.generative_ai.GenerativeAiClient(config, signer=signer)
    
    
    def fetch_models(client, compartment_id, source="discovery", **filters):
        if source not in {"discovery", "imported"}:
            raise ValueError("source must be discovery or imported")
        operation = (
            client.list_model_discovery
            if source == "discovery"
            else client.list_imported_models
        )
        items = []
        while True:
            response = operation(compartment_id=compartment_id, **filters)
            items.extend(oci.util.to_dict(response.data)["items"])
            next_page = response.headers.get("opc-next-page")
            if not next_page:
                return items
            filters["page"] = next_page
    
    
    def normalized(value):
        value = unicodedata.normalize("NFKC", str(value)).casefold()
        return " ".join(re.findall(r"[^\W\d_]+|\d+", value))
    
    
    def search_models(models, query):
        terms = [normalized(term) for term in query.split()]
        terms = [term for term in terms if term]
    
        def matches(model):
            values = [
                model.get(field)
                for field in ("model_id", "id", "display_name", "vendor", "version")
            ]
            values.extend(
                value for value in (model.get("data_source") or {}).values()
                if isinstance(value, str)
            )
            candidates = [normalized(value) for value in values if value]
            return all(
                any(
                    re.search(
                        (r"(?<!\d)" if term[0].isdigit() else "")
                        + re.escape(term),
                        value,
                    )
                    for value in candidates
                )
                for term in terms
            )
    
        return [model for model in models if matches(model)]
    
    
    def show(models):
        print(f"{len(models)} matching model(s)")
        for model in models:
            name = (
                model.get("model_id")
                or model.get("display_name")
                or model.get("id")
            )
            capabilities = ", ".join(model.get("capabilities") or [])
            vendor = model.get("vendor") or "not reported"
            print(f"{name} | vendor={vendor} | capabilities={capabilities}")
    
    
    if __name__ == "__main__":
        client = make_client()
        models = fetch_models(
            client,
            os.environ["OCI_COMPARTMENT_ID"],
            region=[os.environ["OCI_DISCOVERY_REGION"]],
            capability=["CHAT"],
            serving_mode=["ON_DEMAND"],
            is_deprecated=False,
            is_on_demand_retired=False,
        )
        show(models)
  2. Ejecute el script en el entorno activado:
    python model_discovery.py
  3. Revise los modelos coincidentes y copie el identificador que desea inspeccionar.

    Los resultados dependen del catálogo actual y de los filtros. Un resultado vacío no es una prueba de autenticación ni una prueba de que no se puede importar un modelo.

    El SDK deriva su punto final de gestión de config["region"]. El argumento region=[...] independiente filtra la disponibilidad del catálogo. Ninguno de los dos valores configura un punto final de inferencia.

    Para obtener detalles del método, consulte GenerativeAiClient.list_model_discovery.

Tiene una consulta de detección paginada y funciones reutilizables para la búsqueda local y el inventario de modelos importados.

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>
  1. Defina el punto final público de gestión de Chicago:
    export OCI_DISCOVERY_ENDPOINT=https://generativeai.us-chicago-1.oci.oraclecloud.com

    En este ejemplo se utiliza el punto final de Chicago OC1. Para otra región o dominio, utilice el punto final de gestión adecuado en la referencia de API y actualice OCI_DISCOVERY_REGION para el filtro de catálogo. La detección utiliza la API de gestión, no una URL de inferencia de chat.

  2. Enviar una solicitud firmada con la CLI de OCI:
    oci raw-request \
      --profile "$OCI_DISCOVERY_PROFILE" \
      --auth security_token \
      --http-method GET \
      --target-uri "${OCI_DISCOVERY_ENDPOINT}/20231130/modelDiscovery?compartmentId=${OCI_COMPARTMENT_ID}&region=${OCI_DISCOVERY_REGION}&capability=CHAT&servingMode=ON_DEMAND&isDeprecated=false&isOnDemandRetired=false"

    La CLI firma la solicitud y muestra la respuesta. Para recuperar otra página, transfiera el valor opc-next-page devuelto como parámetro de consulta page codificado en URL. El siguiente ejemplo de Python sigue automáticamente la paginación.

  3. Guarde el siguiente código como model_discovery_rest.py junto con model_discovery.py:

    El script importa el ayudante de firma de sesión del ejemplo de SDK. Envía solicitudes HTTP a través de requests e imprime el estado y los ID de solicitud al error estándar.

    """Call Model Discovery over HTTP with OCI request signing."""
    
    import os
    import sys
    
    import requests
    
    from model_discovery import load_session
    
    
    def fetch_rest_models(signer, endpoint, compartment_id, region):
        url = endpoint.rstrip("/") + "/20231130/modelDiscovery"
        params = {
            "compartmentId": compartment_id,
            "region": [region],
            "capability": ["CHAT"],
            "servingMode": ["ON_DEMAND"],
            "isDeprecated": "false",
            "isOnDemandRetired": "false",
        }
        items = []
        while True:
            response = requests.get(
                url,
                params=params,
                headers={"Accept": "application/json"},
                auth=signer,
                timeout=(10, 30),
                allow_redirects=False,
            )
            request_id = response.headers.get("opc-request-id", "not reported")
            print(
                f"HTTP {response.status_code} | request ID: {request_id}",
                file=sys.stderr,
            )
            if 300 <= response.status_code < 400:
                raise RuntimeError("Check the service endpoint. Redirect not followed.")
            response.raise_for_status()
            items.extend(response.json()["items"])
            next_page = response.headers.get("opc-next-page")
            if not next_page:
                return items
            params["page"] = next_page
    
    
    if __name__ == "__main__":
        _, signer = load_session()
        models = fetch_rest_models(
            signer,
            os.environ["OCI_DISCOVERY_ENDPOINT"],
            os.environ["OCI_COMPARTMENT_ID"],
            os.environ["OCI_DISCOVERY_REGION"],
        )
        print(f"{len(models)} matching model(s)")
        for model in models:
            print(f"{model['modelId']} | vendor={model.get('vendor') or 'not reported'}")
  4. Ejecute el ejemplo de REST:
    python model_discovery_rest.py
  5. Compare los identificadores de modelo con los resultados del SDK.

    Utilice el mismo perfil, compartimento, región de punto final y filtros para la comparación. Los resultados pueden cambiar a medida que cambia el catálogo.

    Los campos de respuesta de REST utilizan camelCase, como modelId. La salida oci.util.to_dict() del SDK utiliza snake_case, como model_id. Para los filtros REST con valor de lista, repita la clave de consulta, por ejemplo, region=us-chicago-1&region=us-ashburn-1. El paquete requests codifica las listas en params de esta manera.

4. Preparación de ejemplos prácticos

  1. Guarde esta configuración como model_discovery_recipes.py junto con model_discovery.py:
    import json
    import os
    from collections import Counter
    from pathlib import Path
    
    from model_discovery import fetch_models, make_client, search_models, show
    
    client = make_client()
    compartment_id = os.environ["OCI_COMPARTMENT_ID"]
    region = os.environ["OCI_DISCOVERY_REGION"]
    
    
    def fetch(source="discovery", **filters):
        return fetch_models(client, compartment_id, source=source, **filters)
  2. Inicie Python con la configuración cargada:
    python -i model_discovery_recipes.py

    La opción -i mantiene abierto Python. Ejecute cualquier ejemplo en las siguientes secciones de esa sesión. También puede agregar un ejemplo al archivo de configuración y ejecutarlo sin -i.

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 SDKEjemplo o finalidad
region, realmListas de identificadores de región o valores de dominio. Utilizar los valores notificados por el catálogo.
model_idUn identificador de modelo exacto.
capabilityUna lista como ["CHAT"], ["TEXT_EMBEDDINGS"] o ["TEXT_RERANK"].
api_capabilityLista de identificadores de API informados por el catálogo.
serving_mode["ON_DEMAND"] o ["DEDICATED"].
model_access["HOSTED"] o ["PROXY"].
is_deprecatedFalse excluye los modelos en desuso.
is_on_demand_retired, is_dedicated_retiredUtilice False para el modo de servicio cuyos modelos dados de baja desea excluir.
page, limitToken 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íntomaQué 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.