Oracle Cloud Infrastructure-Dokumentation

Durchlauf für semantische Suche

Erfahren Sie, wie Sie eine semantische Suche nach den Daten mit OCI Search mit OpenSearch durchführen können.

Voraussetzungen

Bevor Sie beginnen, müssen Sie folgende Schritte ausführen:

  • Wählen Sie eines der vortrainierten Modelle aus, die von OCI Search mit OpenSearch unterstützt werden

  • Stellen Sie sicher, dass das Cluster OpenSearch Version 2.11 ist.

  • Aktualisieren Sie die Clustereinstellungen, um eine semantische Suche auszuführen. Mit dem folgenden Beispielbefehl werden die entsprechenden Einstellungen aktualisiert:

    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
      }
    }
  }
}

Modellgruppe registrieren

Mit Modellgruppen können Sie Modelle logisch gruppieren und steuern, wer Zugriff darauf erhält. Registrieren Sie eine Modellgruppe mit dem Vorgang registrieren in den Modellgruppen-APIs, wie im folgenden Beispiel dargestellt:

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

Notieren Sie sich die in der Antwort zurückgegebene model_group_id:

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

Modell registrieren und bereitstellen

Sie haben die folgenden drei Optionen für die semantische Suche:

  • Option 1: Registrieren Sie ein vorgeschultes Modell, das in OCI Search mit OpenSearch gehostet wird, und stellen Sie es bereit. Verwenden Sie dazu die unter Vorgeschultes Modell mit OpenSearch verwenden beschriebenen Schritte. Diese Option ist die einfachste zu verwendende Option. Sie müssen keine zusätzlichen IAM-Policys konfigurieren, und die Payload ist nicht so komplex wie die Payload für die nächste Option.
  • Option 2: Importieren, registrieren und stellen Sie ein vortrainiertes OpenSearch-Modell mit den unter Benutzerdefinierte Modelle beschriebenen Schritten bereit. Dazu gehört das Hochladen der Modelldatei in einen Objektspeicher-Bucket und das Angeben der Objektspeicher-URL der Modelldatei, wenn Sie das Modell registrieren.
  • Option 3: Sie können auch ein Remote-Modell zur GenAI-Einbettung wie cohere.embed-english-v3.0 in Ihrem Cluster über unseren GenAI-Connector registrieren und bereitstellen. Sie müssen zuerst einen Connector erstellen und dann das Modell mit der Connector-ID registrieren und bereitstellen, wie in den folgenden Schritten beschrieben.
    Hinweis

    Wenn Sie das ON-DEMAND-Modell verwenden, bleiben Sie mit den Modellverfallsbenachrichtigungen vom GenAI-Service auf dem neuesten Stand, und aktualisieren Sie den Connector bei Bedarf, um potenzielle Serviceunterbrechungen zu vermeiden. Unter Pretrained Foundational Models in Generative AI finden Sie die unterstützten Einbettungsmodelle, um ein Einbettungsmodell aus der Liste der unterstützten Modelle auszuwählen.

    Wenn Sie das Modell DEDICATED verwenden, ändern Sie den Parameter servingType im folgenden Payload-Beispiel von ON-DEMAND in DEDICATED.

Diese Schritt-für-Schritt-Anleitung zeigt, wie Sie Option 1, ein vortrainiertes Modell, verwenden.
Um ein vortrainiertes Modell zu registrieren, benötigen Sie Folgendes:
  • model_group_id: Wenn Sie Schritt 1 abgeschlossen haben, ist dies der Wert für model_group_id für die _register-Anforderung.
  • name: Der Modellname für das vorgeschulte Modell, das Sie verwenden möchten.
  • version: Die Versionsnummer für das zu verwendende vorgeschulte Modell.
  • model_format: Das Format für das Modell: TORCH_SCRIPT oder ONNX.

Registrieren Sie das Modell mit dem Vorgang registrieren über die Modell-APIs, wie im folgenden Beispiel dargestellt:

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"
}

