Share via

Mogelijkheidshosts

Opmerking

Het bijwerken van capability hosts wordt niet ondersteund. Als u een mogelijkheidshost wilt wijzigen, moet u de bestaande host verwijderen en opnieuw maken met de nieuwe configuratie.

Capaciteitsservers zijn subbronnen die u configureert in zowel het Microsoft Foundry-account als de scope van het Foundry-project. Ze vertellen Foundry Agent Service waar agentgegevens moeten worden opgeslagen en verwerkt, waaronder:

  • Gespreksgeschiedenis (gespreksdraden)
  • Bestandsuploads
  • Vector opslag

Vereiste voorwaarden

Waarom capaciteitshosts gebruiken?

Met functionaliteitshosts kunt u uw eigen Azure-bronnen gebruiken in plaats van de standaard door Microsoft beheerde platformmiddelen. Dit geeft u het volgende:

  • Data-soevereiniteit - Houd alle agentgegevens binnen uw Azure-abonnement.
  • Beveiligingsbeheer : gebruik uw eigen storage-accounts, -databases en -zoekservices.
  • Naleving : voldoen aan specifieke wettelijke of organisatievereisten.

Hoe werken capaciteitshosts?

Het maken van capability hosts is niet vereist. Als u wilt dat agents uw eigen Azure-resources gebruiken, maakt u capaciteitshosts voor zowel de account- als projectomvang.

Standaardgedrag (door Microsoft beheerde resources)

Als u geen eigenschap-hosts maakt, gebruikt Agent Service automatisch door Microsoft beheerde Azure-resources voor:

  • Thread storage (gespreksgeschiedenis, agentdefinities)
  • Bestandsopslag (geüploade documenten)
  • Vectorzoekopdrachten (insluiten en ophalen)

Breng-je-eigen-middelen

Wanneer u capaciteits-hosts maakt op zowel accountniveau als projectniveau, verwerken uw Azure-resources agentgegevens. Dit is de standaardinstelling van de agent. Implementeer alle gerelateerde resources in dezelfde regio als uw virtual network (VNet) voor het instellen van met het netwerk beveiligde standaardagent. Zie Een nieuwe door het netwerk beveiligde omgeving maken met door de gebruiker beheerde identiteit.

Zie Ingebouwde bedrijfsgereedheid met standaard agentinstallatie voor meer informatie over de standaard agentinstallatie.

Opmerking

U wordt aangeraden afzonderlijke Foundry-accounts en -projecten te gebruiken voor het instellen van de standaardagent en het instellen van de basisagent. Vermijd het combineren van installatietypen binnen hetzelfde Foundry-account.

Configuratiehiërarchie

Mogelijkheidshosts volgen een hiërarchie waarbij specifiekere configuraties bredere configuraties overschrijven:

  1. Service defaults (door Microsoft beheerde zoekopdrachten en opslag): wordt gebruikt wanneer er geen capaciteitshost is geconfigureerd.
  2. Mogelijkheidshost op accountniveau : biedt gedeelde standaardinstellingen voor alle projecten onder het account.
  3. Project-level capability host - overschrijft standaardinstellingen voor accountniveau en service voor het specifieke project.

Inzicht in beperkingen voor capaciteitshosts

Wanneer u capaciteitshosts maakt, moet u rekening houden met deze belangrijke beperkingen om conflicten te voorkomen:

  • Eén capability host per scope: elk account en elk project kan slechts één actieve capaciteitshost hebben. Als u probeert een tweede capabiliteitshost met een andere naam in hetzelfde bereik aan te maken, krijgt u een 409-conflict.

  • U kunt configuraties niet bijwerken: als u de configuratie wilt wijzigen, verwijdert u de bestaande mogelijkheidshost en maakt u deze opnieuw.

Verbindingen maken voor capaciteitshosts

