Home
Vibe
Studio

Ce guide détaille le cycle complet du développement local : création d'un schéma, déploiement en local, alimentation et requête de documents, puis itération avec de nouvelles migrations. Consultez Gérer les schémas pour apprendre à gérer les schémas et la référence CLI pour la liste complète des options.

Prérequis

Prérequis

  • Plugin Vespa Search Toolkit 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

Complétez le fichier généré :

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


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

        create_default_schema(
            name="articles",
            mode=SearchMode.INDEX,
            embedding_dimensions=1024,
            schema_version=1,
            default_query_profile_name="hybrid-profile",
            additional_fields=[
                FieldDefinition.TextField(name="title"),
            ],
        )

La fonction create_default_schema() inclut par défaut tous les champs nécessaires au VespaSearchIndex. Utilisez additional_fields pour ajouter des champs adaptés à votre cas d'usage. Pour un contrôle total sur la liste des champs, utilisez create_schema() et définissez-les explicitement.

i
Information

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

i
Information

Les fonctions de fragments sont générées automatiquement lorsqu'un champ fragment est présent. Si un schéma inclut à la fois un champ d'embedding multi-dimensionnel et un champ texte multi-dimensionnel, le plugin génère automatiquement best_chunks, chunk_scores et les helpers associés.

Étape 2 : lancer une instance Vespa locale

Étape 2 : lancer une instance Vespa locale

uv run mistral-vespa local up --query-port 18080 --config-port 19171 --name vespa-dev
PortServiceUtilisation
18080Container HTTPAlimentation et requête
19171Config serverDéploiement de l'application
Étape 3 : déployer depuis les migrations

Étape 3 : déployer depuis les migrations

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

mistral-vespa migrate construit le package de l'application à partir des migrations en mémoire, le déploie et interroge l'endpoint de requête jusqu'à la mise en ligne de l'application.

É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"

Effectuez 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 changements de schéma

Comprendre les changements de schéma

Ce qui se passe lorsque vous modifiez le schéma d'une application en cours d'exécution :

ChangementComportement
Ajout de nouveaux champsAucun problème. Le nouveau champ est vide tant qu'aucun document ne l'utilise.
Modification de l'indexationVespa lance un réindexage en tâche de fond. Incohérence temporaire possible.
Suppression d'un champToutes les données et index du champ sont supprimés.
Changement de type de champPerte de données. Mieux vaut ajouter un 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 principe pour add_schema_model_files, add_schema_custom_document_summary et add_query_profiles.

Optionnel : générer un snapshot vespa.lock

Optionnel : générer un snapshot vespa.lock

Si votre dépôt conserve un package de référence généré pour CI ou 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 depuis les migrations avec mistral-vespa migrate.

Prise en charge des IDE

Prise en charge des IDE

Utilisez un IDE avec le plugin Vespa pour la coloration syntaxique, l'autocomplétion, la navigation entre fonctions et profils, et la détection d'erreurs. Consultez la documentation sur la prise en charge des IDE Vespa.

Voir aussi

Voir aussi