Home
Vibe
Studio

Ce guide couvre l’intégralité du cycle de développement local : créer un schéma, déployer en local, indexer et interroger des documents, puis itérer avec de nouvelles migrations. Consultez Gérer les schémas pour apprendre à gérer les schémas et la référence de l’interface CLI pour la liste complète des options.

Prérequis

Prérequis

  • Plugin Search Toolkit Vespa installé (Installation)
  • Docker installé et en cours d’exécution
Étape 1 : Créer votre première migration

Étape 1 : Créer votre première migration

uv run mistral-vespa generate-migration --app-dir ./vespa_app initial_schema

Remplissez le fichier généré :

from mistralai.search.toolkit.plugins.vespa.app.schemas.app import (
    FieldDefinition,
    IndexingMode,
    SearchMode,
)
from mistralai.search.toolkit.plugins.vespa.migration import VespaMigration, create_schema, set_app_name


class InitialSchema(VespaMigration):
    def migrate(self) -> None:
        set_app_name("mynewproject")

        create_schema(
            name="articles",
            mode=SearchMode.INDEX,
            embedding_dimensions=1024,
            indexing_mode=IndexingMode.DOCUMENT_PER_CHUNK,
            default_query_profile_name="hybrid-profile",
            # The standard chunk fields (content, embedding, identity, metadata) are
            # added automatically. `fields` only declares your extra fields.
            fields=[
                FieldDefinition.TextField(name="title"),
            ],
        )

Avec IndexingMode.DOCUMENT_PER_CHUNK, create_schema() injecte automatiquement les champs standard de fragment (contenu, embedding, identité, métadonnées) ; utilisez fields pour en ajouter. (L’ancienne fonction create_default_schema() est obsolète et sera supprimée avant la version 1.0.0.)

i
Information

Restrictions sur le nom de l’application : le nom passé à set_app_name() ne doit contenir que des lettres minuscules (a-z). Les chiffres, les soulignés, les trait d’union et les autres caractères spéciaux ne sont pas autorisés.

i
Information

Les fonctions de fragment sont générées automatiquement si des champs de fragment sont présents. Si un schéma inclut à la fois un champ d’intégration multidimensionnelle et un champ de texte multidimensionnel, le plugin génère automatiquement best_chunks, chunk_scores et les auxiliaires associés.

Étape 2 : Démarrer une instance Vespa locale

Étape 2 : Démarrer une instance Vespa locale

uv run mistral-vespa local up --query-port 18080 --config-port 19171 --name vespa-dev
PortServiceUtilisation
18080HTTP du conteneurRequêtes et alimentation de documents
19171Serveur de configurationDéploiement de l’application
Étape 3 : Déployer à partir des migrations

Étape 3 : Déployer à partir des migrations

uv run mistral-vespa migrate \
  --app-dir ./vespa_app \
  --config-server http://localhost:19171 \
  --query-port 18080

mistral-vespa migrate construit le package d’application à partir des migrations en mémoire, le déploie et interroge l’endpoint de requête jusqu’à ce que l’app soit opérationnelle.

Étape 4 : Alimenter et interroger des documents

Étape 4 : Alimenter et interroger des documents

Alimentez un document :

curl -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "fields": {
      "title": "Document 1"
    }
  }' \
  "http://localhost:18080/document/v1/articles/articles/docid/doc1"

Exécutez une recherche :

curl -H "Content-Type: application/json" \
  --data '{"yql": "select * from sources * where true"}' \
  "http://localhost:18080/search/"
Étape 5 : Modifier le schéma

Étape 5 : Modifier le schéma

Créez une nouvelle migration pour faire évoluer le schéma :

uv run mistral-vespa generate-migration \
  --app-dir ./vespa_app \
  add_view_count

Mettez à jour le fichier généré :

from mistralai.search.toolkit.plugins.vespa.app.schemas.app import FieldDefinition
from mistralai.search.toolkit.plugins.vespa.migration import VespaMigration, add_field


class AddViewCount(VespaMigration):
    def migrate(self) -> None:
        add_field("articles", FieldDefinition.CountField(name="view_count"))

Prévisualisez la modification :

uv run mistral-vespa migrate \
  --app-dir ./vespa_app \
  --config-server http://localhost:19171 \
  --query-port 18080 \
  --dry-run

Appliquez-la (supprimez --dry-run) :

uv run mistral-vespa migrate \
  --app-dir ./vespa_app \
  --config-server http://localhost:19171 \
  --query-port 18080
Comprendre les modifications du schéma

Comprendre les modifications du schéma

Voici ce qui se passe lorsque vous modifiez le schéma d’une application en cours d’exécution :

ModificationComportement
Ajout de nouveaux champsAucun problème. Le nouveau champ n’a aucune valeur tant que les documents n’y ont pas écrit.
Modification de l’indexation d’un champVespa déclenche une réindexation en arrière-plan. Une incohérence temporaire est possible.
Suppression d’un champToutes les données et index pour ce champ sont supprimés.
Modification du type d’un champPerte de données. Préférez ajouter un nouveau champ, migrer les données, puis supprimer l’ancien.

Pour plus de détails, consultez la documentation Vespa sur la modification des schémas.

Profils de classement personnalisés et ressources supplémentaires

Profils de classement personnalisés et ressources supplémentaires

Ajoutez des profils de classement personnalisés ou des fichiers de modèle depuis une migration :

from pathlib import Path

from mistralai.search.toolkit.plugins.vespa.migration import VespaMigration, add_schema_rank_profiles


class AddCustomRankingProfile(VespaMigration):
    def migrate(self) -> None:
        add_schema_rank_profiles(
            "articles",
            [Path(__file__).parent.parent / "vespa-extra" / "custom.profile"],
        )

Vous pouvez utiliser le même modèle pour add_schema_model_files, add_schema_custom_document_summary et add_query_profiles.

Facultatif : Générer un instantané vespa.lock

Facultatif : Générer un instantané vespa.lock

Si votre dépôt conserve un package de référence généré pour la CI ou la relecture :

uv run mistral-vespa generate \
  --app-dir ./vespa_app \
  --path ./vespa.lock

Régénérez-le après chaque modification de schéma. Le déploiement doit toujours se faire à partir des migrations via mistral-vespa migrate.

Prise en charge par l’IDE

Prise en charge par l’IDE

Utilisez un IDE avec le plugin Vespa pour la coloration syntaxique, la complétion de code, la navigation entre les fonctions et les profils, et la détection des erreurs. Consultez la documentation sur la prise en charge des IDE par Vespa.

Voir aussi

Voir aussi