Dokumente mit Vector Stores und OCI Generative AI-API-Schlüsseln suchen

Erstellen Sie einen Vektorspeicher, laden Sie ein Dokument hoch und nehmen Sie es auf, und durchsuchen Sie dessen Inhalt mit curl oder dem Python-SDK OpenAI mit einem OCI Generative AI-API-Schlüssel.

Überblick

Ein Vektorspeicher macht Ihre Dokumente nach Bedeutung durchsuchbar. Sie laden eine Datei hoch, nehmen sie in den Shop auf und suchen mit einer Frage in natürlicher Sprache. Der Service gibt relevante Passagen, Dateinamen und Relevanzscores zurück. Abgerufene Passagen können auch Kontext für eine Sprachmodellanwendung bereitstellen.

Verwenden Sie Vektorspeicher, um Richtlinien, Produktleitfäden und Supportartikel zu durchsuchen, ohne eine eigene Dokumentparsing- und Einbettungspipeline zu erstellen. Eine Einführung finden Sie unter Vector Stores and Semantic Stores.

In diesem Tutorial führen Sie die folgenden Schritte aus:

  • Vektorspeicher erstellen, abrufen und auflisten
  • Laden Sie ein Beispieldokument hoch, und nehmen Sie es in durchsuchbare Blöcke auf.
  • Suchen Sie das Dokument, und prüfen Sie übereinstimmende Passagen.
  • Benennen Sie den Speicher um, und löschen Sie die Testressourcen.

Jede nummerierte Aufgabe enthält ein curl-Beispiel und ein Python-(OpenAI-SDK-)Beispiel. Wählen Sie einen Pfad und folgen Sie ihm von Anfang bis Ende. In den curl-Beispielen werden HTTP-Anforderungen von Bash erstellt. In den Python-Beispielen wird das für den Aufruf von OCI konfigurierte OpenAI-SDK verwendet. Beide Pfade authentifizieren sich mit einem OCI Generative AI-API-Schlüssel und erfordern keine OCI-CLI-Session.

Bevor Sie beginnen

Um dieses Tutorial abzuschließen, benötigen Sie:

Die Beispiele verwenden diese OCI-Basis-URL:

https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1

Verwenden Sie den Serviceendpunkt für die ausgewählte Region. Behalten Sie im gesamten Tutorial denselben Endpunkt, dasselbe Compartment und dasselbe Projekt bei.

Das Beispieldokument enthält eine fiktive Shop-Richtlinie. Ersetzen Sie nur die Verbindungsplatzhalter durch Ihre eigenen Werte. Die Beispiele fordern den API-Schlüssel an, ohne ihn anzuzeigen oder in den Quellcode aufzunehmen.

curl-Pfad einrichten

Ersetzen Sie in einem Bash-Terminal die Compartment- und Projektplatzhalter, und führen Sie dann Folgendes aus:

set -o pipefail
export GENAI_BASE_URL='https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1'
export GENAI_COMPARTMENT_ID='<your-compartment-ocid>'
export GENAI_PROJECT_ID='<your-project-ocid>'

read -r -s -p 'OCI Generative AI API key: ' GENAI_API_KEY
printf '\n'
export GENAI_API_KEY

VECTOR_STORES_URL="$GENAI_BASE_URL/vector_stores"
FILES_URL="$GENAI_BASE_URL/files"

Führen Sie jedes curl-Beispiel in diesem Terminal aus, damit die Einstellungen und zurückgegebenen Ressourcen-IDs verfügbar bleiben. Anforderungen senden den Bearer-API-Schlüssel und opc-compartment-id. Dateiuploads und das Löschen von Dateien senden auch OpenAI-Project, um Ihr OCI-Projekt zu identifizieren. Legen Sie die Basis-URL ohne einen abschließenden Schrägstrich fest.

