Documentación de Oracle Cloud Infrastructure

Recorrido virtual por la búsqueda semántica

Obtenga información sobre cómo realizar una búsqueda semántica de los datos mediante OCI Search con OpenSearch.

Requisitos

Antes de comenzar, debe hacer lo siguiente:

  • Seleccione uno de los modelos previamente entrenados soportados por OCI Search con OpenSearch

  • Confirme que el cluster OpenSearch es la versión 2.11.

  • Actualice la configuración del cluster para realizar una búsqueda semántica. El siguiente comando de ejemplo actualiza la configuración aplicable:

    PUT _cluster/settings
{
  "persistent": {
    "plugins": {
      "ml_commons": {
        "only_run_on_ml_node": "false",
        "model_access_control_enabled": "true",
        "native_memory_threshold": "99",
        "rag_pipeline_feature_enabled": "true",
        "memory_feature_enabled": "true",
        "allow_registering_model_via_local_file": "true",
        "allow_registering_model_via_url": "true",
        "model_auto_redeploy.enable":"true",
        "model_auto_redeploy.lifetime_retry_times": 10
      }
    }
  }
}

Registrar el grupo de modelos

Utilice grupos de modelos para agrupar modelos de forma lógica y controlar quién obtiene acceso a ellos. Registre un grupo de modelos mediante la operación register en las API de grupo de modelos, como se muestra en el siguiente ejemplo:

POST /_plugins/_ml/model_groups/_register
{
  "name": "general pretrained models",
  "description": "A model group for pretrained models hosted by OCI Search with OpenSearch"
}

Anote el valor model_group_id devuelto en la respuesta:

{
  "model_group_id": "<model_group_ID>",
  "status": "CREATED"
}

Registrar y desplegar el modelo

Tiene las siguientes tres opciones para la búsqueda semántica:

  • Opción 1: registre y despliegue un modelo previamente entrenado alojado en OCI Search con OpenSearch mediante los pasos descritos en Uso de un modelo previamente entrenado OpenSearch. Esta opción es la más sencilla de usar, no necesita configurar ninguna política de IAM adicional y la carga útil no es tan compleja como la carga útil para la siguiente opción.
  • Opción 2: importe, registre y despliegue un modelo entrenado previamente OpenSearch mediante los pasos descritos en Modelos personalizados. Esto incluye cargar el archivo de modelo en un cubo de Object Storage y, a continuación, especificar la URL de Object Storage del archivo de modelo al registrar el modelo.
  • Opción 3: también puede registrar y desplegar un modelo de incrustación GenAI remoto, como cohere.embed-english-v3.0, en el cluster mediante nuestro conector GenAI. Primero debe crear un conector y, a continuación, registrar y desplegar el modelo con el ID de conector, como se describe en los siguientes pasos.
    Nota

    Si utiliza el modelo ON-DEMAND, manténgase al día con las notificaciones de desuso del modelo del servicio GenAI y actualice el conector cuando sea necesario para evitar posibles interrupciones del servicio. Consulte Modelos fundamentales previamente entrenados en IA generativa para conocer los modelos de incrustación soportados a fin de seleccionar un modelo de incrustación de la lista de modelos soportados.

    Si utiliza el modelo DEDICATED, cambie el parámetro servingType en el siguiente ejemplo de carga útil de ON-DEMAND a DEDICATED.

En este recorrido virtual se muestra cómo utilizar la opción 1, un modelo previamente entrenado.
Para registrar un modelo previamente entrenado, necesita lo siguiente:
  • model_group_id: si ha completado el paso 1, este es el valor de model_group_id para la solicitud _register.
  • name: nombre del modelo para el modelo previamente entrenado que desea utilizar.
  • version: número de versión del modelo previamente entrenado que desea utilizar.
  • model_format: formato del modelo, ya sea TORCH_SCRIPT o ONNX.

Registre el modelo mediante la operación register desde las API de modelo, como se muestra en el siguiente ejemplo:

POST /_plugins/_ml/models/_register
{
  "name": "huggingface/sentence-transformers/msmarco-distilbert-base-tas-b",
  "version": "1.0.2",
  "model_group_id": "<model_group_ID>",
  "model_format": "TORCH_SCRIPT"
}

Anote el valor task_id devuelto en la respuesta, puede utilizar task_id para comprobar el estado de la operación.

Por ejemplo, de la siguiente respuesta:

{
  "task_id": "<task_ID>",
  "status": "CREATED"
}

Para comprobar el estado de la operación de registro, utilice task_id con la operación Get de las API de tarea, como se muestra en el siguiente ejemplo: 

GET /_plugins/_ml/tasks/<task_ID>

Cuando se completa la operación de registro, el valor state en la respuesta a la operación Get es COMPLETED, como se muestra en el siguiente ejemplo: 

{
  "model_id": "<embedding_model_ID>",
  "task_type": "REGISTER_MODEL",
  "function_name": "TEXT_EMBEDDING",
  "state": "COMPLETED",
  "worker_node": [
    "f2b_8-mVRVyVqeKqsA7dcQ"
  ],
  "create_time": 1706831015570,
  "last_update_time": 1706831070740,
  "is_async": true
}

