Recherche vidéo avancée : Tirer parti de Twelve Labs et de Milvus pour la recherche sémantique

Introduction

Bienvenue dans ce tutoriel complet sur la mise en œuvre de la recherche sémantique de vidéos à l'aide de Twelve Labs Embed API et de Milvus. Dans ce guide, nous verrons comment exploiter la puissance des embeddings multimodaux avancés de Twelve Labs et de la base de données vectorielle efficace de Milvus pour créer une solution de recherche vidéo robuste. En intégrant ces technologies, les développeurs peuvent exploiter de nouvelles possibilités en matière d'analyse de contenu vidéo, permettant des applications telles que la recherche vidéo basée sur le contenu, les systèmes de recommandation et les moteurs de recherche sophistiqués qui comprennent les nuances des données vidéo.

Ce tutoriel vous guidera tout au long du processus, de la configuration de votre environnement de développement à la mise en œuvre d'une application de recherche vidéo sémantique fonctionnelle. Nous aborderons des concepts clés tels que la génération d'incrustations multimodales à partir de vidéos, leur stockage efficace dans Milvus et l'exécution de recherches de similarité pour récupérer le contenu pertinent. Que vous construisiez une plate-forme d'analyse vidéo, un outil de découverte de contenu ou que vous amélioriez vos applications existantes avec des fonctionnalités de recherche vidéo, ce guide vous fournira les connaissances et les étapes pratiques pour exploiter les forces combinées de Twelve Labs et de Milvus dans vos projets.

Conditions préalables

Avant de commencer, assurez-vous de disposer des éléments suivants :