Wenn ein Befehl fehlschlägt, beheben Sie den Fehler, bevor Sie fortfahren. Behalten Sie die IDs bei, die von erfolgreichen Bereinigungsanforderungen zurückgegeben werden. Führen Sie keinen erfolgreichen Befehl zum Erstellen oder Hochladen erneut aus, nur um den Status einer Ressource abzurufen.

Python-Pfad einrichten

Erstellen und aktivieren Sie eine virtuelle Umgebung, und installieren Sie dann das Python-SDK OpenAI:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

Erstellen Sie vector_store_tutorial.py mit dem folgenden Setup. Ersetzen Sie die Compartment- und Projektplatzhalter. Hängen Sie dann den Python-Block von jeder der acht nummerierten Aufgaben in der richtigen Reihenfolge an. Alle Blöcke verwenden dieselben Client- und Ressourcenvariablen.

import getpass
import time

from openai import OpenAI

BASE_URL = "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1"
COMPARTMENT_ID = "<your-compartment-ocid>"
PROJECT_ID = "<your-project-ocid>"
API_KEY = getpass.getpass("OCI Generative AI API key: ")

client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL.rstrip("/") + "/",
    default_headers={"opc-compartment-id": COMPARTMENT_ID},
    timeout=30,
)

Nachdem Sie das Beispieldokument gespeichert und alle Python-Blöcke assembliert haben, führen Sie das fertiggestellte Skript aus demselben Verzeichnis aus:

python vector_store_tutorial.py

Das abgeschlossene Skript erstellt Ressourcen, durchsucht das Dokument und löscht den Speicher und die hochgeladene Datei. Um weitere Fragen vor der Bereinigung zu versuchen, fügen Sie Suchaufrufe nach Aufgabe 6 und vor dem Löschblock hinzu. Wenn das Skript bei einem Fehler gestoppt wird, prüfen und bereinigen Sie die bereits erstellten Ressourcen mit den vor dem Fehler gedruckten Ressourcen-IDs.

Beispieldokument vorbereiten

Speichern Sie diese fiktive Policy unter sample-document.txt in dem Verzeichnis, in dem Sie die curl-Befehle oder das Python-Skript ausführen:

Example shop policy

Returns
Customers can return unused purchases within 30 days of delivery.
Include the order number and keep the item in its original packaging.
Contact support before shipping a return.
Refunds go to the original payment method.

Delivery
Standard delivery usually takes 3 to 5 business days.
Express delivery usually takes 1 to 2 business days.

1. Vektorspeicher erstellen

Erstellen Sie einen leeren Shop mit einem erkennbaren Namen. Im Beispiel wird eine Ablauf-Policy von einem Tag basierend auf last_active_at festgelegt. Beim Erstellen des Shops wird kein Dokument hochgeladen oder aufgenommen.

Führen Sie das Beispiel für den ausgewählten Pfad aus.

curl

STORE_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "$VECTOR_STORES_URL" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header 'Content-Type: application/json' \
  --data '{"name":"document-search-demo","expires_after":{"anchor":"last_active_at","days":1}}')

printf '%s\n' "$STORE_RESPONSE" | jq '{id, name, status}'
VECTOR_STORE_ID=$(printf '%s' "$STORE_RESPONSE" | jq -er '.id')

Python (OpenAI SDK)

store = client.vector_stores.create(
    name="document-search-demo",
    expires_after={"anchor": "last_active_at", "days": 1},
)
print("Created store:", store.id, store.status)

Speichern Sie die zurückgegebene Filial-ID. Die Erstellung kann asynchron sein. Prüfen Sie den Status in der nächsten Aufgabe.

2. Filiale abrufen und Status prüfen

Rufen Sie die Metadaten des Speichers ab, und warten Sie auf completed, bevor Sie ein Dokument aufnehmen.

Führen Sie das Beispiel für den ausgewählten Pfad aus.

curl

curl --fail-with-body --silent --show-error \
  "$VECTOR_STORES_URL/$VECTOR_STORE_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  | jq '{id, name, status}'

