Home
Studio

Gérez les schémas de votre application Vespa avec des migrations Python. Pour comprendre les concepts liés aux schémas, aux champs et au ranking, consultez Anatomie d'une application Vespa.

Créer et faire évoluer les schémas

Créer et faire évoluer les schémas

Utilisez les migrations pour définir et modifier vos schémas. Les migrations sont des fichiers Python placés dans vespa_app/migrations/. Elles fonctionnent en ajout uniquement, sont ordonnées par horodatage et sont réexécutées à chaque déploiement.

Générez une nouvelle migration :

uv run mistral-vespa generate-migration --app-dir ./vespa_app <name>

Cette commande crée un fichier horodaté avec un squelette de classe :

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


class MyMigration(VespaMigration):
    def migrate(self) -> None:
        pass  # Define your changes here
Définir un schéma

Définir un schéma

Utilisez create_schema avec un indexing_mode explicite. DOCUMENT_PER_CHUNK est le mode recommandé. Il indexe un document Vespa par fragment et injecte automatiquement les champs de fragment standard (contenu, embedding, identité, métadonnées) :

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("myapp")
        create_schema(
            name="articles",
            mode=SearchMode.INDEX,
            embedding_model=MistralEmbeddingPreset.MISTRAL_EMBED_DIM_1024,
            indexing_mode=IndexingMode.DOCUMENT_PER_CHUNK,
            # The standard chunk fields (content, embedding, identity, metadata) are
            # added automatically. `fields` only declares your extra fields.
            fields=[
                FieldDefinition.TextField(name="title"),
                FieldDefinition.TimestampField(name="created_at"),
            ],
        )
i
Information

Restrictions sur le nom de l'application : Le nom transmis à 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.

Cette commande injecte les champs requis par le pipeline (contenu du fragment, embedding, identité, métadonnées) et ajoute les champs propres à votre projet via fields.

Avertissement

create_default_schema(...) est déprécié. Il produit uniquement l'ensemble de champs hérité IndexingMode.SINGLE_DOCUMENT et sera supprimé avant la version 1.0.0. Utilisez plutôt create_schema(..., indexing_mode=...).

Ajouter des champs à un schéma existant

Utilisez add_field dans une nouvelle migration pour ajouter des champs après la création du schéma initial :

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

Définissez multi_dimensional=True pour les champs de type tableau (par exemple, des embeddings par fragment ou des fragments de texte). Le modèle d'embedding est défini une seule fois dans create_schema(embedding_model=...).

Plusieurs schémas

Appelez create_schema() plusieurs fois pour enregistrer plusieurs types de documents dans une même application. Chaque schéma produit son propre fichier .sd et son propre profil de requête. Les noms doivent être uniques.

Helpers de migration

Helpers de migration

HelperDescription
set_app_name(name)Définir le nom de l'application (requis dans la première migration)
create_schema(...)Créer un schéma avec un indexing_mode explicite et des champs (recommandé)
create_default_schema(...)Schéma hérité à document unique. Déprécié et supprimé avant la version 1.0.0.
add_field(schema, field)Ajouter un champ à un schéma existant
add_custom_functions(schema, functions)Ajouter des fonctions de ranking personnalisées à un schéma existant
add_query_profiles(...)Ajouter ou mettre à jour des profils de requête
add_schema_rank_profiles(schema, paths)Ajouter des fichiers de profils de ranking personnalisés
add_schema_model_files(schema, paths)Ajouter des fichiers de modèle ML
add_schema_custom_document_summary(...)Ajouter des résumés de documents personnalisés
set_content_id(id)Remplacer l'id du cluster de contenu (évite les renommages de cluster destructifs)
allow_schema_removal(until)Autoriser la suppression du schéma jusqu'à une date donnée

Pour les signatures et paramètres complets, consultez la référence des helpers de migration.

Déploiement

Déploiement

mistral-vespa migrate découvre les migrations, les exécute dans l'ordre, construit le paquet d'application, puis le télécharge. Consultez les guides Développement local et Déployer et exploiter pour plus de détails.

Snapshot facultatif

Snapshot facultatif

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

Écrit le paquet d'application sur le disque pour inspection ou validation CI. Il n'est pas utilisé pour le déploiement.

Voir aussi

Voir aussi