Cette page a été traduite par l'API Cloud Translation.

Utiliser une base de données Weaviate avec le moteur de RAG Vertex AI

Cette page explique comment connecter votre corpus du moteur RAG à votre base de données Weaviate.

Vous pouvez également suivre avec le notebook Moteur RAG avec Weaviate.

Vous pouvez utiliser votre instance de base de données Weaviate, qui est une base de données Open Source, avec le moteur RAG afin d'indexer et d'effectuer une recherche de similarités basée sur les vecteurs. Une recherche de similarité permet de trouver des éléments de texte semblables au texte recherché et nécessite l'utilisation d'un modèle d'embedding. Le modèle d'embedding produit des données vectorielles pour chaque élément de texte comparé. La recherche de similarités permet de récupérer les contextes sémantiques pour l'ancrage afin de renvoyer les contenus les plus pertinents de votre LLM.

Avec le moteur RAG, vous pouvez continuer à utiliser votre instance de base de données vectorielle entièrement gérée dont vous êtes chargé du provisionnement. Le moteur RAG utilise la base de données vectorielle pour le stockage, la gestion des index et la recherche.

Remarques

Suivez les étapes ci-dessous avant d'utiliser la base de données Weaviate :

Vous devez créer, configurer et déployer votre instance et votre collection de base de données Weaviate. Suivez les instructions de la section Créer votre collection Weaviate pour configurer une collection basée sur votre schéma.
Vous devez fournir une clé API Weaviate, qui permet au moteur RAG d'interagir avec la base de données Weaviate. Le moteur RAG est compatible avec les processus d'authentification et d'autorisation AuthN et AuthZ basés sur les clés API, qui se connectent à votre base de données Weaviate et permettent une connexion HTTPS.
Le moteur RAG ne stocke pas ni ne gère votre clé API Weaviate. À la place, vous devez effectuer les actions suivantes :
1. Stockez votre clé dans Google Cloud Secret Manager.
2. Accordez au compte de service de votre projet les autorisations nécessaires pour accéder à votre secret.
3. Fournissez au moteur RAG un accès au nom de ressource de votre secret.
4. Lorsque vous interagissez avec votre base de données Weaviate, le moteur RAG accède à votre ressource de secret à l'aide de votre compte de service.
Le corpus du moteur RAG et la collection Weaviate présentent un mappage de type "un à un". Les fichiers RAG sont stockés dans une collection de base de données Weaviate. Lorsqu'un appel est effectué vers l'API CreateRagCorpus ou l'API UpdateRagCorpus, le corpus RAG est associé à la collection de base de données.
En plus des recherches sémantiques denses basées sur des embeddings, la recherche hybride est également compatible avec le moteur RAG par le biais d'une base de données Weaviate. Vous pouvez également ajuster la pondération entre les similarités de vecteurs denses et creux dans une recherche hybride.

Provisionner la base de données Weaviate

Avant d'utiliser la base de données Weaviate avec le moteur RAG, vous devez effectuer les opérations suivantes :

Configurez et déployez votre instance de base de données Weaviate.
Préparez le point de terminaison HTTPS.
Créez votre collection Weaviate.
Utilisez votre clé API pour provisionner Weaviate à l'aide de AuthN et AuthZ.
Provisionnez votre compte de service de moteur RAG.

Configurer et déployer votre instance de base de données Weaviate

Vous devez suivre le guide de démarrage rapide du guide officiel de Weaviate. Toutefois, vous pouvez utiliser le guide deGoogle Cloud Marketplace, qui est facultatif.

Vous pouvez configurer votre instance Weaviate n'importe où, à condition que le point de terminaison Weaviate soit accessible pour configurer votre projet et y effectuer des déploiements. Vous pouvez ensuite gérer entièrement votre instance de base de données Weaviate.

Étant donné que le moteur RAG n'est impliqué à aucun stade du cycle de vie de votre instance de base de données Weaviate, il vous incombe d'accorder des autorisations au moteur RAG afin qu'il puisse stocker et rechercher des données dans votre base de données Weaviate. Il est également de votre responsabilité de vous assurer que les données de votre base de données peuvent être utilisées par le moteur RAG. Par exemple, si vous modifiez vos données, le moteur RAG n'est pas responsable des comportements inattendus en raison de ces modifications.

Préparer le point de terminaison HTTPS

Lors du provisionnement de Weaviate, veillez à créer un point de terminaison HTTPS. Bien que les connexions HTTP soient compatibles, il est préférable que le trafic du moteur RAG et de la base de données Weaviate utilise une connexion HTTPS.

Créer votre collection Weaviate

Étant donné que le corpus du moteur RAG et la collection Weaviate présentent un mappage de type "un à un", vous devez créer une collection dans votre base de données Weaviate avant de l'associer au corpus du moteur RAG. Cette association unique est effectuée lorsque vous appelez l'API CreateRagCorpus ou l'API UpdateRagCorpus.