Wenn der Status in_progress lautet, warten Sie zwei Sekunden, und führen Sie den Befehl zum Abrufen erneut aus. Fahren Sie nur fort, wenn der Status completed lautet. Stoppen Sie den Vorgang, und prüfen Sie, ob der Speicher abläuft oder länger als zwei Minuten in Bearbeitung ist.

Python (OpenAI SDK)

store = client.vector_stores.retrieve(store.id)
deadline = time.monotonic() + 120
while store.status == "in_progress":
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Store creation is still in progress: {store.id}")
    time.sleep(2)
    store = client.vector_stores.retrieve(store.id)

if store.status != "completed":
    raise RuntimeError(f"Store is not ready: {store.id}, {store.status}")
print("Store is ready:", store.id)

Das zweiminütige Polling-Timeout ist ein Limit für dieses Beispiel und keine Service-Abschlussgarantie. Behalten Sie die Filial-ID bei, und prüfen Sie die Filiale, bevor Sie es erneut versuchen.

Der Laden ist bereit für die Aufnahme.

3. Vektorspeicher auflisten

Listet Filialen auf, um Ressourcen zu suchen, die Sie bereits erstellt haben. In diesem Beispiel wird die erste Seite mit bis zu zehn Einträgen angezeigt. Ein Shop befindet sich möglicherweise auf einer späteren Seite. Rufen Sie nach ID ab, um eine bestimmte Filiale zu prüfen.

Führen Sie das Beispiel für den ausgewählten Pfad aus.

curl

curl --fail-with-body --silent --show-error \
  "$VECTOR_STORES_URL?limit=10" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  | jq '.data[] | {id, name, status}'

Python (OpenAI SDK)

for item in client.vector_stores.list(limit=10).data:
    print(item.id, item.name, item.status)

In der Ausgabe werden die ID, der Name und der Status der zurückgegebenen Filiale angezeigt.

4. Dokument hochladen

Laden Sie das Beispieldokument hoch, um eine Dateiressource zu erstellen. Der OpenAI-Project-Header verknüpft den Upload mit Ihrem OCI Generative AI-Projekt. Die Datei kann nach der Aufnahme in der nächsten Aufgabe durchsucht werden.

Führen Sie das Beispiel für den ausgewählten Pfad aus.

curl

FILE_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "$FILES_URL" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header "OpenAI-Project: $GENAI_PROJECT_ID" \
  --form 'purpose=assistants' \
  --form 'file=@sample-document.txt')

printf '%s\n' "$FILE_RESPONSE" | jq '{id, filename}'
FILE_ID=$(printf '%s' "$FILE_RESPONSE" | jq -er '.id')

Python (OpenAI SDK)

with open("sample-document.txt", "rb") as document:
    uploaded_file = client.files.create(
        file=document,
        purpose="assistants",
        extra_headers={"OpenAI-Project": PROJECT_ID},
    )
print("Uploaded file:", uploaded_file.id, uploaded_file.filename)

Lassen Sie den Befehl für curl den mehrteiligen Inhaltstyp und die Begrenzung automatisch festlegen.

Speichern Sie die zurückgegebene Datei-ID für Aufnahme und Bereinigung.

5. Dokument in den Speicher aufnehmen

Die Aufnahme ordnet die Datei dem Speicher zu, teilt das Dokument in Blöcke auf und erstellt Einbettungen für den Abruf. Ein Dateibatch kann mehrere Dateien enthalten. In diesem Beispiel werden eine Datei und die standardmäßigen Chunking-Einstellungen verwendet.

Führen Sie das Beispiel für den ausgewählten Pfad aus.

curl

BATCH_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "$VECTOR_STORES_URL/$VECTOR_STORE_ID/file_batches" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header 'Content-Type: application/json' \
  --data "$(jq -n --arg file_id "$FILE_ID" '{file_ids:[$file_id]}')")

