Cette page explique les concepts qui composent une application Vespa : package d’application, schémas, champs, profils de classement et profils de requête. Pour apprendre à les créer et à les configurer, consultez 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 n’écrivez jamais ces fichiers à la main. 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 la référence de la CLI).

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

Fonctionnement :

1. Créez des fichiers de migration dans vespa_app/migrations/ pour décrire vos schémas et votre configuration
2. Exécutez 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 :

• Append-only : ajoutez de nouveaux fichiers pour les modifications, sans jamais modifier les fichiers existants
• Ordonnées : triées par préfixe d’horodatage, exécutées séquentiellement à chaque déploiement
• Versionnées : le seul élément que vous committez dans votre dépôt
• Idempotentes : peuvent être réexécutées sans effet de bord

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 relire 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 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 de recherche

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

Mode d’indexation

Chaque schéma déclare aussi un mode d’indexation qui contrôle la manière dont les documents sont organisés dans Vespa. Il est obligatoire sur chaque schéma, ce qui rend l’organisation toujours explicite.

Avec DOCUMENT_PER_CHUNK, create_schema() injecte automatiquement les champs de fragment standard (content, embedding, identity, metadata). Consultez le modèle de document pour comprendre comment les fragments sont identifiés, Gérer le schéma pour définir le mode, et la référence des assistants de migration pour la signature complète de create_schema().

Les champs définissent les données contenues dans un document et la manière dont elles sont utilisées pour l’indexation et le classement. Le plugin fournit les types de champs suivants :

Les champs peuvent être monovalués ou multidimensionnels (tableaux). Définissez multi_dimensional=True pour un champ de type tableau, par exemple une liste de tags ou des embeddings de sections. Consultez la référence des assistants de migration pour la signature du constructeur de chaque type de champ.

Fieldset par défaut

Le plugin génère un fieldset par défaut contenant tous les champs TextField. Ce fieldset définit les champs recherchés lors de l’utilisation de userQuery() en 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 vitesse et qualité :

1. Première phase : appliquée à tous les documents correspondants. Elle doit être rapide. Elle utilise des fonctions comme BM25, la distance d’embedding ou la fraîcheur.
2. Deuxième phase : reclasse les k premiers documents de la phase 1. Elle peut utiliser des fonctions plus coûteuses comme la correspondance de champ, le scoring logarithmique ou des modèles de ML.
3. Phase globale (facultative) : s’exécute sur l’ensemble de résultats fusionné dans le nœud conteneur.

Le plugin associe chaque fonction générée automatiquement à la phase appropriée selon le 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 pondérations 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

Toutes les pondérations commencent à 0. Définissez une ou plusieurs pondérations sur 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, avec le nom du schéma par défaut). Il inclut :

• Une requête YQL pour la recherche hybride (si des embeddings sont présents) ou la recherche par mots-clés
• Le profil de classement weighted-rank2 par défaut
• Des champs de type requête pour les pondérations de fonctions

Pour en savoir plus, consultez Gérer le classement et la documentation Vespa sur les profils de requête.

• Gérer le schéma : créer des schémas, des champs et un classement avec des migrations
• Gérer le classement : configurer le classement au moment de la requête