Lorsque vous créez une collection dans Weaviate, vous devez utiliser le schéma suivant :

Nom de propriété	Type de données
`fileId`	`text`
`corpusId`	`text`
`chunkId`	`text`
`chunkDataType`	`text`
`chunkData`	`text`
`fileOriginalUri`	`text`

Utiliser votre clé API pour provisionner Weaviate à l'aide de `AuthN` et `AuthZ`.

Le provisionnement de la clé API Weaviate implique les étapes suivantes :

Créer la clé API Weaviate.
Configurer Weaviate à l'aide de votre clé API Weaviate.
Stocker votre clé API Weaviate dans Secret Manager.

Créer la clé API

Le moteur RAG ne peut se connecter à vos instances de base de données Weaviate qu'à l'aide de votre clé API pour l'authentification et l'autorisation. Vous devez suivre le guide officiel de l'authentification de Weaviate pour configurer l'authentification basée sur une clé API dans votre instance de base de données Weaviate.

Si la création de la clé API Weaviate nécessite d'associer des informations d'identité provenant du moteur RAG, vous devez créer votre premier corpus et utiliser votre compte de service de moteur RAG comme identité.

Stocker votre clé API dans Secret Manager

Une clé API contient des informations personnelles sensibles, qui sont soumises à des obligations légales. Si ces données sont compromises ou utilisées de manière abusive, une personne physique peut être exposée à des risques ou à des préjudices importants. Pour minimiser les risques encourus par une personne lors de l'utilisation du moteur RAG, ne stockez pas et ne gérez pas votre clé API, et évitez de partager la clé API non chiffrée.

Pour protéger les informations personnelles sensibles, procédez comme suit :

Stockez votre clé API dans Secret Manager.
Accordez à votre compte de service du moteur RAG les autorisations nécessaires pour vos secrets, et gérez le contrôle des accès au niveau de la ressource du secret.
1. Accédez aux autorisations de votre projet.
2. Activez l'option Inclure les attributions de rôles fournies par Google.
3. Recherchez le compte de service, qui est au format suivant :
  service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
4. Modifiez les comptes principaux du compte de service.
5. Ajoutez le rôle Accesseur de secrets Secret Manager au compte de service.
Lors de la création ou de la mise à jour du corpus RAG, transmettez le nom de la ressource de secret au moteur RAG, puis stockez le nom de la ressource de secret.

Lorsque vous envoyez des requêtes API à vos instances de base de données Weaviate, le moteur RAG utilise chaque compte de service pour lire la clé API correspondant à vos ressources de secret dans Secret Manager à partir de vos projets.

Provisionner votre compte de service de moteur RAG

Lorsque vous créez la première ressource dans votre projet, le moteur RAG crée un compte de service dédié. Vous pouvez trouver votre compte de service sur la page IAM de votre projet. Le compte de service respecte le format suivant :

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Par exemple : service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

Lors de l'intégration à la base de données Weaviate, votre compte de service est utilisé dans les scénarios suivants :

Vous pouvez utiliser votre compte de service pour générer votre clé API Weaviate à des fins d'authentification. Dans certains cas, la génération de la clé API ne nécessite aucune information utilisateur, ce qui signifie qu'un compte de service n'est pas nécessaire pour générer la clé API.
Vous pouvez lier votre compte de service à la clé API dans votre base de données Weaviate pour configurer l'authentification (AuthN) et l'autorisation (AuthZ). Toutefois, votre compte de service n'est pas nécessaire.
Vous pouvez stocker la clé API Secret Manager dans votre projet, et vous pouvez accorder à votre compte de service des autorisations pour accéder à ces ressources de secrets.
Le moteur RAG utilise des comptes de service pour accéder à la clé API à partir du Secret Manager dans vos projets.

Configurer l'environnement de votre console Google Cloud

Cliquez ici pour apprendre à configurer votre environnement

Découvrez comment configurer votre environnement en sélectionnant l'un des onglets suivants :

Python

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Installez ou mettez à jour le SDK Vertex AI pour Python en exécutant la commande suivante :
```
pip3 install --upgrade "google-cloud-aiplatform>=1.38"
    
```

Node.js

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Installez ou mettez à jour le SDK Vertex AI pour Node.js en exécutant la commande suivante :
```
npm install @google-cloud/vertexai
    
```

Java

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Pour ajouter google-cloud-vertexai en tant que dépendance, ajoutez le code approprié pour votre environnement :

Maven avec BOM

Ajoutez le code HTML suivant à votre pom.xml :

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.32.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-vertexai</artifactId>
  </dependency>
</dependencies>

Maven sans BOM

Ajoutez le code HTML suivant à votre pom.xml :

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-vertexai</artifactId>
  <version>0.4.0</version>
</dependency>

Gradle without BOM

Add the following to your build.gradle

implementation 'com.google.cloud:google-cloud-vertexai:0.4.0'