Capaciteitshosts verwijzen naar verbindingsnamen die u maakt in uw Foundry-account en project. Voordat u een project host voor mogelijkheden configureert voor de installatie van een standaardagent, maakt u verbindingen met de middelen die agentgegevens opslaan.

  • Thread storage: Azure Cosmos DB-verbinding
  • Bestandsopslag: Azure Storage-verbinding
  • Vector store: Azure AI Search connection

Als u modelimplementaties wilt gebruiken vanuit uw eigen Azure OpenAI-resource, maakt u ook een Azure OpenAI-verbinding.

Zie Toevoegen van een nieuwe verbinding met uw project om verbindingen toe te voegen in de Foundry-portal.

Mogelijkheidshosts configureren

Op dit moment beheert u capaciteitshosts via de REST API. SDK-ondersteuning voor beheer van functionaliteitshosts is niet beschikbaar.

Vereiste eigenschappen (project capaciteitenhost)

Als u uw eigen resources wilt gebruiken voor agentgegevens (standaardagentinstallatie), configureert u de project mogelijkheidshost met de volgende eigenschappen:

Vastgoed Doel Vereiste Azure-resource Voorbeeld van verbindingsnaam
threadStorageConnections Slaat agentdefinities, gespreksgeschiedenis en chatthreads op Azure Cosmos DB "my-cosmosdb-connection"
vectorStoreConnections Beheert vectoropslag voor opvragen en zoeken Azure AI Search "my-ai-search-connection"
storageConnections Beheert bestanden uploaden en blob-opslag Azure Storage-account "my-storage-connection"

Optionele eigenschap

Vastgoed Doel Vereiste Azure-resource Wanneer te gebruiken
aiServicesConnections Uw eigen modelimplementaties gebruiken Azure OpenAI Wanneer u modellen van uw bestaande Azure OpenAI-resource wilt gebruiken in plaats van de ingebouwde accountniveau modellen.

Host van accountmogelijkheid

Gebruik een accountondersteuningshost om agentservice in te schakelen en (optioneel) standaardwaarden te definiëren die projecten kunnen overnemen.

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

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

Naslaginformatie: REST API voor Foundry-accountbeheer

Project capaciteit host

Deze configuratie overschrijft de standaardinstellingen van de service en eventuele instellingen op accountniveau. Alle agents in deze project gebruiken de opgegeven resources:

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"]
  }
}

Referentie: Project Capability Hosts - Maken of bijwerken

Optioneel: standaardinstellingen op het accountniveau met projectoverschrijvingen

Stel gedeelde standaardinstellingen in op accountniveau die van toepassing zijn op alle projecten:

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"]
  }
}

Opmerking

Alle Foundry-projecten nemen deze instellingen over. Overschrijf vervolgens zo nodig specifieke instellingen op project niveau.

Uw configuratie controleren

Gebruik deze stappen om te controleren of de capaciteitshosts correct zijn geconfigureerd:

  1. Haal de host van de accountmogelijkheid op en bevestig dat deze bestaat.

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

  2. Haal de projectcapaciteitsserver op en bevestig dat deze verwijst naar de verwachte verbindingsnamen.

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

  3. Test uw configuratie door een testagent te maken en een gesprek uit te voeren. Controleer of:

    • Gespreksthreads worden weergegeven in uw Azure Cosmos DB
    • Geüploade bestanden worden weergegeven in uw Azure Storage-account
    • Vectorgegevens worden weergegeven in uw Azure AI Search-index

  4. Als u verbindingen bijwerkt of wilt aanpassen waar gegevens worden opgeslagen, verwijder dan de capaciteitshosts en maak ze opnieuw met de bijgewerkte configuratie.

Mogelijkheidshosts verwijderen

Waarschuwing

Het verwijderen van een capaciteitshost heeft invloed op alle agenten die hiervan afhankelijk zijn. Zorg ervoor dat u de impact begrijpt voordat u doorgaat. Als u bijvoorbeeld de host van het project en de accountfunctionaliteit verwijdert, hebben agents in uw project niet langer toegang tot de bestanden, discussielijnen en vectoropslagplaatsen.

