Home
Studio

Ce guide couvre toute la boucle de développement local : créer un schéma, déployer en local, alimenter 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 la 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

Renseignez le fichier généré :

from mistralai.search.toolkit.embedding import MistralEmbeddingPreset
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_model=MistralEmbeddingPreset.MISTRAL_EMBED_DIM_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 de fragment standard (content, embedding, identity, metadata) ; utilisez fields pour ajouter les vôtres. (L’ancien helper create_default_schema() est déprécié et sera supprimé avant la version 1.0.0.)

i
Information

Restrictions sur le nom de l’application : le nom passé à set_app_name() doit contenir uniquement des lettres minuscules (a-z). Les chiffres, les underscores, les traits 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 lorsque des champs de fragment sont présents. Si un schéma inclut à la fois un champ d’embedding multidimensionnel et un champ de texte multidimensionnel, le plugin génère automatiquement best_chunks, chunk_scores et les helpers 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 en documents
19171Serveur de configurationDéploiements d’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, puis interroge l’endpoint de requête jusqu’à ce que l’application soit active.

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

Comprendre les modifications de schéma

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 pas de valeur tant que des documents n’y écrivent pas.
Modification du mode d’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 tous les index de 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 de Vespa sur la modification des schémas.

Profils de ranking personnalisés et ressources supplémentaires

Profils de ranking personnalisés et ressources supplémentaires

Ajoutez des profils de ranking 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 snapshot vespa.lock

Facultatif : générer un snapshot 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

Regénérez-le après chaque modification de schéma. Le déploiement doit toujours s’effectuer à partir des migrations via 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 les fonctions et les profils, ainsi que la détection des erreurs. Consultez la documentation de prise en charge des IDE Vespa.

Voir aussi

Voir aussi