Go

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Examinez les packages Go de l'API Vertex AI disponibles pour déterminer le package qui répond le mieux aux besoins de votre projet :
- Package cloud.google.com/go/vertexai (recommandé)
  
  vertexai est un package créé manuellement qui permet d'accéder aux fonctionnalités et capacités courantes.
  
  Ce package est recommandé comme point de départ pour la plupart des développeurs utilisant l'API Vertex AI. Pour accéder à des fonctionnalités et capacités qui ne sont pas encore couvertes par ce package, utilisez plutôt le package aiplatform généré automatiquement.
- Package cloud.google.com/go/aiplatform
  
  aiplatform est un package généré automatiquement.
  
  Ce package est destiné aux projets nécessitant un accès aux fonctionnalités et capacités de l'API Vertex AI qui ne sont pas encore fournies par le package vertexai créé manuellement.

Installez le package Go souhaité en fonction des besoins de votre projet en exécutant l'une des commandes suivantes :

# Human authored package. Recommended for most developers.
go get cloud.google.com/go/vertexai
    

# Auto-generated package.
go get cloud.google.com/go/aiplatform

C#

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

REST

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Configurez les variables d'environnement en saisissant les informations suivantes. Remplacez PROJECT_ID par l'ID de votre projet Google Cloud .
```
MODEL_ID="gemini-2.0-flash-001"
PROJECT_ID="PROJECT_ID"
    
```

Provisionnez le point de terminaison :

gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_ID}

Facultatif : Si vous utilisez Cloud Shell et que vous êtes invité à l'autoriser, cliquez sur Autoriser.

Préparer votre corpus RAG

Pour accéder aux données de votre base de données Weaviate, le moteur RAG doit avoir accès à un corpus RAG. Cette section décrit la procédure à suivre pour créer un seul corpus RAG et des corpus RAG supplémentaires.

Utiliser les API `CreateRagCorpus` et `UpdateRagCorpus`

Vous devez spécifier les champs suivants lorsque vous appelez les API CreateRagCorpus et UpdateRagCorpus :

rag_vector_db_config.weaviate : après l'appel de l'API CreateRagCorpus, la configuration de la base de données vectorielle est choisie. La configuration de la base de données vectorielle contient tous les champs de configuration. Si le champ rag_vector_db_config.weaviate n'est pas défini, rag_vector_db_config.rag_managed_db est défini par défaut.
weaviate.http_endpoint : le point de terminaison Weaviate HTTPS ou HTTP est créé lors du provisionnement de l'instance de base de données Weaviate.
weaviate.collection_name : nom de la collection créée lors du provisionnement de l'instance Weaviate. Le nom doit commencer par une lettre majuscule.
api_auth.api_key_config : la configuration indique qu'une clé API doit être utilisée pour autoriser l'accès à la base de données vectorielle.
api_key_config.api_key_secret_version : nom de la ressource du secret stocké dans Secret Manager, qui contient votre clé API Weaviate.

Vous pouvez créer et associer votre corpus RAG à la collection Weaviate dans votre instance de base de données. Toutefois, vous aurez peut-être besoin du compte de service pour générer votre clé API et configurer votre instance de base de données Weaviate. Lorsque vous créez votre premier corpus RAG, le compte de service est généré. Une fois que vous avez créé votre premier corpus RAG, il se peut que l'association entre la base de données Weaviate et la clé API ne soit pas prête à être utilisée pour la création d'un autre corpus RAG.

Dans le cas où votre base de données et votre clé ne sont pas prêtes à être associées à votre corpus RAG, procédez comme suit sur votre corpus RAG :

Définissez le champ weaviate dans rag_vector_db_config.
- Vous ne pouvez pas modifier la base de données vectorielle associée.
- Laissez les champs http_endpoint et collection_name vides. Les deux champs peuvent être modifiés ultérieurement.
Si votre clé API n'est pas stockée dans Secret Manager, vous pouvez laisser le champ api_auth vide. Lorsque vous appelez l'API UpdateRagCorpus, vous pouvez modifier le champ api_auth. Weaviate nécessite de réaliser les opérations suivantes :
1. Définissez api_key_config dans le champ api_auth.
2. Définissez l'élément api_key_secret_version de votre clé API Weaviate dans Secret Manager. Le champ api_key_secret_version utilise le format suivant :
  
  projects/{project}/secrets/{secret}/versions/{version}
Si vous spécifiez des champs qui ne peuvent être définis qu'une seule fois, tels que http_endpoint ou collection_name, vous ne pouvez pas les modifier, sauf si vous supprimez votre corpus RAG et le recréez. D'autres champs, tels que le champ de clé API, api_key_secret_version, peuvent être modifiés.
Lorsque vous appelez UpdateRagCorpus, vous pouvez définir le champ vector_db. vector_db doit être défini sur weaviate par votre appel d'API CreateRagCorpus. Sinon, le système choisit l'option Base de données gérée RAG, qui est la valeur par défaut. Cette option ne peut pas être modifiée lorsque vous appelez l'API UpdateRagCorpus. Lorsque vous appelez UpdateRagCorpus et que le champ vector_db est partiellement défini, vous pouvez actualiser les champs marqués comme modifiables (également appelés "mutables").