Notieren Sie sich die in der Antwort zurückgegebene task_id. Mit der task_id können Sie den Status des Vorgangs prüfen.

Beispiel: Von der folgenden Antwort:

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

um den Status des Registrierungsvorgangs zu prüfen, verwenden Sie task_id mit dem Vorgang Get der Aufgaben-APIs, wie im folgenden Beispiel dargestellt: 

GET /_plugins/_ml/tasks/<task_ID>

Wenn der Kassenvorgang abgeschlossen ist, lautet der Wert state in der Antwort auf den Get-Vorgang COMPLETED, wie im folgenden Beispiel dargestellt: 

{
  "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
}

Notieren Sie sich den in der Antwort zurückgegebenen Wert model_ID, der beim Deployment des Modells verwendet werden soll.

Modell bereitstellen

Nachdem der Registrierungsvorgang für das Modell abgeschlossen ist, können Sie das Modell mit dem Deployment-Vorgang der Modell-APIs im Cluster bereitstellen und die model_ID aus der Antwort des Get-Vorgangs im vorherigen Schritt übergeben, wie im folgenden Beispiel dargestellt: 

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

Notieren Sie sich die in der Antwort zurückgegebene task_id. Mit der task_id können Sie den Status des Vorgangs prüfen.

Beispiel: Von der folgenden Antwort:

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

Um den Status des Registervorgangs zu prüfen, verwenden Sie task_ID mit dem Vorgang Get der Aufgaben-APIs, wie im folgenden Beispiel dargestellt: 

GET /_plugins/_ml/tasks/<task_ID>

Wenn der Deployment-Vorgang abgeschlossen ist, lautet der Wert status in der Antwort auf den Get-Vorgang COMPLETED.

k-NN-Aufnahmepipeline erstellen

Nachdem der Deployment-Vorgang abgeschlossen ist, erstellen Sie eine Aufnahmepipeline mit dem bereitgestellten Modell. Die Aufnahmepipeline verwendet das bereitgestellte Modell, um die Einbettungsvektoren für jedes Dokument bei der Aufnahme automatisch zu generieren. Der Prozessor verarbeitet alles für die Einbettung, so dass Sie nur das erwartete Textfeld im Dokument, das in die Einbettung konvertiert wird, entsprechend zuordnen müssen. Das folgende Beispiel zeigt das Erstellen einer Aufnahmepipeline:

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>"
        }
      }
    }
  ]
}

Wenn die Aufnahmepipeline erstellt wurde, wird die folgende Antwort zurückgegeben:

{
  "acknowledged": true
}

Index erstellen

Erstellen Sie einen Index mit der Aufnahme-Pipeline, die im vorherigen Schritt erstellt wurde. Sie können alle verfügbaren ANN-Engines im Index verwenden. Im folgenden Beispiel wird die Lucene Engine verwendet:

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"
            }
        }
    }
    }

Das Feld passage_text für den Erstellungsindex stimmt mit dem Feld passage_text in der Aufnahmepipeline überein. Dadurch weiß die Pipeline, wie Einbettungen erstellt werden, und ordnet sie bei der Aufnahme Dokumenten zu.

Informationen zur Auswahl der zu verwendenden Engine und der verfügbaren Konfigurationsparameter für diese Engines finden Sie unter k-NN-Index und Ungefähre k-NN-Suche.

Im Folgenden finden Sie eine Beispielantwort für eine erfolgreiche Indexerstellung:

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

Dokumente in den Index aufnehmen

Nehmen Sie Daten in den Index auf, wie im folgenden Beispiel gezeigt:

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"
}

Antwort:

# 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
}

Führen Sie den folgenden Befehl aus, um eines der Dokumente zu prüfen und sicherzustellen, dass Einbettungen korrekt generiert werden:

GET /lucene-index/_doc/3

Antwort:

{
  "_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,