Partage via

Hôtes de capacité

Note

La mise à jour des hôtes de capacité n’est pas prise en charge. Pour modifier un hôte de capacité, vous devez supprimer l’hôte existant et le recréer avec la nouvelle configuration.

Les hôtes de fonctionnalité sont des sous-ressources que vous configurez à la fois sur le compte Microsoft Foundry et dans les domaines du projet Foundry. Ils indiquent au service Foundry Agent où stocker et traiter les données de l’agent, notamment :

  • Historique des conversations (threads)
  • Chargements de fichiers
  • Magasins de vecteurs

Prerequisites

Pourquoi utiliser des hôtes de capacité ?

Les hôtes de capacité vous permettent d'apporter vos propres ressources Azure plutôt que d’utiliser les ressources de plateforme gérées par Microsoft par défaut. Cela vous donne les avantages suivants :

  • Souveraineté des données : conservez toutes les données de l’agent dans votre abonnement Azure.
  • Contrôle de la sécurité - Utilisez vos propres comptes de stockage, bases de données et services de recherche.
  • Conformité : répondez aux exigences réglementaires ou organisationnelles spécifiques.

Comment fonctionnent les hôtes de capacité?

La création d’hôtes de capacité n’est pas nécessaire. Si vous souhaitez que les agents utilisent vos propres ressources Azure, créez des hôtes de fonctionnalités à la fois au niveau du compte et du projet.

Comportement par défaut (ressources gérées par Microsoft)

Si vous ne créez pas d'hôtes de fonctionnalité, le service Agent utilise automatiquement les ressources Azure gérées par Microsoft pour :

  • Thread storage (historique des conversations, définitions d’agent)
  • Stockage de fichiers (documents téléchargés)
  • Recherche vectorielle (incorporations et récupération)

Apporter vos propres ressources

Lorsque vous créez des hôtes de capacité à la fois au niveau du compte et des projets, vos ressources Azure stockent et traitent les données de l’agent. Il s’agit de la configuration de l’agent standard. Pour la configuration de l’agent standard sécurisé par le réseau, déployez toutes les ressources associées dans la même région que votre virtual network (VNet). Pour obtenir des conseils, consultez Créer un environnement sécurisé par le réseau avec une identité managée par l’utilisateur.

Pour en savoir plus sur la configuration de l’agent standard, consultez La préparation intégrée de l’entreprise avec la configuration de l’agent standard.

Note

Nous vous recommandons d’utiliser des comptes et projets Foundry distincts pour la configuration de l’agent standard et la configuration de l’agent de base. Évitez de mélanger les types d’installation dans le même compte Foundry.

Hiérarchie de configuration

Les hôtes de capacité suivent une hiérarchie où des configurations plus spécifiques remplacent des configurations plus larges :

  1. Service par défaut (recherche gérée par Microsoft et storage) : utilisé lorsqu’aucun hôte de fonctionnalité n’est configuré.
  2. Hôte de capacité au niveau du compte : fournit des valeurs par défaut partagées pour tous les projets sous le compte.
  3. Hôte de capacités au niveau du projet – substitution des paramètres par défaut définis au niveau du compte et du service pour ce projet particulier.

Comprendre les contraintes de l’hôte de capacité

Lors de la création d’hôtes de capacité, tenez compte de ces contraintes importantes pour éviter les conflits :

  • Un seul hôte de fonctionnalité par étendue : chaque compte et chaque projet ne peuvent avoir qu’un seul hôte de capacité actif. Si vous tentez de créer un second hôte de capacités portant un nom différent au sein de la même étendue, une erreur de conflit 409 se produit.

  • Vous ne pouvez pas mettre à jour les configurations : si vous avez besoin de modifier la configuration, supprimez l’hôte de fonctionnalité existant et recréez-le.

Créer des connexions pour les hôtes de capacité

Les hôtes de capacités référencent les noms de connexion que vous créez dans votre compte Foundry et votre projet. Avant de configurer un hôte de capacité de projet pour la configuration standard de l’agent, créez des connexions pour les ressources qui stockent les données d’agent :

  • Thread storage : connexion Azure Cosmos DB
  • File storage : connexion Azure Storage
  • Magasin de vecteurs : connexion Recherche Azure AI