Ce tableau liste les champs modifiables et immuables WeaviateConfig utilisés dans votre code.

Nom du champ	Modifiable ou Immuable
`http_endpoint`	Immuable une fois défini
`collection_name`	Immuable une fois défini
`api_key_authentication`	Modifiable

Créer le premier corpus RAG

Lorsque le compte de service de moteur RAG n'existe pas, procédez comme suit :

Créez un corpus RAG dans le moteur RAG avec une configuration Weaviate vide, ce qui lance le provisionnement du moteur RAG afin de créer un compte de service.
Choisissez un nom pour votre compte de service de moteur RAG au format suivant :

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Par exemple : service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com
À l'aide de votre compte de service, accédez à votre secret stocké dans le Secret Manager de votre projet, qui contient votre clé API Weaviate.
Obtenez les informations suivantes une fois le provisionnement de Weaviate terminé :
- Votre point de terminaison HTTPS ou HTTP Weaviate.
- Le nom de votre collection Weaviate.
Appelez l'API CreateRagCorpus pour créer un corpus RAG avec une configuration Weaviate vide, puis appelez l'API UpdateRagCorpus pour actualiser le corpus RAG avec les informations suivantes :
- Votre point de terminaison HTTPS ou HTTP Weaviate.
- Le nom de votre collection Weaviate.
- Le nom de la ressource de clé API.

Créer un autre corpus RAG

Lorsque le compte de service de moteur RAG existe, procédez comme suit :

Obtenez votre compte de service de moteur RAG à partir des autorisations de votre projet.
Activez l'option "Inclure les attributions de rôles fournies par Google".
Choisissez un nom pour votre compte de service de moteur RAG au format suivant :

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
À l'aide de votre compte de service, accédez à votre secret stocké dans le Secret Manager de votre projet, qui contient votre clé API Weaviate.
Lors du provisionnement de Weaviate, obtenez les informations suivantes :
- Le point de terminaison HTTPS ou HTTP de Weaviate.
- Le nom de votre collection Weaviate.
Créez un corpus RAG dans le moteur RAG, puis associez-le à votre collection Weaviate en effectuant l'une des opérations suivantes :
1. Effectuez un appel d'API CreateRagCorpus pour créer un corpus RAG avec une configuration Weaviate renseignée, ce qui est l'option recommandée.
2. Effectuez un appel d'API CreateRagCorpus pour créer un corpus RAG avec une configuration Weaviate vide, puis un appel d'API UpdateRagCorpus pour actualiser le corpus RAG avec les informations suivantes :
  - Le point de terminaison HTTP de la base de données Weaviate
  - Le nom de la collection Weaviate
  - La clé API

Exemples

Cette section présente un exemple de code qui montre comment configurer votre base de données Weaviate, Secret Manager, le corpus RAG et le fichier RAG. Un exemple de code est également fourni pour montrer comment importer des fichiers, récupérer le contexte, générer le contenu, et supprimer le corpus et les fichiers RAG.

Pour utiliser le notebook de l'API RAG de Model Garden, consultez Utiliser Weaviate avec Llama 3.

Configurer votre base de données Weaviate

Cet exemple de code montre comment configurer vos données Weaviate et Secret Manager.

REST

# TODO(developer): Update the variables.
# The HTTPS/HTTP Weaviate endpoint you created during provisioning.
HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"

# Select your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
# For example, "MyCollectionName"
# Note that the first letter needs to be capitalized.
# Otherwise, Weavaite will capitalize it for you.
WEAVIATE_COLLECTION_NAME="MyCollectionName"

# Create a collection in Weaviate which includes the required schema fields shown below.
echo '{
  "class": "'${WEAVIATE_COLLECTION_NAME}'",
  "properties": [
    { "name": "fileId", "dataType": [ "string" ] },
    { "name": "corpusId", "dataType": [ "string" ] },
    { "name": "chunkId", "dataType": [ "string" ] },
    { "name": "chunkDataType", "dataType": [ "string" ] },
    { "name": "chunkData", "dataType": [ "string" ] },
    { "name": "fileOriginalUri", "dataType": [ "string" ] }
  ]
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer "${WEAVIATE_API_KEY} \
    -d @- \
    ${HTTP_ENDPOINT_NAME}/v1/schema

Configurer Secret Manager

Pour configurer Secret Manager, vous devez l'activer et définir des autorisations.

Créer un secret

Pour activer Secret Manager, procédez comme suit :

Console

