Buscar documentos con almacenes vectoriales y claves de API de OCI Generative AI

Cree un almacén de vectores, cargue e ingiera un documento y busque su contenido con curl o el SDK de Python OpenAI mediante una clave de API de OCI Generative AI.

Descripción general

Una tienda de vectores hace que sus documentos sean buscables por significado. Puede cargar un archivo, ingerirlo en la tienda y buscar con una pregunta en lenguaje natural. El servicio devuelve pasajes, nombres de archivo y puntuaciones de relevancia relevantes. Los pasajes recuperados también pueden proporcionar contexto para una aplicación de modelo de lenguaje.

Utilice almacenes de vectores para buscar políticas, guías de productos y artículos de soporte sin crear su propio pipeline de análisis e incrustación de documentos. Para obtener una introducción, consulte Tiendas vectoriales y tiendas semánticas.

En este tutorial:

  • Crear, recuperar y mostrar almacenes de vectores.
  • Cargar un documento de ejemplo e introducirlo en fragmentos que permiten la búsqueda.
  • Busque el documento e inspeccione las pasajes coincidentes.
  • Cambie el nombre del almacén y suprima los recursos de prueba.

Cada tarea numerada proporciona un ejemplo de curl y un ejemplo de Python (SDK OpenAI). Elija un camino y sígalo de principio a fin. Los ejemplos curl realizan solicitudes HTTP desde Bash. Los ejemplos de Python utilizan el SDK OpenAI configurado para llamar a OCI. Ambas rutas se autentican con una clave de API de OCI Generative AI y no requieren una sesión de CLI de OCI.

Antes de empezar

Para completar este tutorial, necesita:

En los ejemplos se utiliza esta URL base de OCI:

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

Utilice el punto final de servicio para la región seleccionada. Mantenga el mismo punto final, compartimento y proyecto durante todo el tutorial.

El documento de ejemplo contiene una política de tienda ficticia. Sustituya solo los marcadores de posición de conexión por sus propios valores. Los ejemplos solicitan la clave de API sin mostrarla ni incluirla en el código fuente.

Configurar la ruta de curl

En un terminal de Bash, sustituya los marcadores de posición del compartimento y del proyecto y, a continuación, ejecute:

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"

Ejecute cada ejemplo de curl en este terminal para que la configuración y los ID de recursos devueltos permanezcan disponibles. Las solicitudes envían la clave de API de portador y opc-compartment-id. Las cargas de archivos y la supresión de archivos también envían OpenAI-Project para identificar su proyecto de OCI. Defina la URL base sin una barra final.

Si un comando falla, resuelva el error antes de continuar. Mantenga los ID devueltos por las solicitudes de limpieza correctas. No vuelva a ejecutar un comando de creación o carga correcto solo para recuperar el estado de un recurso.

Configuración de la ruta de Python

Cree y active un entorno virtual y, a continuación, instale el SDK de Python OpenAI:

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

Cree vector_store_tutorial.py con la siguiente configuración. Sustituya los marcadores de posición del compartimento y del proyecto. A continuación, agregue el bloque Python de cada una de las ocho tareas numeradas en orden. Todos los bloques comparten las mismas variables de cliente y recurso.

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,
)

Después de guardar el documento de ejemplo y de ensamblar todos los bloques de Python, ejecute el script terminado desde el mismo directorio:

python vector_store_tutorial.py

El script completado crea recursos, busca el documento y suprime su archivo de almacenamiento y cargado. Para probar más preguntas antes de la limpieza, agregue llamadas de búsqueda después de la tarea 6 y antes del bloque de supresión. Si la secuencia de comandos se detiene en un error, use los ID de recursos impresos antes del error para inspeccionar y limpiar los recursos ya creados.

Preparación de un documento de muestra

Guarde esta política ficticia como sample-document.txt en el directorio en el que ejecuta los comandos curl o el script de Python:

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. Crear una tienda de vectores

Cree una tienda vacía con un nombre reconocible. En el ejemplo se define una política de caducidad de un día basada en last_active_at. La creación de la tienda no carga ni ingiere un documento.

Ejecute el ejemplo de la ruta elegida.

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 (SDK OpenAI)

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

Guarde el ID de tienda devuelto. La creación puede ser asíncrona. Compruebe su estado en la siguiente tarea.

2. Recuperar la tienda y comprobar su estado

Recupere los metadatos del almacén y espere a completed antes de ingerir un documento.

Ejecute el ejemplo de la ruta elegida.

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

Si el estado es in_progress, espere dos segundos y vuelva a ejecutar el comando de recuperación. Continúe solo cuando el estado sea completed. Detenga e investigue si la tienda caduca o si permanece en curso durante más de dos minutos.

Python (SDK OpenAI)

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)

El timeout de sondeo de dos minutos es un límite para este ejemplo, no una garantía de finalización del servicio. Si se alcanza, conserve el ID de tienda e inspeccione la tienda antes de volver a intentarlo.

La tienda está lista para la ingestión.

3. Lista de almacenes de vectores

