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

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        # Définitions de schéma
└── search/
    └── query-profiles/
        ├── <profile_name>.xml    # Profils de requête
        └── types/root.xml        # Types de profils de requête

<app-package>/
├── schemas/
│   └── <document_type>.sd        # Définitions de schéma
└── search/
    └── query-profiles/
        ├── <profile_name>.xml    # Profils de requête
        └── types/root.xml        # Types de profils de requête

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

Les migrations sont des fichiers Python qui constituent la source de vérité de votre package d’application. Au lieu d’écrire manuellement des schémas et des fichiers de configuration, vous définissez les schémas, les champs et le ranking via des migrations Python.

Fonctionnement :

1. Créez des fichiers de migration dans vespa_app/migrations/ qui décrivent vos schémas et votre configuration
2. Exécutez mistral-vespa migrate pour valider toutes les migrations dans l’ordre
3. Le système de migration génère l’ensemble du package d’application en mémoire
4. Le package est déployé sur votre cluster Vespa

Propriétés des migrations :

• Append-only — ajoutez de nouveaux fichiers pour chaque modification, ne modifiez jamais les fichiers existants
• Ordonnées — triées par préfixe de timestamp, exécutées séquentiellement à chaque déploiement
• Versionnées — la seule chose que vous poussez dans votre dépôt
• Idempotentes — sans effet de bord même en cas de réexécution

Cette approche vous permet de versionner et faire évoluer vos schémas comme n’importe quel code source, avec tout l’historique et la possibilité de revoir les modifications.

Un schéma définit un type de document. Il déclare les champs contenus dans le document, la manière dont ils sont indexés et comment les résultats sont ordonnés. Chaque schéma produit 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, comments). Les noms doivent être uniques.

Mode "Recherche"

Chaque schéma fonctionne selon deux modes :

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

Les champs peuvent être à valeur unique ou multi-dimensionnels (tableaux). Par exemple, les embeddings par fragment et les fragments de texte sont des champs multi-dimensionnels.

Ensemble de champs par défaut

Le plugin génère un ensemble de champs par défaut qui inclut tous les champs TextField. Cet ensemble sert à déterminer sur quels champs la recherche s'effectue lors de l'utilisation de userQuery() dans YQL. Les autres types de champs sont exclus.

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

Ranking en plusieurs phases

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

1. Première phase — appliquée à tous les documents correspondants. Doit être rapide. Utilise des fonctions type BM25, distance d'embedding, fraîcheur.
2. Seconde phase — reclasse le top k des documents extraits en phase 1. Permet d'utiliser des fonctions plus complexes comme la correspondance champ, le score logarithmique ou des modèles ML.
3. Phase globale (optionnel) — s'applique sur l'ensemble des résultats fusionnés dans le nœud conteneur.

Le plugin associe chaque fonction générée automatiquement à la phase la plus adaptée selon le type de champ.

Profils pondérés

Les profils weighted-rank1 et weighted-rank2 vous permettent d’ajuster le ranking à la requête en modifiant les poids des fonctions, sans changer 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 sont initialisés à 0. Il suffit d’attribuer une valeur non nulle à un ou plusieurs pour activer le ranking.

Le plugin crée un profil de requête par schéma (nommé via default_query_profile_name, par défaut le nom du schéma). Il comprend :

• Une requête YQL pour la recherche hybride (si des embeddings sont présents) ou une recherche par mot-clé
• Le profil de ranking weighted-rank2 en valeur par défaut
• Des champs de type « query » pour pondérer les fonctions

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

• Gérer les schémas : Création de schémas, champs et ranking via des migrations
• Gérer le ranking : Configurer le ranking à la requête