Accédez à la page Secret Manager.
Accéder à Secret Manager
Cliquez sur + Créer un secret.
Saisissez le nom de votre secret. Les noms de secrets ne doivent contenir que des lettres en alphabet latin (A à Z), des chiffres (0 à 9), des tirets (-) et des traits de soulignement (_).
La spécification des champs suivants est facultative :
1. Pour importer le fichier avec votre secret, cliquez sur Parcourir.
2. Consultez la règle de réplication.
3. Si vous souhaitez gérer manuellement les emplacements de votre secret, consultez Gérer manuellement les emplacements de ce secret. Vous devez sélectionner au moins une région.
4. Sélectionnez votre option de chiffrement.
5. Si vous souhaitez définir manuellement la période de rotation, cochez la case Définir la période de rotation.
6. Si vous souhaitez spécifier un ou plusieurs sujets de publication ou d'abonnement pour recevoir des notifications d'événement, cliquez sur Ajouter des sujets.
7. Par défaut, le secret n'expire jamais. Si vous souhaitez définir une date d'expiration, cochez la case Définir la date d'expiration.
8. Par défaut, les versions des secrets sont détruites immédiatement en cas de demande. Pour différer la destruction des versions de secret, consultez Définir la durée du délai de destruction.
9. Si vous souhaitez utiliser des étiquettes pour organiser et classer vos secrets, cliquez sur + Ajouter une étiquette.
10. Si vous souhaitez utiliser des annotations pour associer des métadonnées ne permettant pas d'identifier l'utilisateur à vos secrets, cliquez sur + Ajouter une annotation.
Cliquez sur Créer un secret.

REST

# Create a secret in SecretManager.
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets?secretId=${SECRET_NAME}" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"replication\": {\"automatic\": {}}}"

Python

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python décrites dans le guide de démarrage rapide de Vertex AI sur l'utilisation des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Vertex AI Python.

Pour vous authentifier auprès de Vertex AI, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

# Import the Secret Manager client library.
from google.cloud import secretmanager


def create_secret(
    project_id: str, secret_id: str, ttl: Optional[str] = None
) -> secretmanager.Secret:
    """
    Create a new secret with the given name. A secret is a logical wrapper
    around a collection of secret versions. Secret versions hold the actual
    secret material.

     Args:
        project_id (str): The project ID where the secret is to be created.
        secret_id (str): The ID to assign to the new secret. This ID must be unique within the project.
        ttl (Optional[str]): An optional string that specifies the secret's time-to-live in seconds with
                             format (e.g., "900s" for 15 minutes). If specified, the secret
                             versions will be automatically deleted upon reaching the end of the TTL period.

    Returns:
        secretmanager.Secret: An object representing the newly created secret, containing details like the
                              secret's name, replication settings, and optionally its TTL.

    Example:
        # Create a secret with automatic replication and no TTL
        new_secret = create_secret("my-project", "my-new-secret")

        # Create a secret with a TTL of 30 days
        new_secret_with_ttl = create_secret("my-project", "my-timed-secret", "7776000s")
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent project.
    parent = f"projects/{project_id}"

    # Create the secret.
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {"replication": {"automatic": {}}, "ttl": ttl},
        }
    )

    # Print the new secret name.
    print(f"Created secret: {response.name}")

Définir des autorisations

Vous devez accorder des autorisations Secret Manager à votre compte de service.

Console

Dans la section IAM et administration de la console Google Cloud , recherchez votre compte de service, puis cliquez sur l'icône en forme de crayon pour le modifier.
Dans le champ Rôle, sélectionnez Accesseur de secrets Secret Manager.

Python

def iam_grant_access(
    project_id: str, secret_id: str, member: str
) -> iam_policy_pb2.SetIamPolicyRequest:
    """
    Grant the given member access to a secret.
    """

    # Import the Secret Manager client library.
    from google.cloud import secretmanager

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Get the current IAM policy.
    policy = client.get_iam_policy(request={"resource": name})

    # Add the given member with access permissions.
    policy.bindings.add(role="roles/secretmanager.secretAccessor", members=[member])

    # Update the IAM Policy.
    new_policy = client.set_iam_policy(request={"resource": name, "policy": policy})

    # Print data about the secret.
    print(f"Updated IAM policy on {secret_id}")

Ajouter une version de secret

REST

# TODO(developer): Update the variables.
# Select a resource name for your Secret, which contains your API Key.
SECRET_NAME="MyWeaviateApiKeySecret"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"
# Encode your WEAVIATE_API_KEY using base 64.
SECRET_DATA=$(echo ${WEAVIATE_API_KEY} | base64)

# Create a new version of your secret which uses SECRET_DATA as payload
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets/${SECRET_NAME}:addVersion" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"payload\": {\"data\": \"${SECRET_DATA}\"}}"

Python

from google.cloud import secretmanager
import google_crc32c  # type: ignore


def add_secret_version(
    project_id: str, secret_id: str, payload: str
) -> secretmanager.SecretVersion:
    """
    Add a new secret version to the given secret with the provided payload.
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent secret.
    parent = client.secret_path(project_id, secret_id)

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload_bytes = payload.encode("UTF-8")

    # Calculate payload checksum. Passing a checksum in add-version request
    # is optional.
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    # Add the secret version.
    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )

    # Print the new secret version name.
    print(f"Added secret version: {response.name}")