Muestre las tiendas para buscar los recursos que ya ha creado. Este ejemplo muestra la primera página con hasta diez entradas. Una tienda puede estar en una página posterior. Recuperar por ID para comprobar una tienda específica.

Ejecute el ejemplo de la ruta elegida.

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 (SDK OpenAI)

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

La salida muestra el ID, el nombre y el estado de cada tienda devuelta.

4. Cargar un documento

Cargue el documento de ejemplo para crear un recurso de archivo. La cabecera OpenAI-Project asocia la carga con el proyecto de OCI Generative AI. El archivo se puede buscar después de la ingestión en la siguiente tarea.

Ejecute el ejemplo de la ruta elegida.

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 (SDK OpenAI)

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)

Para curl, deje que el comando defina el tipo de contenido de varias partes y el límite automáticamente.

Guarde el ID de archivo devuelto para la ingesta y la limpieza.

5. Ingestión del documento en la tienda

La ingestión asocia el archivo con la tienda, divide el documento en fragmentos y crea incrustaciones para su recuperación. Un lote de archivos puede contener varios archivos. En este ejemplo se utiliza un archivo y la configuración de fragmentación por defecto.

Ejecute el ejemplo de la ruta elegida.

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')

Compruebe el estado del lote:

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

Si el estado es in_progress, espere dos segundos y vuelva a recuperar el lote. Continúe cuando el estado sea completed, el recuento de archivos completado sea uno y los recuentos fallidos y cancelados sean cero. Detenga e investigue si la ingestión falla, se cancela o permanece en curso durante más de dos minutos.

Python (SDK OpenAI)

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.")

El documento está listo para buscar después de una ingestión correcta. Consulte API de lotes de archivos de almacén de vector para obtener más información.

6. Buscar el documento

Haga una pregunta en lenguaje natural para recuperar pasajes relevantes. La llamada de búsqueda devuelve el contenido del documento. No genera una respuesta de modelo de idioma.

Ejecute el ejemplo de la ruta elegida.

curl

Python (SDK OpenAI)

Busque un pasaje que contenga el período de devolución de 30 días de la política de muestra. Los límites de paso, el orden y las puntuaciones pueden variar. max_num_results limita los fragmentos coincidentes, no los documentos.

Pruebe con otra pregunta, como ¿Qué tan rápido es la entrega rápida? o ¿Qué debo incluir con una devolución? Repita solo la llamada de búsqueda mientras el almacén y el archivo siguen existiendo.

7. Cambiar nombre de la tienda

Actualice el nombre de la tienda. El cambio de nombre cambia los metadatos del almacén y deja el texto de política cargado sin cambios.

Ejecute el ejemplo de la ruta elegida.

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

Si el estado es in_progress, utilice el comando de recuperación de la tarea 2 hasta que el estado sea completed. Detenga e investigue si la actualización no se completa dentro del período de sondeo de dos minutos del ejemplo.

Python (SDK OpenAI)

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)

La tienda tiene el nombre actualizado. Espere a que finalice la actualización antes de eliminarla.

8. Supresión de los Recursos de Prueba

Suprima el almacén y el archivo cargado creado en este tutorial. Son recursos separados. La supresión del almacén no sustituye la supresión del archivo. Utilice sólo los ID de los recursos de prueba que ha creado.

Si una tarea anterior falló, use los ID impresos por las tareas correctas para limpiar solo los recursos que existen. Mantenga la misma configuración de punto final, compartimento, proyecto y clave de API. Para Python, ejecute el bloque de configuración con el bloque de supresión y sustituya store.id y uploaded_file.id por los ID guardados como cadenas entre comillas. Omita la supresión de cualquier recurso que no se haya creado.

Ejecute el ejemplo de la ruta elegida.

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 (SDK OpenAI)

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()

Una confirmación de supresión correcta contiene deleted: true. Confirme este valor para ambos recursos.

Solución de problemas

SíntomaQué comprobar
Error de autenticación o HTTP 401Confirme que el secreto de clave de API de OCI Generative AI es válido para la región seleccionada y se envía como token de portador.
Error de autorización o HTTP 403Compruebe los permisos de clave de API y los permisos de almacén de archivos y vectores para el compartimento y el proyecto.
No se ha encontrado el recursoVerifique la URL de servicio, la región, el compartimento, la cabecera del proyecto para las solicitudes de archivo y el ID de recurso.
Carga rechazadaCompruebe el tipo de archivo y los límites de carga en el tema API de archivos. Comience con el documento de ejemplo pequeño.
Error de ingestiónRecupere el lote e inspeccione su estado y los recuentos de archivos. Recupere registros de archivo de almacén de vectores individuales para obtener detalles del error.
No hay resultados de búsquedaConfirme que la ingestión se ha realizado correctamente y que está buscando en la tienda que contiene el documento.
Timeout del sondeoVuelva a recuperar el recurso para inspeccionar su estado actual. Mantenga su ID para la resolución de problemas y la limpieza.
El SDK no tiene ningún método vector_stores ni searchActive el entorno de Python que utiliza el script y actualice el paquete openai.