Une clé API Twelve Labs (inscrivez-vous sur https://api.twelvelabs.io si vous n'en avez pas) Python 3.7 ou supérieur installé sur votre système.

Configuration de l'environnement de développement

Créez un nouveau répertoire pour votre projet et naviguez-y :

mkdir video-search-tutorial
cd video-search-tutorial

Créez un environnement virtuel (facultatif mais recommandé) :

python -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

Installez les bibliothèques Python requises :

pip install twelvelabs pymilvus

Créez un nouveau fichier Python pour votre projet :

touch video_search.py

Ce fichier video_search.py sera le script principal que nous utiliserons pour le tutoriel. Ensuite, configurez votre clé API Twelve Labs en tant que variable d'environnement pour la sécurité :

export TWELVE_LABS_API_KEY='your_api_key_here'

Connexion à Milvus

Pour établir une connexion avec Milvus, nous utiliserons la classe MilvusClient. Cette approche simplifie le processus de connexion et nous permet de travailler avec une instance Milvus locale basée sur des fichiers, ce qui est parfait pour notre tutoriel.

from pymilvus import MilvusClient

# Initialize the Milvus client
milvus_client = MilvusClient("milvus_twelvelabs_demo.db")

print("Successfully connected to Milvus")

Ce code crée une nouvelle instance de client Milvus qui stockera toutes les données dans un fichier nommé milvus_twelvelabs_demo.db. Cette approche basée sur les fichiers est idéale pour le développement et les tests.

Création d'une collection Milvus pour les incorporations vidéo

Maintenant que nous sommes connectés à Milvus, créons une collection pour stocker nos incorporations vidéo et les métadonnées associées. Nous allons définir le schéma de la collection et créer la collection si elle n'existe pas encore.

# Initialize the collection name
collection_name = "twelvelabs_demo_collection"

# Check if the collection already exists and drop it if it does
if milvus_client.has_collection(collection_name=collection_name):
    milvus_client.drop_collection(collection_name=collection_name)

# Create the collection
milvus_client.create_collection(
    collection_name=collection_name,
    dimension=1024  # The dimension of the Twelve Labs embeddings
)

print(f"Collection '{collection_name}' created successfully")

Dans ce code, nous vérifions d'abord si la collection existe déjà et la supprimons si c'est le cas. Cela nous permet de faire table rase du passé. Nous créons la collection avec une dimension de 1024, ce qui correspond à la dimension de sortie des embeddings de Twelve Labs.

Génération d'embeddings avec l'API Embed de Twelve Labs

Pour générer des embeddings pour nos vidéos à l'aide de l'API Embed de Twelve Labs, nous utiliserons le SDK Python de Twelve Labs. Ce processus implique la création d'une tâche d'intégration, l'attente de son achèvement et la récupération des résultats. Voici comment procéder :

Tout d'abord, assurez-vous que le SDK Twelve Labs est installé et importez les modules nécessaires :

from twelvelabs import TwelveLabs
from twelvelabs.models.embed import EmbeddingsTask
import os

# Retrieve the API key from environment variables
TWELVE_LABS_API_KEY = os.getenv('TWELVE_LABS_API_KEY')

Initialiser le client Twelve Labs :

twelvelabs_client = TwelveLabs(api_key=TWELVE_LABS_API_KEY)

Créez une fonction pour générer des embeddings pour une URL vidéo donnée :

def generate_embedding(video_url):
    """
    Generate embeddings for a given video URL using the Twelve Labs API.

    This function creates an embedding task for the specified video URL using
    the Marengo-retrieval-2.6 engine. It monitors the task progress and waits
    for completion. Once done, it retrieves the task result and extracts the
    embeddings along with their associated metadata.

    Args:
        video_url (str): The URL of the video to generate embeddings for.

    Returns:
        tuple: A tuple containing two elements:
            1. list: A list of dictionaries, where each dictionary contains:
                - 'embedding': The embedding vector as a list of floats.
                - 'start_offset_sec': The start time of the segment in seconds.
                - 'end_offset_sec': The end time of the segment in seconds.
                - 'embedding_scope': The scope of the embedding (e.g., 'shot', 'scene').
            2. EmbeddingsTaskResult: The complete task result object from Twelve Labs API.

    Raises:
        Any exceptions raised by the Twelve Labs API during task creation,
        execution, or retrieval.
    """

    # Create an embedding task
    task = twelvelabs_client.embed.task.create(
        engine_name="Marengo-retrieval-2.6",
        video_url=video_url
    )
    print(f"Created task: id={task.id} engine_name={task.engine_name} status={task.status}")

    # Define a callback function to monitor task progress
    def on_task_update(task: EmbeddingsTask):
        print(f"  Status={task.status}")

    # Wait for the task to complete
    status = task.wait_for_done(
        sleep_interval=2,
        callback=on_task_update
    )
    print(f"Embedding done: {status}")

    # Retrieve the task result
    task_result = twelvelabs_client.embed.task.retrieve(task.id)

    # Extract and return the embeddings
    embeddings = []
    for v in task_result.video_embeddings:
        embeddings.append({
            'embedding': v.embedding.float,
            'start_offset_sec': v.start_offset_sec,
            'end_offset_sec': v.end_offset_sec,
            'embedding_scope': v.embedding_scope
        })
    
    return embeddings, task_result

Utilisez la fonction pour générer des embeddings pour vos vidéos :

# Example usage
video_url = "https://example.com/your-video.mp4"

# Generate embeddings for the video
embeddings, task_result = generate_embedding(video_url)

print(f"Generated {len(embeddings)} embeddings for the video")
for i, emb in enumerate(embeddings):
    print(f"Embedding {i+1}:")
    print(f"  Scope: {emb['embedding_scope']}")
    print(f"  Time range: {emb['start_offset_sec']} - {emb['end_offset_sec']} seconds")
    print(f"  Embedding vector (first 5 values): {emb['embedding'][:5]}")
    print()

Cette implémentation vous permet de générer des embeddings pour n'importe quelle URL vidéo à l'aide de l'API Embed de Twelve Labs. La fonction generate_embedding gère l'ensemble du processus, de la création de la tâche à la récupération des résultats. Elle renvoie une liste de dictionnaires, chacun contenant un vecteur d'intégration avec ses métadonnées (plage temporelle et portée). N'oubliez pas de gérer les erreurs potentielles, telles que les problèmes de réseau ou les limites de l'API, dans un environnement de production. N'oubliez pas de gérer les erreurs potentielles, telles que les problèmes de réseau ou les limites de l'API, dans un environnement de production.

Insertion des embeddings dans Milvus

Après avoir généré des embeddings à l'aide de l'API Embed de Twelve Labs, l'étape suivante consiste à insérer ces embeddings avec leurs métadonnées dans notre collection Milvus. Ce processus nous permet de stocker et d'indexer nos incorporations vidéo pour une recherche de similarité efficace ultérieurement.

Voici comment insérer les embeddings dans Milvus :

def insert_embeddings(milvus_client, collection_name, task_result, video_url):
    """
    Insert embeddings into the Milvus collection.

    Args:
        milvus_client: The Milvus client instance.
        collection_name (str): The name of the Milvus collection to insert into.
        task_result (EmbeddingsTaskResult): The task result containing video embeddings.
        video_url (str): The URL of the video associated with the embeddings.

    Returns:
        MutationResult: The result of the insert operation.

    This function takes the video embeddings from the task result and inserts them
    into the specified Milvus collection. Each embedding is stored with additional
    metadata including its scope, start and end times, and the associated video URL.
    """
    data = []

    for i, v in enumerate(task_result.video_embeddings):
        data.append({
            "id": i,
            "vector": v.embedding.float,
            "embedding_scope": v.embedding_scope,
            "start_offset_sec": v.start_offset_sec,
            "end_offset_sec": v.end_offset_sec,
            "video_url": video_url
        })

    insert_result = milvus_client.insert(collection_name=collection_name, data=data)
    print(f"Inserted {len(data)} embeddings into Milvus")
    return insert_result

# Usage example
video_url = "https://example.com/your-video.mp4"

# Assuming this function exists from previous step
embeddings, task_result = generate_embedding(video_url)

# Insert embeddings into the Milvus collection
insert_result = insert_embeddings(milvus_client, collection_name, task_result, video_url)
print(insert_result)

Cette fonction prépare les données à insérer, y compris toutes les métadonnées pertinentes telles que le vecteur d'intégration, l'intervalle de temps et l'URL de la vidéo source. Elle utilise ensuite le client Milvus pour insérer ces données dans la collection spécifiée.

Recherche de similarité

Une fois nos embeddings stockés dans Milvus, nous pouvons effectuer des recherches de similarité pour trouver les segments vidéo les plus pertinents sur la base d'un vecteur de requête. Voici comment mettre en œuvre cette fonctionnalité :

def perform_similarity_search(milvus_client, collection_name, query_vector, limit=5):
    """
    Perform a similarity search on the Milvus collection.

    Args:
        milvus_client: The Milvus client instance.
        collection_name (str): The name of the Milvus collection to search in.
        query_vector (list): The query vector to search for similar embeddings.
        limit (int, optional): The maximum number of results to return. Defaults to 5.

    Returns:
        list: A list of search results, where each result is a dictionary containing
              the matched entity's metadata and similarity score.

    This function searches the specified Milvus collection for embeddings similar to
    the given query vector. It returns the top matching results, including metadata
    such as the embedding scope, time range, and associated video URL for each match.
    """
    search_results = milvus_client.search(
        collection_name=collection_name,
        data=[query_vector],
        limit=limit,
        output_fields=["embedding_scope", "start_offset_sec", "end_offset_sec", "video_url"]
    )

    return search_results
    
# define the query vector
# We use the embedding inserted previously as an example. In practice, you can replace it with any video embedding you want to query.
query_vector = task_result.video_embeddings[0].embedding.float

# Perform a similarity search on the Milvus collection
search_results = perform_similarity_search(milvus_client, collection_name, query_vector)

print("Search Results:")
for i, result in enumerate(search_results[0]):
    print(f"Result {i+1}:")
    print(f"  Video URL: {result['entity']['video_url']}")
    print(f"  Time Range: {result['entity']['start_offset_sec']} - {result['entity']['end_offset_sec']} seconds")
    print(f"  Similarity Score: {result['distance']}")
    print()

Cette implémentation effectue les opérations suivantes :

1. Définit une fonction perform_similarity_search qui prend un vecteur de requête et recherche des embeddings similaires dans la collection Milvus.
2. Elle utilise la méthode de recherche du client Milvus pour trouver les vecteurs les plus similaires.
3. Spécifie les champs de sortie que nous voulons récupérer, y compris les métadonnées sur les segments vidéo correspondants.
4. Fournit un exemple d'utilisation de cette fonction avec une vidéo de requête, en générant d'abord son intégration, puis en l'utilisant pour la recherche.
5. Imprime les résultats de la recherche, y compris les métadonnées pertinentes et les scores de similarité.

En mettant en œuvre ces fonctions, vous avez créé un flux de travail complet pour stocker les incorporations vidéo dans Milvus et effectuer des recherches de similarité. Cette configuration permet de récupérer efficacement des contenus vidéo similaires sur la base des embeddings multimodaux générés par l'API Embed de Twelve Labs.

Optimisation des performances

D'accord, faisons passer cette application au niveau supérieur ! Lorsque l'on traite des collections de vidéos à grande échelle, les performances sont essentielles. Pour les optimiser, nous devons mettre en œuvre un traitement par lots pour la génération et l'insertion d'embeddings dans Milvus. De cette manière, nous pouvons traiter plusieurs vidéos simultanément, ce qui réduit considérablement le temps de traitement global. En outre, nous pourrions exploiter la fonction de partitionnement de Milvus pour organiser nos données de manière plus efficace, par exemple par catégories de vidéos ou par périodes. Cela accélèrerait les requêtes en nous permettant de ne rechercher que les partitions pertinentes.

Une autre astuce d'optimisation consiste à utiliser des mécanismes de mise en cache pour les incorporations ou les résultats de recherche fréquemment consultés. Cela permettrait d'améliorer considérablement les temps de réponse pour les requêtes les plus fréquentes. N'oubliez pas d'affiner les paramètres d'indexation de Milvus en fonction de votre ensemble de données et de vos modèles de requêtes spécifiques - un petit ajustement peut contribuer grandement à améliorer les performances de recherche.

Fonctionnalités avancées

Ajoutons maintenant quelques fonctionnalités intéressantes pour que notre application se démarque ! Nous pourrions mettre en œuvre une recherche hybride qui combine des requêtes textuelles et vidéo. En fait, l'API Embed de Twelve Labs peut également générer des incrustations de texte pour vos requêtes textuelles. Imaginez que vous permettiez aux utilisateurs de saisir à la fois une description textuelle et un exemple de clip vidéo - nous générerions des embeddings pour les deux et effectuerions une recherche pondérée dans Milvus. Nous obtiendrions ainsi des résultats extrêmement précis.

Un autre ajout génial serait la recherche temporelle dans les vidéos. Nous pourrions diviser les longues vidéos en segments plus petits, chacun avec sa propre intégration. Ainsi, les utilisateurs pourraient trouver des moments précis dans les vidéos, et pas seulement des clips entiers. Et pourquoi ne pas ajouter un peu d'analyse vidéo de base ? Nous pourrions utiliser les embeddings pour regrouper des segments vidéo similaires, détecter des tendances ou même identifier des valeurs aberrantes dans de grandes collections de vidéos.

Gestion des erreurs et journalisation

Soyons réalistes, les choses peuvent mal tourner, et lorsque c'est le cas, nous devons être prêts. La mise en œuvre d'une gestion robuste des erreurs est cruciale. Nous devons envelopper nos appels d'API et nos opérations de base de données dans des blocs try-except, en fournissant des messages d'erreur informatifs aux utilisateurs en cas d'échec. Pour les problèmes liés au réseau, l'implémentation de tentatives avec un backoff exponentiel peut aider à gérer les problèmes temporaires de manière gracieuse.

Quant à la journalisation, c'est notre meilleur ami pour le débogage et la surveillance. Nous devrions utiliser le module de journalisation de Python pour suivre les événements importants, les erreurs et les mesures de performance tout au long de notre application. Mettons en place différents niveaux de journalisation - DEBUG pour le développement, INFO pour le fonctionnement général et ERROR pour les problèmes critiques. N'oubliez pas de mettre en place une rotation des journaux pour gérer la taille des fichiers. Grâce à la mise en place d'une journalisation appropriée, nous serons en mesure d'identifier et de résoudre rapidement les problèmes, ce qui garantira le bon fonctionnement de notre application de recherche vidéo, même lorsqu'elle sera mise à l'échelle.

Conclusion

Nous vous félicitons ! Vous avez maintenant construit une application de recherche vidéo sémantique puissante à l'aide de l'API Embed de Twelve Labs et de Milvus. Cette intégration vous permet de traiter, stocker et récupérer du contenu vidéo avec une précision et une efficacité sans précédent. En exploitant les incorporations multimodales, vous avez créé un système qui comprend les nuances des données vidéo, ce qui ouvre des possibilités passionnantes pour la découverte de contenu, les systèmes de recommandation et l'analyse vidéo avancée.

Alors que vous continuez à développer et à affiner votre application, n'oubliez pas que la combinaison de la génération d'intégration avancée de Twelve Labs et du stockage vectoriel évolutif de Milvus constitue une base solide pour relever des défis encore plus complexes en matière de compréhension vidéo. Nous vous encourageons à expérimenter les fonctionnalités avancées présentées et à repousser les limites de ce qui est possible en matière de recherche et d'analyse vidéo.