Utiliser Weaviate avec Llama 3

Le notebook de l'API RAG de Model Garden montre comment utiliser le SDK Vertex AI pour Python avec un corpus Weaviate et le modèle Llama 3. Pour utiliser le notebook, procédez comme suit :

Pour en savoir plus, consultez Exemples.

Créer un corpus RAG

Cet exemple de code montre comment créer un corpus RAG et définit l'instance Weaviate comme sa base de données vectorielle.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# weaviate_http_endpoint = "weaviate-http-endpoint"
# weaviate_collection_name = "weaviate-collection-name"
# weaviate_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.EmbeddingModelConfig(
    publisher_model="publishers/google/models/text-embedding-004"
)

# Configure Vector DB
vector_db = rag.Weaviate(
    weaviate_http_endpoint=weaviate_http_endpoint,
    collection_name=weaviate_collection_name,
    api_key=weaviate_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    embedding_model_config=embedding_model_config,
    vector_db=vector_db,
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

Utiliser le fichier RAG

L'API RAG gère la mise en ligne, l'importation, le listage et la suppression du fichier.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : .
LOCATION : région dans laquelle traiter la requête.
RAG_CORPUS_ID : ID de la ressource RagCorpus.
INPUT_FILE : chemin d'accès à un fichier local.
FILE_DISPLAY_NAME : nom à afficher du RagFile.
RAG_FILE_DESCRIPTION : description du RagFile.

Méthode HTTP et URL :

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload

Corps JSON de la requête :

{
 "rag_file": {
  "display_name": "FILE_DISPLAY_NAME",
  "description": "RAG_FILE_DESCRIPTION"
 }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé INPUT_FILE, puis exécutez la commande suivante :

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @INPUT_FILE \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé INPUT_FILE, puis exécutez la commande suivante :

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile INPUT_FILE `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload" | Select-Object -Expand Content

Une réponse réussie renvoie la ressource RagFile. Le dernier composant du champ RagFile.name est le rag_file_id généré par le serveur.

Python

Pour savoir comment installer ou mettre à jour le SDK Vertex AI pour Python, consultez la section Installer le SDK Vertex AI pour Python. Pour en savoir plus, consultez la documentation de référence de l'API Python.


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# path = "path/to/local/file.txt"
# display_name = "file_display_name"
# description = "file description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_file = rag.upload_file(
    corpus_name=corpus_name,
    path=path,
    display_name=display_name,
    description=description,
)
print(rag_file)
# RagFile(name='projects/[PROJECT_ID]/locations/us-central1/ragCorpora/1234567890/ragFiles/09876543',
#  display_name='file_display_name', description='file description')

Importer des fichiers RAG

Vous pouvez importer des fichiers et des dossiers depuis Drive ou Cloud Storage.

REST

Utilisez response.metadata pour afficher les échecs partiels, le temps de requête et le temps de réponse dans l'objet response du SDK.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : .
LOCATION : région dans laquelle traiter la requête.
RAG_CORPUS_ID : ID de la ressource RagCorpus.
GCS_URIS : liste d'emplacements Cloud Storage. Par exemple : gs://my-bucket1, gs://my-bucket2
DRIVE_RESOURCE_ID : ID de la ressource Drive. Par exemple :

https://drive.google.com/file/d/ABCDE
https://drive.google.com/corp/drive/u/0/folders/ABCDEFG

DRIVE_RESOURCE_TYPE : type de la ressource Drive. Options :

RESOURCE_TYPE_FILE : fichier
RESOURCE_TYPE_FOLDER : dossier

CHUNK_SIZE(facultatif) : nombre de jetons que chaque fragment doit avoir.
CHUNK_OVERLAP (facultatif) : nombre de chevauchements de jetons entre les fragments.

Méthode HTTP et URL :

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import

Corps JSON de la requête :

{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": GCS_URIS
    },
    "google_drive_source": {
      "resource_ids": {
        "resource_id": DRIVE_RESOURCE_ID,
        "resource_type": DRIVE_RESOURCE_TYPE
      },
    }
  }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content

Une réponse réussie renvoie la ressource ImportRagFilesOperationMetadata.

L'exemple suivant montre comment importer un fichier depuis Cloud Storage. Utilisez le champ de contrôle max_embedding_requests_per_min pour limiter la fréquence à laquelle le moteur RAG appelle le modèle d'embedding au cours du processus d'indexation ImportRagFiles. La valeur par défaut du champ est de 1000 appels par minute.

// Cloud Storage bucket/file location.
// Such as "gs://rag-e2e-test/"
GCS_URIS=YOUR_GCS_LOCATION

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, GCS_URIS
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URIS}"\"'
    },
    "rag_file_chunking_config": {
      "chunk_size": 512
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

L'exemple suivant montre comment importer un fichier depuis Drive. Utilisez le champ de contrôle max_embedding_requests_per_min pour limiter la fréquence à laquelle le moteur RAG appelle le modèle d'embedding au cours du processus d'indexation ImportRagFiles. La valeur par défaut du champ est de 1000 appels par minute.

// Google Drive folder location.
FOLDER_RESOURCE_ID=YOUR_GOOGLE_DRIVE_FOLDER_RESOURCE_ID

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, FOLDER_RESOURCE_ID
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "google_drive_source": {
      "resource_ids": {
        "resource_id": '\""${FOLDER_RESOURCE_ID}"\"',
        "resource_type": "RESOURCE_TYPE_FOLDER"
      }
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

Python


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# paths = ["https://drive.google.com/file/123", "gs://my_bucket/my_files_dir"]  # Supports Google Cloud Storage and Google Drive Links

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.import_files(
    corpus_name=corpus_name,
    paths=paths,
    transformation_config=rag.TransformationConfig(
        rag.ChunkingConfig(chunk_size=512, chunk_overlap=100)
    ),
    import_result_sink="gs://sample-existing-folder/sample_import_result_unique.ndjson",  # Optional, this has to be an existing storage bucket folder, and file name has to be unique (non-existent).
    max_embedding_requests_per_min=900,  # Optional
)
print(f"Imported {response.imported_rag_files_count} files.")
# Example response:
# Imported 2 files.

Obtenir un fichier RAG

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : .
LOCATION : région dans laquelle traiter la requête.
RAG_CORPUS_ID : ID de la ressource RagCorpus.
RAG_FILE_ID : ID de la ressource RagFile.

Méthode HTTP et URL :

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

Exécutez la commande suivante :

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Une réponse réussie renvoie la ressource RagFile.

Python


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_file = rag.get_file(name=file_name)
print(rag_file)
# Example response:
# RagFile(name='projects/1234567890/locations/us-central1/ragCorpora/11111111111/ragFiles/22222222222',
# display_name='file_display_name', description='file description')

Lister les fichiers RAG

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : .
LOCATION : région dans laquelle traiter la requête.
RAG_CORPUS_ID : ID de la ressource RagCorpus.
PAGE_SIZE : taille de page de la liste standard. Vous pouvez ajuster le nombre de RagFiles à renvoyer par page en modifiant le paramètre page_size.
PAGE_TOKEN : jeton de page de la liste standard. Généralement obtenu à l'aide de ListRagFilesResponse.next_page_token de l'appel VertexRagDataService.ListRagFiles précédent.

Méthode HTTP et URL :

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

PowerShell

Exécutez la commande suivante :

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content

Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une liste de RagFiles sous le RAG_CORPUS_ID donné.

Python


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

files = rag.list_files(corpus_name=corpus_name)
for file in files:
    print(file.display_name)
    print(file.name)
# Example response:
# g-drive_file.txt
# projects/1234567890/locations/us-central1/ragCorpora/111111111111/ragFiles/222222222222
# g_cloud_file.txt
# projects/1234567890/locations/us-central1/ragCorpora/111111111111/ragFiles/333333333333

Supprimer un fichier RAG

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : .
LOCATION : région dans laquelle traiter la requête.
RAG_CORPUS_ID : ID de la ressource RagCorpus.
RAG_FILE_ID : ID de la ressource RagFile. Format : projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file_id}.

Méthode HTTP et URL :

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Exécutez la commande suivante :

curl -X DELETE \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

Exécutez la commande suivante :

$headers = @{  }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Une réponse réussie renvoie la ressource DeleteOperationMetadata.

Python


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag.delete_file(name=file_name)
print(f"File {file_name} deleted.")
# Example response:
# Successfully deleted the RagFile.
# File projects/1234567890/locations/us-central1/ragCorpora/1111111111/ragFiles/2222222222 deleted.

Récupérer le contexte

Lorsqu'un utilisateur pose une question ou fournit un prompt, le composant de récupération du RAG effectue une recherche dans sa base de connaissances afin de trouver des informations pertinentes pour la requête.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

LOCATION : région dans laquelle traiter la requête.
PROJECT_ID : .
RAG_CORPUS_RESOURCE : nom de la ressource RagCorpus. Format : projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
VECTOR_DISTANCE_THRESHOLD : seuls les contextes dont la distance vectorielle est inférieure au seuil sont renvoyés.
TEXT : texte de requête permettant d'obtenir des contextes pertinents.
SIMILARITY_TOP_K : nombre de contextes principaux à récupérer.

Méthode HTTP et URL :

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts

Corps JSON de la requête :

{
 "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "vector_distance_threshold": 0.8
  },
  "query": {
   "text": "TEXT",
   "similarity_top_k": SIMILARITY_TOP_K
  }
 }

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content

Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une liste des RagFiles associés.

Python


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/[rag_corpus_id]"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=10,
        filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
    ),
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Générer du contenu

Une prédiction contrôle la méthode LLM qui génère le contenu.

REST

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : .
LOCATION : région dans laquelle traiter la requête.
MODEL_ID : modèle LLM pour la génération de contenu. Par exemple : gemini-2.5-flash
GENERATION_METHOD : méthode LLM pour la génération de contenu. Options : generateContent, streamGenerateContent
INPUT_PROMPT : texte envoyé au LLM pour la génération de contenu. Essayez d'utiliser un prompt pertinent pour les fichiers rag importés.
RAG_CORPUS_RESOURCE : nom de la ressource RagCorpus. Format : projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
SIMILARITY_TOP_K (facultatif) : nombre de contextes principaux à récupérer.
VECTOR_DISTANCE_THRESHOLD (facultatif) : seuls les contextes dont la distance vectorielle est inférieure au seuil sont renvoyés.

Méthode HTTP et URL :

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD

Corps JSON de la requête :

{
 "contents": {
  "role": "user",
  "parts": {
    "text": "INPUT_PROMPT"
  }
 },
 "tools": {
  "retrieval": {
   "disable_attribution": false,
   "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "similarity_top_k": SIMILARITY_TOP_K,
    "vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD
   }
  }
 }
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" | Select-Object -Expand Content

Une réponse réussie renvoie le contenu généré avec des citations.

Python


from vertexai import rag
from vertexai.generative_models import GenerativeModel, Tool
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            rag_retrieval_config=rag.RagRetrievalConfig(
                top_k=10,
                filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
            ),
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-2.0-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

Recherche hybride

La recherche hybride est compatible avec la base de données Weaviate, qui combine les recherches sémantiques et par mots clés pour améliorer la pertinence des résultats de recherche. Lors de la récupération des résultats de recherche, une combinaison de scores de similarité issus de la sémantique (un vecteur dense) et de la correspondance des mots clés (un vecteur creux) produit les résultats classés finaux.

Recherche hybride à l'aide de l'API de récupération du moteur RAG

Voici un exemple d'activation d'une recherche hybride à l'aide de l'API de récupération du moteur RAG.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/[rag_corpus_id]"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=10,
        filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
    ),
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Utiliser la recherche hybride et le moteur RAG pour la génération de réponses ancrées

Voici un exemple d'utilisation de la recherche hybride et du moteur RAG pour la génération de réponses ancrées.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python


from vertexai import rag
from vertexai.generative_models import GenerativeModel, Tool
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            rag_retrieval_config=rag.RagRetrievalConfig(
                top_k=10,
                filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
            ),
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-2.0-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

Étape suivante

Utiliser Pinecone avec le moteur RAG de Vertex AI

Utiliser une base de données Weaviate avec le moteur de RAG Vertex AI Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Remarques

Provisionner la base de données Weaviate

Configurer et déployer votre instance de base de données Weaviate

Préparer le point de terminaison HTTPS

Créer votre collection Weaviate

Utiliser votre clé API pour provisionner Weaviate à l'aide de AuthN et AuthZ.

Créer la clé API

Stocker votre clé API dans Secret Manager

Provisionner votre compte de service de moteur RAG

Configurer l'environnement de votre console Google Cloud

Cliquez ici pour apprendre à configurer votre environnement

Python

Node.js

Java

Maven avec BOM

Maven sans BOM

Gradle without BOM

Go

C#

REST

Préparer votre corpus RAG

Utiliser les API CreateRagCorpus et UpdateRagCorpus

Créer le premier corpus RAG

Créer un autre corpus RAG

Exemples

Configurer votre base de données Weaviate

REST

Configurer Secret Manager

Créer un secret

Console

REST

Python

Définir des autorisations

Console

Python

Ajouter une version de secret

REST

Python

Utiliser Weaviate avec Llama 3

Créer un corpus RAG

REST

Python

Utiliser le fichier RAG

REST

curl

PowerShell

Python

Importer des fichiers RAG

REST

curl

PowerShell

Python

Obtenir un fichier RAG

REST

curl

PowerShell

Python

Lister les fichiers RAG

REST

curl

PowerShell

Python

Supprimer un fichier RAG

REST

curl

PowerShell

Python

Récupérer le contexte

REST

curl

PowerShell

Python

Générer du contenu

REST

curl

PowerShell

Python

Recherche hybride

Recherche hybride à l'aide de l'API de récupération du moteur RAG

Utiliser une base de données Weaviate avec le moteur de RAG Vertex AI

Utiliser votre clé API pour provisionner Weaviate à l'aide de `AuthN` et `AuthZ`.

Utiliser les API `CreateRagCorpus` et `UpdateRagCorpus`