Een capability host op accountniveau verwijderen

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

Een capaciteitshost op projectniveau verwijderen

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

Probleemoplossingsproces

Als u problemen ondervindt bij het maken van capaciteitshosts, biedt deze sectie oplossingen voor de meest voorkomende problemen en fouten.

HTTP 409 conflictfouten

Probleem: Hosts met meerdere mogelijkheden per bereik

Symptomen: U ontvangt een 409 Conflict-fout bij het maken van een functionaliteitshost, ook al denkt u dat het bereik leeg is.

Foutbericht:

{
  "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."
  }
}

Oorzaak: Elk account en elk project kan slechts één actieve capabiliteitshost hebben. U probeert een 'capability host' met een andere naam te maken terwijl er al een aanwezig is binnen hetzelfde bereik.

Solution:

  1. Bestaande capaciteitshosts controleren : voer een query uit op het bereik om te zien wat er al bestaat
  2. Gebruik consistente naamgeving : zorg ervoor dat u dezelfde naam gebruikt voor alle aanvragen voor hetzelfde bereik
  3. Controleer uw vereisten - Bepalen of de bestaande capaciteitshost aan uw behoeften voldoet

Validatiestappen: Gebruik de GET-aanvragen in De configuratie controleren om te controleren of er al een capaciteitshost bestaat binnen het doelbereik.

Probleem: Gelijktijdige bewerkingen worden uitgevoerd

Symptomen: Er wordt een 409-conflictfout weergegeven die aangeeft dat er momenteel een andere bewerking wordt uitgevoerd.

Foutbericht:

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

Oorzaak: U probeert een functiehost te maken terwijl een andere bewerking (bijwerken, verwijderen, wijzigen) in dezelfde context wordt uitgevoerd.

Solution:

  1. Wacht tot de huidige bewerking is voltooid - Controleer de status van lopende bewerkingen
  2. Voortgang van de bewerking bewaken - De bewerkings-API gebruiken om de voltooiing bij te houden
  3. Logica voor opnieuw proberen implementeren - Exponentieel uitstel gebruiken voor tijdelijke conflicten

Bewaking van bewerkingen:

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

Aanbevolen procedures voor conflictpreventie

1. Validatie vooraf aanvragen

Controleer altijd de huidige status voordat u wijzigingen aanbrengt:

  • Query's uitvoeren op bestaande capaciteitshosts in het doelbereik
  • Controleren op enige lopende bewerkingen
  • Inzicht in de huidige configuratie

2. Uitvoeren van opnieuw probeerlogica met exponentiële vertraging

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. Inzicht in idempotent gedrag

Het systeem ondersteunt idempotent create-aanvragen:

  • Dezelfde naam + dezelfde configuratie → retourneert bestaande resource (200 OK)
  • Dezelfde naam + andere configuratie → retourneert 400 Ongeldige aanvraag
  • Andere naam → retourneert 409 Conflict

4. Werkstroom voor configuratiewijziging

Aangezien updates niet worden ondersteund, volgt u deze volgorde voor configuratiewijzigingen:

  1. Bestaande capability host verwijderen
  2. Wachten tot het verwijderen is voltooid
  3. Maak een nieuwe capability-host met de gewenste configuratie

Algemene scenario's

  • Ontwikkeling en testen: gebruik door Microsoft beheerde resources. Er is geen mogelijkheid voor hostconfiguratie nodig.
  • Productie met nalevingsvereisten: Creëer hosts voor mogelijkheden met uw eigen Azure Cosmos DB, Storage en AI Search.
  • Gedeelde bronnen tussen projecten: Configureer standaardinstellingen op accountniveau en overschrijf ze indien nodig op projectniveau.

Volgende stappen

  • Last updated on