Rechercher des documents avec des magasins de vecteurs et des clés d'API du service d'intelligence artificielle générative pour OCI
Créez un magasin de vecteurs, chargez et ingérez un document, et recherchez son contenu à l'aide de curl ou de la trousse SDK Python OpenAI à l'aide d'une clé d'API du service d'intelligence artificielle générative pour OCI.
Aperçu
Un magasin de vecteurs rend vos documents consultables par signification. Vous chargez un fichier, l'ingérez dans le magasin et effectuez une recherche à l'aide d'une question en langage naturel. Le service retourne les passages pertinents, les noms de fichier et les notes de pertinence. Les passages extraits peuvent également fournir un contexte pour une application de modèle de langage.
Utilisez des magasins de vecteurs pour rechercher des politiques, des guides de produit et des articles de soutien sans créer votre propre pipeline d'analyse et d'intégration de documents. Pour une présentation, voir Magasins vectoriels et magasins sémantiques.
Dans ce tutoriel, vous allez :
- Créer, extraire et répertorier les magasins de vecteurs.
- Chargez un exemple de document et ingérez-le dans des fragments interrogeables.
- Recherchez le document et inspectez les passages correspondants.
- Renommez le magasin et supprimez les ressources de test.
Chaque tâche numérotée fournit un exemple de courbe et un exemple de trousse SDK PythonOpenAI. Choisissez un chemin et suivez-le du début à la fin. Les exemples curl effectuent des requêtes HTTP à partir de Bash. Les exemples Python utilisent la trousse SDK OpenAI configurée pour appeler OCI. Les deux chemins s'authentifient avec une clé d'API du service d'intelligence artificielle générative pour OCI et ne nécessitent pas de session d'interface de ligne de commande OCI.
Avant de commencer
Pour terminer ce tutoriel, vous devez :
- Une clé d'API du service d'intelligence artificielle générative pour OCI autorisée pour la région et le compartiment sélectionnés. Utilisez l'une des valeurs secrètes de la clé à l'invite.
- Autorisation de gérer les fichiers et les magasins de vecteurs dans ce compartiment. Voir Autorisations de fichier, Autorisations de magasin de vecteurs et Ajout d'autorisations de clé d'API.
- Projet d'intelligence artificielle générative OCI existant pour les chargements de fichier. Copiez son OCID et l'OCID de son compartiment. Si nécessaire, créez un projet avant de commencer.
- Accès à une région où les API de stockage de fichiers et de vecteurs sont disponibles. Les exemples utilisent US Midwest (Chicago),
us-chicago-1. Voir Régions des agents d'IA d'entreprise et les rubriques API de gestion de fichiers et API de gestion des lots de fichiers du magasin de vecteurs. - Pour curl, Bash, curl avec prise en charge de
--fail-with-bodyetjq. Pour Python, Python 3.11 ou version ultérieure et l'ensembleopenai.
Les exemples utilisent cette URL de base OCI :
https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/openai/v1Utilisez le point d'extrémité du service pour la région sélectionnée. Conservez le même point d'extrémité, compartiment et projet tout au long du tutoriel.
L'exemple de document contient une politique de magasin fictif. Remplacez uniquement les paramètres fictifs de connexion par vos propres valeurs. Les exemples demandent la clé d'API sans l'afficher ni l'inclure dans le code source.
Configurer le chemin de boucle
Dans un terminal Bash, remplacez les paramètres fictifs de compartiment et de projet, puis exécutez :
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"Exécutez chaque exemple de courbe dans ce terminal afin que les paramètres et les ID ressource retournés restent disponibles. Les demandes envoient la clé d'API du porteur et opc-compartment-id. Les chargements de fichier et la suppression de fichier envoient également OpenAI-Project pour identifier votre projet OCI. Définissez l'URL de base sans barre oblique de fin.
Si une commande échoue, résolvez l'erreur avant de continuer. Conservez les ID retournés par les demandes de nettoyage réussies. Ne réexécutez pas une commande de création ou de chargement réussie uniquement pour extraire le statut d'une ressource.
Configurer le chemin Python
Créez et activez un environnement virtuel, puis installez la trousse SDK Python OpenAI :
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openaiCréez vector_store_tutorial.py avec la configuration suivante. Remplacez le compartiment et les paramètres fictifs de projet. Ajoutez ensuite le bloc Python à partir de chacune des huit tâches numérotées dans l'ordre. Tous les blocs partagent les mêmes variables de client et de ressource.
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,
)Après avoir enregistré l'exemple de document et assemblé tous les blocs Python, exécutez le script terminé à partir du même répertoire :
python vector_store_tutorial.pyLe script terminé crée des ressources, effectue une recherche dans le document et supprime son magasin et son fichier chargé. Pour essayer d'autres questions avant le nettoyage, ajoutez des appels de recherche après la tâche 6 et avant le bloc de suppression. Si le script s'arrête en cas d'erreur, utilisez les ID ressource imprimés avant l'erreur pour inspecter et nettoyer les ressources déjà créées.
Préparer un exemple de document
Enregistrez cette politique fictive sous le nom sample-document.txt dans le répertoire où vous exécutez les commandes curl ou le script 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. Créer un magasin de vecteurs
Créez un magasin vide avec un nom reconnaissable. L'exemple définit une politique d'expiration d'un jour en fonction de last_active_at. La création du magasin ne charge ni n'ingère de document.
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 TROUSSE 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)Enregistrez l'ID magasin retourné. La création peut être asynchrone. Vérifiez son statut dans la tâche suivante.
2. Extraire le magasin et vérifier son statut
Extrayez les métadonnées du magasin et attendez completed avant d'ingérer un document.
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 le statut est in_progress, attendez deux secondes et exécutez de nouveau la commande d'extraction. Continuez uniquement lorsque le statut est completed. Arrêtez et vérifiez si le magasin expire ou reste en cours pendant plus de deux minutes.
Python (OpenAI TROUSSE 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)La temporisation de scrutation de deux minutes est une limite pour cet exemple, et non une garantie d'achèvement de service. S'il est atteint, conservez l'ID magasin et inspectez-le avant de réessayer.
Le magasin est prêt pour l'ingestion.
3. Lister les magasins de vecteurs
Lister les magasins pour rechercher les ressources que vous avez déjà créées. Cet exemple montre comment afficher la première page contenant jusqu'à dix entrées. Un magasin peut être sur une page ultérieure. Extraire par ID pour vérifier un magasin spécifique.
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 TROUSSE SDK)
for item in client.vector_stores.list(limit=10).data:
print(item.id, item.name, item.status)La sortie affiche l'ID, le nom et le statut de chaque magasin retourné.
4. Charger un document
Chargez l'exemple de document pour créer une ressource de fichier. L'en-tête OpenAI-Project associe le chargement à votre projet d'intelligence artificielle générative pour OCI. Le fichier devient interrogeable après l'ingestion dans la tâche suivante.
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 TROUSSE 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)Pour curl, laissez la commande définir automatiquement le type de contenu en plusieurs parties et la limite.
Enregistrez l'ID fichier retourné pour l'ingestion et le nettoyage.
5. Ingérer le document dans le magasin
Ingestion associe le fichier au magasin, fractionne le document en fragments et crée des plongements pour extraction. Un lot de fichiers peut contenir plusieurs fichiers. Cet exemple utilise un fichier et les paramètres de fragmentation par défaut.
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')Vérifiez le statut du lot :
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 le statut est in_progress, attendez deux secondes et extrayez de nouveau le lot. Continuez lorsque le statut est completed, que le nombre de fichiers terminés est égal à un et que le nombre d'échecs et d'annulations est égal à zéro. Arrêter et vérifier si l'ingestion échoue, est annulée ou reste en cours pendant plus de deux minutes.
Python (OpenAI TROUSSE 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.")Le document est prêt pour la recherche après une ingestion réussie. Pour plus d'informations, voir API de lots de fichiers de magasin de vecteurs.
6. Rechercher le document
Posez une question en langage naturel pour récupérer les passages pertinents. L'appel de recherche retourne le contenu du document. Il ne génère pas de réponse de modèle de langage.
curl
curl --fail-with-body --silent --show-error \
--request POST "$VECTOR_STORES_URL/$VECTOR_STORE_ID/search" \
--header "Authorization: Bearer $GENAI_API_KEY" \
--header "opc-compartment-id: $GENAI_COMPARTMENT_ID" \
--header 'Content-Type: application/json' \
--data '{"query":"How long do I have to return a purchase?","max_num_results":3}' \
| jq '.data[] | {filename, score, text:[.content[] | select(.type == "text") | .text]}'Python (OpenAI TROUSSE SDK)
query = "How long do I have to return a purchase?"
results = client.vector_stores.search(
vector_store_id=store.id,
query=query,
max_num_results=3,
)
print("Question:", query)
if not results.data:
print("No matching passages found.")
for result in results.data:
print(f"\n{result.filename} (score: {result.score:.3f})")
for content in result.content:
if content.type == "text":
print(content.text)Recherchez un passage contenant la période de retour de 30 jours de l'exemple de politique. Les limites de passage, l'ordre et les notes peuvent varier. max_num_results limite les fragments correspondants, et non les documents.
Essayez une autre question, par exemple À quelle vitesse la livraison express est-elle rapide?
ou Que dois-je inclure dans un retour?
Répétez uniquement l'appel de recherche tant que le magasin et le fichier existent toujours.
7. Renommer le magasin
Mettez à jour le nom du magasin. Le changement de nom modifie les métadonnées du magasin et laisse le texte de politique chargé inchangé.
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 le statut est in_progress, utilisez la commande d'extraction de la tâche 2 jusqu'à ce que le statut soit completed. Arrêtez et vérifiez si la mise à jour ne se termine pas dans la période de scrutation de deux minutes de l'exemple.
Python (OpenAI TROUSSE 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)Le magasin a le nom mis à jour. Attendez la fin de la mise à jour avant de la supprimer.
8. Supprimer les ressources de test
Supprimez le magasin et le fichier chargé créés dans ce tutoriel. Ce sont des ressources distinctes. La suppression du magasin ne remplace pas la suppression du fichier. Utilisez uniquement les ID des ressources de test que vous avez créées.
En cas d'échec d'une tâche antérieure, utilisez les ID imprimés par les tâches réussies pour nettoyer uniquement les ressources existantes. Conservez les mêmes paramètres de point d'extrémité, de compartiment, de projet et de clé d'API. Pour Python, exécutez le bloc de configuration avec le bloc de suppression et remplacez store.id et uploaded_file.id par les ID enregistrés en tant que chaînes entre guillemets. Omettre la suppression pour toute ressource qui n'a pas été créée.
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 TROUSSE 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()Un accusé de réception de suppression a réussi contient deleted: true. Confirmez cette valeur pour les deux ressources.
Dépannage
| Symptôme | Que vérifier |
|---|---|
| Erreur d'authentification ou HTTP 401 | Confirmez que la clé secrète de la clé d'API du service d'intelligence artificielle générative pour OCI est valide pour la région sélectionnée et envoyée en tant que jeton porteur. |
| Erreur d'autorisation ou HTTP 403 | Vérifiez les autorisations de clé d'API et les autorisations de fichier et de magasin de vecteurs pour le compartiment et le projet. |
| Ressource introuvable | Vérifiez l'URL du service, la région, le compartiment, l'en-tête du projet pour les demandes de fichier et l'ID ressource. |
| Chargement rejeté | Vérifiez le type de fichier et chargez les limites dans la rubrique API de gestion de fichiers. Commencez par le petit exemple de document. |
| Échec de l'ingestion | Extrayez le lot et inspectez son statut et le nombre de fichiers. Extraire des enregistrements de fichier de magasin de vecteurs individuels pour obtenir les détails des erreurs. |
| Aucun résultat de la recherche | Vérifiez que l'ingestion a réussi et que vous recherchez le magasin contenant le document. |
| Temporisation de scrutation | Extrayez à nouveau la ressource pour inspecter son statut courant. Conservez son ID pour le dépannage et le nettoyage. |
La trousse SDK n'a pas de méthode vector_stores ou search | Activez l'environnement Python utilisé par le script et mettez à niveau l'ensemble openai. |