Si vous souhaitez utiliser des déploiements de modèles à partir de votre propre ressource OpenAI Azure, créez également une connexion OpenAI Azure.

Pour ajouter des connexions dans le portail Foundry, consultez Ajouter une nouvelle connexion à votre projet.

Configurer des hôtes de capacité

Actuellement, vous gérez les hôtes de capacité à l’aide de l’API REST. La prise en charge par le SDK de la gestion des hôtes de capacités n’est pas disponible.

Propriétés requises (hôte des capacités du projet)

Pour utiliser vos propres ressources pour les données de l’agent (configuration de l’agent standard), configurez l’hôte de capacité du projet avec les propriétés suivantes :

Propriété Objectif Ressource Azure requise Exemple de nom de connexion
threadStorageConnections Stocke les définitions d’agent, l’historique des conversations et les threads de conversation Azure Cosmos DB "my-cosmosdb-connection"
vectorStoreConnections Gère le stockage vectoriel pour la récupération et la recherche Azure AI Search "my-ai-search-connection"
storageConnections Gère les chargements de fichiers et les blob storage compte Azure Storage "my-storage-connection"

Propriété facultative

Propriété Objectif Ressource Azure requise Quand utiliser
aiServicesConnections Utiliser vos propres déploiements de modèle Azure OpenAI Lorsque vous souhaitez utiliser des modèles de votre ressource Azure OpenAI existante au lieu de ceux intégrés au niveau du compte.

Hôte de capacité de compte

Utilisez un hôte de capacité de compte pour activer le service d'agent et éventuellement définir les valeurs par défaut dont les projets peuvent hériter.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents"
  }
}

Référence : API REST de gestion des comptes Foundry

hôte de capacité du projet

Cette configuration remplace les paramètres par défaut du service et tous les paramètres au niveau du compte. Tous les agents de cette project utiliseront vos ressources spécifiées :

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["my-cosmos-db-connection"],
    "vectorStoreConnections": ["my-ai-search-connection"],
    "storageConnections": ["my-storage-account-connection"],
    "aiServicesConnections": ["my-azure-openai-connection"]
  }
}

Référence : Hôtes de capacité de projet - Créer ou mettre à jour

Facultatif : valeurs par défaut au niveau du compte avec remplacements de projet

Définissez les valeurs par défaut partagées au niveau du compte qui s’appliquent à tous les projets :

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["shared-cosmosdb-connection"],
    "vectorStoreConnections": ["shared-ai-search-connection"],
    "storageConnections": ["shared-storage-connection"]
  }
}

Note

Tous les projets Foundry héritent de ces paramètres. Remplacez ensuite les paramètres spécifiques au niveau project en fonction des besoins.

Vérifier votre configuration

Procédez comme suit pour vérifier que les hôtes de capacité sont configurés correctement :

  1. Obtenez l'hôte de capacité de compte et confirmez son existence.

    GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01

  2. Obtenez l’hôte de capacité du projet et confirmez qu’il fait référence aux noms de connexion attendus.

    GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01

  3. Testez votre configuration en créant un agent de test et en exécutant une conversation. Confirmez que :

    • Les threads de conversation apparaissent dans votre Azure Cosmos DB
    • Les fichiers chargés apparaissent dans votre compte Azure Storage
    • Les données vectorielles s’affichent dans votre index de Azure AI Search

  4. Si vous mettez à jour les connexions ou souhaitez modifier l’emplacement où les données sont stockées, supprimez et recréez les hôtes de capacité avec la configuration mise à jour.

Supprimer des hôtes de capacité

Avertissement

La suppression d’un hôte de capacité affecte tous les agents qui en dépendent. Veillez à tenir compte de l’impact avant de continuer. Par exemple, si vous supprimez l’hôte de capacité de projet et de compte, les agents de votre projet n’ont plus accès aux fichiers, threads et magasins vectoriels auxquels ils avaient précédemment accès.

Supprimer un hôte de capacité au niveau du compte

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

Supprimer un hôte de capacité de niveau projet

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

Résolution des problèmes

Si vous rencontrez des problèmes lors de la création d’hôtes de capacité, cette section fournit des solutions aux problèmes et erreurs les plus courants.

Erreurs de conflit HTTP 409

Problème : plusieurs hôtes de capacité par étendue