printf '%s\n' "$BATCH_RESPONSE" | jq '{id, status, file_counts}'
BATCH_ID=$(printf '%s' "$BATCH_RESPONSE" | jq -er '.id')

Prüfen Sie den Batch-Status:

curl --fail-with-body --silent --show-error \
  "$VECTOR_STORES_URL/$VECTOR_STORE_ID/file_batches/$BATCH_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  | jq '{id, status, file_counts}'

Wenn der Status in_progress lautet, warten Sie zwei Sekunden, und rufen Sie den Batch erneut ab. Fahren Sie fort, wenn der Status completed lautet, die Anzahl der abgeschlossenen Dateien eins ist und die Anzahl der nicht erfolgreichen und abgebrochenen Dateien null ist. Stoppen und untersuchen, ob die Aufnahme fehlschlägt, abgebrochen wird oder länger als zwei Minuten in Bearbeitung bleibt.

Python (OpenAI SDK)

batch = client.vector_stores.file_batches.create(
    vector_store_id=store.id,
    file_ids=[uploaded_file.id],
)
print("Ingestion batch:", batch.id)

deadline = time.monotonic() + 120
while batch.status == "in_progress":
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Document ingestion is still in progress: {batch.id}")
    time.sleep(2)
    batch = client.vector_stores.file_batches.retrieve(
        batch.id, vector_store_id=store.id,
    )

counts = batch.file_counts
if (
    batch.status != "completed"
    or counts.completed != 1
    or counts.failed
    or counts.cancelled
):
    raise RuntimeError(
        f"Ingestion did not succeed: {batch.id}, {batch.status}, {counts}"
    )
print("Document is ready to search.")

Das Dokument kann nach erfolgreicher Aufnahme gesucht werden. Weitere Informationen finden Sie unter Vector Store File Batches API.

6. Dokument durchsuchen

Stellen Sie eine Frage in natürlicher Sprache, um relevante Passagen abzurufen. Der Suchaufruf gibt Dokumentinhalt zurück. Es wird keine Antwort auf das Sprachmodell generiert.

Führen Sie das Beispiel für den ausgewählten Pfad aus.

curl

Python (OpenAI SDK)

Suchen Sie nach einer Passage mit der 30-tägigen Rückgabefrist der Beispielrichtlinie. Grenzen, Reihenfolge und Scores für Übergänge können variieren. max_num_results begrenzt übereinstimmende Blöcke, nicht Dokumente.

Versuchen Sie es mit einer anderen Frage, z.B. Wie schnell ist die Expresszustellung? oder Was sollte ich bei einer Rücksendung berücksichtigen? Wiederholen Sie nur den Suchaufruf, während der Speicher und die Datei noch vorhanden sind.

7. Filiale umbenennen

Aktualisieren Sie den Filialnamen. Die Umbenennung ändert die Metadaten des Speichers und lässt den hochgeladenen Policy-Text unverändert.

Führen Sie das Beispiel für den ausgewählten Pfad aus.

curl

curl --fail-with-body --silent --show-error \
  --request POST "$VECTOR_STORES_URL/$VECTOR_STORE_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header 'Content-Type: application/json' \
  --data '{"name":"document-search-demo-updated"}' \
  | jq '{id, name, status}'

Wenn der Status in_progress lautet, verwenden Sie den Befehl zum Abrufen aus Aufgabe 2, bis der Status completed lautet. Stoppen und untersuchen Sie, ob das Update innerhalb des zweiminütigen Polling-Zeitraums des Beispiels nicht abgeschlossen wird.

Python (OpenAI SDK)

store = client.vector_stores.update(
    store.id, name="document-search-demo-updated",
)
deadline = time.monotonic() + 120
while store.status == "in_progress":
    if time.monotonic() >= deadline:
        raise TimeoutError(f"Store update is still in progress: {store.id}")
    time.sleep(2)
    store = client.vector_stores.retrieve(store.id)

