Cette page explique les concepts qui composent une application Vespa : le package d’application, les schémas, les champs, les profils de classement et les profils de requête. Pour apprendre à les créer et à les configurer, voir Gérer le schéma.

Un package d’application Vespa est un ensemble de fichiers de configuration qui indiquent au cluster comment stocker et classer les documents :

<app-package>/
├── schemas/
│   └── <document_type>.sd        # Schema definitions
└── search/
    └── query-profiles/
        ├── <profile_name>.xml    # Query profiles
        └── types/root.xml        # Query profile types

<app-package>/
├── schemas/
│   └── <document_type>.sd        # Schema definitions
└── search/
    └── query-profiles/
        ├── <profile_name>.xml    # Query profiles
        └── types/root.xml        # Query profile types

Vous ne rédigez jamais ces fichiers manuellement. Ils sont construits en mémoire à partir de vos migrations et téléchargés vers le cluster Vespa. Vous pouvez les inspecter avec mistral-vespa generate (voir référence de la CLI).

Les migrations sont des fichiers Python qui servent de source unique de vérité pour votre package d’application. Au lieu d’écrire manuellement les définitions de schéma et les fichiers de configuration, vous définissez les schémas, les champs et le classement via des migrations Python.

Fonctionnement :

1. Créer des fichiers de migration dans vespa_app/migrations/ qui décrivent vos schémas et votre configuration
2. Exécuter mistral-vespa migrate pour appliquer toutes les migrations dans l’ordre
3. Le système de migration construit le package d’application complet en mémoire
4. Le package est déployé sur votre cluster Vespa

Propriétés des migrations :

• Ajout uniquement — ajoutez de nouveaux fichiers pour les modifications, ne modifiez jamais ceux existants
• Ordonnées — triées par préfixe horodaté, exécutées séquentiellement à chaque déploiement
• Contrôlées par version — la seule chose que vous commisiez dans votre dépôt
• Idempotentes — sans risque de réexécution sans effets secondaires

Cette approche vous permet de versionner et de faire évoluer votre schéma comme n’importe quel autre code source, avec un historique complet et la possibilité de réviser les modifications.

Un schéma définit un type de document. Il déclare les champs qu’un document contient, la manière dont ces champs sont indexés, et la manière dont les résultats sont classés. Chaque schéma génère un fichier .sd et un profil de requête dans le package d’application.

Une application peut contenir plusieurs schémas, chacun représentant un type de document différent (par exemple, articles, commentaires). Les noms doivent être uniques.

mode "Recherche"

Chaque schéma fonctionne selon l’un des deux modes suivants :

Mode d’indexation

Chaque schéma déclare également un mode d’indexation qui contrôle la manière dont les documents sont organisés dans Vespa. Ce paramètre est obligatoire pour chaque schéma, afin que la disposition soit toujours explicite.

Avec DOCUMENT_PER_CHUNK, create_schema() injecte automatiquement les champs standard des fragments (contenu, embedding, identité, métadonnées). Consultez le Modèle de document pour savoir comment les fragments sont identifiés et Gérer le schéma pour définir le mode.

Les champs définissent les données qu’un document contient et la manière dont ces données sont utilisées pour l’indexation et le classement. Le plugin propose cinq types de champs :

Les champs peuvent être monolignes ou multidimensionnels (tableaux). Pour un champ de type tableau, définissez multi_dimensional=True, par exemple pour une liste d’étiquettes ou d’embeddings de sections.

Jeu de champs par défaut

Le plugin génère un jeu de champs par défaut contenant tous les champs de type TextField. Ce jeu de champs définit les champs recherchés lors de l’utilisation de userQuery() dans YQL. Les autres types de champs sont exclus.

Le plugin génère quatre profils de classement par schéma :

Classement par phases

Vespa classe les documents par phases pour équilibrer rapidité et qualité :

1. Première phase — appliquée à tous les documents correspondants. Doit être rapide. Utilise des fonctions comme BM25, la distance des incorporations, la fraîcheur.
2. Deuxième phase — reclasse les k documents principaux de la phase 1. Peut utiliser des fonctions plus coûteuses comme la correspondance de champ, le scoring logarithmique ou les modèles ML.
3. Phase globale (facultative) — s’exécute sur le jeu de résultats fusionné dans le nœud conteneur.

Le plugin associe chaque fonction auto-générée à la phase appropriée en fonction du type de champ.

Profils pondérés

Les profils weighted-rank1 et weighted-rank2 vous permettent d’ajuster le classement au moment de la requête en modifiant les poids des fonctions sans modifier le schéma.

Phase 1: bm25_title_weight * bm25_title +
         content_embedding_distance_weight * content_embedding_distance +
         freshness_created_at_weight * freshness_created_at

Phase 2: firstPhase +
         match_title_weight * match_title +
         log_freshness_created_at_weight * log_freshness_created_at

Phase 1: bm25_title_weight * bm25_title +
         content_embedding_distance_weight * content_embedding_distance +
         freshness_created_at_weight * freshness_created_at

Phase 2: firstPhase +
         match_title_weight * match_title +
         log_freshness_created_at_weight * log_freshness_created_at

Tous les poids commencent à 0. Définissez un ou plusieurs à une valeur non nulle pour activer le classement.

Le plugin génère un profil de requête par schéma (nommé via default_query_profile_name, par défaut le nom du schéma). Il inclut :

• Une requête YQL pour la recherche hybride (si des incorporations sont présentes) ou la recherche par mot-clé
• Le profil de classement weighted-rank2 comme profil par défaut
• Des champs de type de requête pour les poids des fonctions

Pour plus d’informations, voir Profils de requête et la documentation Vespa sur les profils de requête.

• Gérer le schéma — Comment créer des schémas, des champs et un classement via des migrations
• Gérer le classement — Configurer le classement au moment de la requête