Symptômes : vous recevez une erreur de conflit 409 lorsque vous essayez de créer un hôte de capacité, même si vous pensez que l’étendue est vide.

Message d’erreur :

{
  "error": {
    "code": "Conflict",
    "message": "There is an existing Capability Host with name: existing-host, provisioning state: Succeeded for workspace: /subscriptions/.../workspaces/my-workspace, cannot create a new Capability Host with name: new-host for the same ClientId."
  }
}

Root cause : Chaque compte et chaque projet ne peuvent avoir qu’un seul hôte de fonctionnalité actif. Vous essayez de créer un hôte de capacité avec un nom différent alors qu’il en existe déjà un dans la même étendue.

Solution:

  1. Vérifier les hôtes de capacité existants : interrogez l’étendue pour voir ce qui existe déjà.
  2. Utiliser un nom cohérent : vérifiez que vous utilisez le même nom dans toutes les demandes pour la même étendue.
  3. Passer en revue vos besoins : déterminez si l’hôte de capacité existant répond à vos besoins.

Étapes de validation : Utilisez les requêtes GET dans Vérifier votre configuration pour vérifier si un hôte de fonctionnalité existe déjà dans l’étendue cible.

Problème : opérations simultanées en cours

Symptômes : vous recevez une erreur de conflit 409 indiquant qu’une autre opération est en cours d’exécution.

Message d’erreur :

{
  "error": {
    "code": "Conflict", 
    "message": "Create: Capability Host my-host is currently in non creating, retry after its complete: /subscriptions/.../workspaces/my-workspace"
  }
}

Cause : vous essayez de créer un hôte de capacité alors qu’une autre opération (mise à jour, suppression, modification) est en cours dans la même étendue.

Solution:

  1. Attendre la fin de l’opération actuelle : vérifiez l’état des opérations en cours.
  2. Surveiller la progression de l’opération : utilisez l’API d’opérations pour suivre la progression.
  3. Implémenter une logique de réessai - Utiliser un retrait exponentiel en cas de conflits temporaires

Surveillance des opérations :

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01

Meilleures pratiques pour la prévention des conflits

1. Validation de la pré-demande

Vérifiez toujours l’état actuel avant d’apporter des modifications :

  • Interroger des hôtes de capacité existants dans l’étendue cible
  • Rechercher les opérations en cours
  • Comprendre la configuration actuelle

2. Implémenter une logique de nouvelle tentative avec backoff exponentiel

try 
{
    var response = await CreateCapabilityHostAsync(request);
    return response;
}
catch (HttpRequestException ex) when (ex.Message.Contains("409"))
{
    if (ex.Message.Contains("existing Capability Host with name"))
    {
        // Handle name conflict - check if existing resource is acceptable
        var existing = await GetExistingCapabilityHostAsync();
        if (IsAcceptable(existing))
        {
            return existing; // Use existing resource
        }
        else
        {
            throw new InvalidOperationException("Scope already has a capability host with different name");
        }
    }
    else if (ex.Message.Contains("currently in non creating"))
    {
        // Handle concurrent operation - implement retry with backoff
        await Task.Delay(TimeSpan.FromSeconds(30));
        return await CreateCapabilityHostAsync(request); // Retry once
    }
}

3. Comprendre le comportement idempotent

Le système prend en charge les demandes de création idempotentes :

  • Même nom + même configuration → renvoie la ressource existante (200 OK)
  • Même nom + autre configuration → renvoie Requête incorrecte 400
  • Nom différent → renvoie Conflit 409

4. Flux de travail de modification de configuration

Étant donné que les mises à jour ne sont pas prises en charge, suivez cette séquence pour les modifications de configuration :

  1. Supprimer l’hôte de capacité existant
  2. Attendre la fin de la suppression
  3. Créer un hôte de fonctionnalité avec la configuration souhaitée

Scénarios courants

  • Développement et test : utilisez des ressources gérées par Microsoft. Aucune configuration d’hôte de capacité n’est nécessaire.
  • Production avec exigences de conformité : Créez des hôtes de capacité avec votre propre Azure Cosmos DB, Storage et recherche Azure AI.
  • Les ressources partagés entre les projets : configurez les valeurs par défaut au niveau du compte, puis remplacez-les au niveau project en fonction des besoins.

Prochaines étapes

  • Last updated on