if store.status != "completed":
    raise RuntimeError(f"Store update did not complete: {store.id}, {store.status}")
print("Updated store:", store.id, store.name)

Der Filialname wurde aktualisiert. Warten Sie, bis die Aktualisierung abgeschlossen ist, bevor Sie sie löschen.

8. Testressourcen löschen

Löschen Sie den Speicher und die hochgeladene Datei, die in diesem Tutorial erstellt wurden. Es handelt sich um separate Ressourcen. Durch das Löschen des Speichers wird das Löschen der Datei nicht ersetzt. Verwenden Sie nur die IDs der von Ihnen erstellten Testressourcen.

Wenn eine frühere Aufgabe nicht erfolgreich war, verwenden Sie die Kennungen, die von den erfolgreichen Aufgaben gedruckt wurden, um nur vorhandene Ressourcen zu bereinigen. Behalten Sie dieselben Einstellungen für Endpunkt-, Compartment-, Projekt- und API-Schlüssel bei. Führen Sie für Python den Setupblock mit dem Löschblock aus, und ersetzen Sie store.id und uploaded_file.id durch die gespeicherten IDs als Zeichenfolgen in Anführungszeichen. Lassen Sie den Löschvorgang für eine Ressource aus, die nicht erstellt wurde.

Führen Sie das Beispiel für den ausgewählten Pfad aus.

curl

curl --fail-with-body --silent --show-error \
  --request DELETE "$VECTOR_STORES_URL/$VECTOR_STORE_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  | jq '{id, deleted}'

curl --fail-with-body --silent --show-error \
  --request DELETE "$FILES_URL/$FILE_ID" \
  --header "Authorization: Bearer $GENAI_API_KEY" \
  --header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
  --header "OpenAI-Project: $GENAI_PROJECT_ID" \
  | jq '{id, deleted}'

Python (OpenAI SDK)

deleted_store = client.vector_stores.delete(store.id)
print("Store deleted:", deleted_store.id, deleted_store.deleted)

deleted_file = client.files.delete(
    uploaded_file.id,
    extra_headers={"OpenAI-Project": PROJECT_ID},
)
print("File deleted:", deleted_file.id, deleted_file.deleted)
client.close()

Eine Bestätigung zum erfolgreichen Löschen enthält deleted: true. Bestätigen Sie diesen Wert für beide Ressourcen.

Fehlerbehebung

SymptomWas zu überprüfen ist
Authentifizierungsfehler oder HTTP 401Bestätigen Sie, dass das OCI Generative AI-API-Schlüssel-Secret für die ausgewählte Region gültig ist und als Bearer-Token gesendet wird.
Autorisierungsfehler oder HTTP 403Prüfen Sie die API-Schlüsselberechtigungen sowie die Datei- und Vektorspeicherberechtigungen für das Compartment und das Projekt.
Ressource nicht GefundenPrüfen Sie Service-URL, Region, Compartment, Projektheader für Dateianforderungen und Ressourcen-ID.
Upload abgelehntPrüfen Sie den Dateityp und die Uploadlimits im Thema Dateien-API. Beginnen Sie mit dem kleinen Musterdokument.
Aufnahme nicht erfolgreichRufen Sie den Batch ab, und prüfen Sie dessen Status und Dateianzahl. Rufen Sie einzelne Vektorspeicherdateidatensätze für Fehlerdetails ab.
Keine SuchergebnisseBestätigen Sie, dass die Aufnahme erfolgreich abgeschlossen wurde und dass Sie den Speicher durchsuchen, der das Dokument enthält.
Polling-TimeoutRufen Sie die Ressource erneut ab, um ihren aktuellen Status zu prüfen. Behalten Sie die ID für die Fehlerbehebung und Bereinigung bei.
Das SDK enthält keine vector_stores- oder search-MethodeAktivieren Sie die vom Skript verwendete Python-Umgebung, und führen Sie ein Upgrade des Packages openai durch.