Anote el valor model_ID devuelto en la respuesta para utilizarlo al desplegar el modelo.

Despliegue del modelo

Una vez finalizada la operación de registro para el modelo, puede desplegar el modelo en el cluster mediante la operación desplegar de las API de modelo, transfiriendo model_ID de la respuesta de la operación Get del paso anterior, como se muestra en el siguiente ejemplo: 

POST /_plugins/_ml/models/<embedding_model_ID>/_deploy

Anote el valor task_id devuelto en la respuesta, puede utilizar task_id para comprobar el estado de la operación.

Por ejemplo, de la siguiente respuesta:

{
  "task_id": "<task_ID>",
  "task_type": "DEPLOY_MODEL",
  "status": "CREATED"
}

Para comprobar el estado de la operación de registro, utilice task_ID con la operación Get de las API de tareas, como se muestra en el siguiente ejemplo: 

GET /_plugins/_ml/tasks/<task_ID>

Cuando se completa la operación de despliegue, el valor status de la respuesta a la operación Get es COMPLETED.

Crear un pipeline de ingesta de k-NN

Una vez finalizada la operación de despliegue, cree un pipeline de ingesta con el modelo desplegado. El pipeline de ingestión utiliza el modelo desplegado para generar automáticamente los vectores de incrustación para cada documento en el momento de la ingestión. El procesador gestiona todo lo necesario para la incrustación, por lo que solo es necesario asignar adecuadamente el campo de texto esperado en el documento que se está convirtiendo en incrustación. En el siguiente ejemplo se muestra la creación de un pipeline de ingesta:

PUT _ingest/pipeline/<pipeline_name>
{
  "description": "An example neural search pipeline",
  "processors" : [
    {
      "text_embedding": {
        "model_id": "<embedding_model_ID>",
        "field_map": {
           "<text_field_name>": "<embedding_field_name>"
        }
      }
    }
  ]
}

Si se creó el pipeline de ingestión, se devuelve la siguiente respuesta:

{
  "acknowledged": true
}

Crear índice

Cree un índice mediante el pipeline de ingestión creado en el paso anterior. Puede utilizar cualquiera de los motores ANN disponibles en el índice. En el siguiente ejemplo se utiliza el motor Lucene:

PUT /lucene-index
{
    "settings": {
        "index.knn": true,
        "default_pipeline": "<pipeline_name>"
    },
    "mappings": {
        "properties": {
            "<embedding_field_name>": {
                "type": "knn_vector",
                "dimension": <model_dimension>,
                "method": {
                    "name":"hnsw",
                    "engine":"lucene",
                    "space_type": "l2",
                    "parameters":{
                        "m":512,
                        "ef_construction": 245
                    }
                }
            },
            "<text_field_name>": {
                "type": "text"
            }
        }
    }
    }

El campo passage_text para el índice de creación coincide con el campo passage_text en el pipeline de ingestión, lo que hace que el pipeline sepa cómo crear incrustaciones y, a continuación, asignarlas a documentos en el momento de la ingestión.

Para ayudarle a elegir el motor que desea utilizar y los parámetros de configuración disponibles para esos motores, consulte k-NN index y Approximate k-NN search.

A continuación se muestra un ejemplo de respuesta para una creación correcta de índice:

{
        "acknowledged": true,
        "shards_acknowledged": true,
        "index": "lucene-index"
}

Ingestión de documentos en el índice

Ingiera datos en el índice como se muestra en el siguiente ejemplo:

POST /lucene-index/_doc/1
{
  "<text_field_name>": "there are many sharks in the ocean"
}
 
POST /lucene-index/_doc/2
{
  "<text_field_name>": "fishes must love swimming"
}
 
POST /lucene-index/_doc/3
{
  "<text_field_name>": "summers are usually very hot"
}
 
POST /lucene-index/_doc/4
{
  "<text_field_name>": "florida has a nice weather all year round"
}

Respuesta:

# POST /lucene-index/_doc/1
{
  "_index": "lucene-index",
  "_id": "1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}
# POST /lucene-index/_doc/2
{
  "_index": "lucene-index",
  "_id": "2",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 1,
  "_primary_term": 1
}
# POST /lucene-index/_doc/3
{
  "_index": "lucene-index",
  "_id": "3",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 2,
  "_primary_term": 1
}
# POST /lucene-index/_doc/4
{
  "_index": "lucene-index",
  "_id": "4",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 3,
  "_primary_term": 1
}

Ejecute lo siguiente para comprobar uno de los documentos y asegurarse de que las incrustaciones se generan correctamente:

GET /lucene-index/_doc/3

Respuesta:

{
  "_index": "lucene-index",
  "_id": "3",
  "_version": 1,
  "_seq_no": 2,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "<embedding_field_list>": [
      -0.1254959,
      -0.3151774,
      0.03526799,
      0.39322096,
      -0.0475556,
      -0.12378334,
      -0.032554347,
      0.4033895,
      0.050718695,
      -0.3587931,
      0.097042784,
      0.11742551,
      -0.06573639,
      0.14252506,
      -0.466573,
      0.56093556,
      -0.2815812,
      -0.00016521096,
      -0.2858566,