Udostępnij przez

Hosty zdolności

Uwaga / Notatka

Aktualizowanie hostów możliwości nie jest obsługiwane. Aby zmodyfikować host funkcji, musisz usunąć istniejący i ponownie utworzyć go przy użyciu nowej konfiguracji.

Hosty funkcjonalności to zasoby podrzędne konfigurowane zarówno na koncie Microsoft Foundry, jak i w zakresach projektów Foundry. Informują one usługę agenta Foundry, gdzie mają być przechowywane i przetwarzane dane agenta, w tym:

  • Historia konwersacji (wątki)
  • Przekazywanie plików
  • Magazyny wektorów

Wymagania wstępne

Dlaczego warto używać hostów funkcjonalności?

Hosty możliwości umożliwiają przenoszenie własnych zasobów platformy Azure zamiast używania domyślnych zasobów platformy zarządzanej przez firmę Microsoft. Zapewnia to:

  • Niezależność danych — zachowaj wszystkie dane agenta w ramach subskrypcji platformy Azure.
  • Kontrola zabezpieczeń — użyj własnych kont magazynu, baz danych i usług wyszukiwania.
  • Zgodność — spełnia określone wymagania prawne lub organizacyjne.

Jak działają hosty funkcji?

Tworzenie hostów dla możliwości nie jest wymagane. Jeśli chcesz, aby agenci używali własnych zasobów platformy Azure, utwórz hosty możliwości zarówno w zakresie konta, jak i projektu.

Domyślne zachowanie (zasoby zarządzane przez firmę Microsoft)

Jeśli nie utworzysz hostów funkcji, usługa agenta automatycznie używa zasobów Azure zarządzanych przez Microsoft, aby:

  • Przechowywanie wątków (historia rozmów, definicje agentów)
  • Przechowywanie plików (przesłane dokumenty)
  • Wyszukiwanie wektorowe (osadzanie i pobieranie)

Przynieś własne zasoby

Podczas tworzenia hostów możliwości na poziomie konta i projektu zasoby platformy Azure przechowują i przetwarzają dane agenta. Jest to standardowa konfiguracja agenta. W przypadku konfiguracji agenta standardowego zabezpieczonego siecią należy wdrożyć wszystkie powiązane zasoby w tym samym regionie co sieć wirtualna. Aby uzyskać wskazówki, zobacz Tworzenie nowego środowiska zabezpieczonego siecią przy użyciu tożsamości zarządzanej przez użytkownika.

Aby dowiedzieć się więcej na temat standardowej konfiguracji agenta, zobacz Wbudowana gotowość przedsiębiorstwa ze standardową konfiguracją agenta.

Uwaga / Notatka

Zalecamy używanie oddzielnych kont i projektów foundry na potrzeby standardowej konfiguracji agenta i podstawowej konfiguracji agenta. Unikaj mieszania typów konfiguracji w ramach tego samego konta Foundry.

Hierarchia konfiguracji

Hosty funkcji przestrzegają hierarchii, w której bardziej szczegółowe konfiguracje mają pierwszeństwo przed szerszymi:

  1. Wartości domyślne usługi (wyszukiwanie i magazyn zarządzany przez firmę Microsoft) — używane, gdy nie skonfigurowano hosta funkcji.
  2. Możliwości hosta na poziomie konta — zapewnia wspólne wartości domyślne dla wszystkich projektów w ramach konta.
  3. Host możliwości na poziomie projektu — zastępuje wartości domyślne na poziomie konta i usługi dla tego konkretnego projektu.

Zrozumienie ograniczeń hosta możliwości

Podczas tworzenia hostów możliwości należy pamiętać o tych ważnych ograniczeniach, aby uniknąć konfliktów:

  • Jeden host funkcji na zakres: każde konto i każdy projekt może mieć tylko jeden aktywny host funkcji. Jeśli spróbujesz utworzyć drugi host możliwości o innej nazwie w tym samym zakresie, wystąpi konflikt 409.

  • Nie można zaktualizować konfiguracji: jeśli musisz zmienić konfigurację, usuń istniejący host możliwości i utwórz go ponownie.

Utwórz połączenia dla hostów funkcji

Hosty funkcjonalności zawierają nazwy połączeń, które tworzysz na koncie i w projekcie Foundry. Przed skonfigurowaniem hosta możliwości projektu dla standardowej konfiguracji agenta utwórz połączenia dla zasobów, które przechowują dane agenta:

  • Przechowywanie wątków: połączenie z usługą Azure Cosmos DB
  • Przechowywanie plików: połączenie z Azure Storage
  • Magazyn wektorów: połączenie z Azure AI Search

Jeśli chcesz używać wdrożeń modelu z własnego zasobu usługi Azure OpenAI, również utwórz połączenie Azure OpenAI.

Aby dodać połączenia w portalu Foundry, zobacz Dodawanie nowego połączenia do projektu.

Konfigurowanie hostów możliwości

Obecnie zarządzasz hostami funkcji za pomocą API REST. Obsługa zestawu SDK na potrzeby zarządzania hostami możliwości nie jest dostępna.

Wymagane właściwości (host możliwości projektu)

Aby użyć własnych zasobów na potrzeby danych agenta (konfiguracja agenta standardowego), skonfiguruj hosta możliwości projektu przy użyciu następujących właściwości:

Majątek Przeznaczenie Wymagany zasób platformy Azure Przykładowa nazwa połączenia
threadStorageConnections Przechowuje definicje agentów, historię konwersacji i wątki rozmów Azure Cosmos DB "my-cosmosdb-connection"
vectorStoreConnections Obsługuje magazyn wektorów do pobierania i wyszukiwania Wyszukiwanie AI platformy Azure "my-ai-search-connection"
storageConnections Zarządza przekazywaniem plików i przechowywaniem blobów Konto magazynu platformy Azure "my-storage-connection"

Właściwość opcjonalna

Majątek Przeznaczenie Wymagany zasób platformy Azure Kiedy należy używać
aiServicesConnections Używaj własnych wdrożeń modelu Azure OpenAI Jeśli chcesz używać modeli z istniejącego zasobu usługi Azure OpenAI, zamiast modeli wbudowanych na poziomie konta.

Gospodarz funkcji konta

Aby włączyć usługę agenta, użyj hosta obsługi konta i (opcjonalnie) zdefiniuj wartości domyślne, które mogą dziedziczyć projekty.

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

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

Dokumentacja: interfejs API REST zarządzania kontem Foundry

Host możliwości projektu

Ta konfiguracja zastępuje ustawienia domyślne usługi i ustawienia na poziomie konta. Wszyscy agenci w tym projekcie będą używać określonych zasobów:

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

Dokumentacja: Hosty możliwości projektu — tworzenie lub aktualizowanie

Opcjonalnie: wartości domyślne na poziomie konta z nadpisaniami projektu

Ustaw wartości domyślne udostępnione na poziomie konta, które mają zastosowanie do wszystkich projektów:

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

Uwaga / Notatka

Wszystkie projekty Foundry będą dziedziczyć te ustawienia. Następnie przesłoń określone ustawienia na poziomie projektu zgodnie z potrzebami.

Weryfikowanie konfiguracji

Wykonaj następujące kroki, aby upewnić się, że hosty funkcji są poprawnie skonfigurowane:

  1. Pobierz hosta możliwości konta i upewnij się, że istnieje.

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

  2. Pobierz hosta możliwości projektu i potwierdź, że odwołuje się do oczekiwanych nazw połączeń.

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

  3. Przetestuj konfigurację, tworząc agenta testowego i uruchamiając konwersację. Potwierdź, że:

    • Wątki konwersacji są wyświetlane w usłudze Azure Cosmos DB
    • Przekazane pliki są wyświetlane na koncie usługi Azure Storage
    • Dane wektorowe są wyświetlane w indeksie usługi Azure AI Search

  4. Jeśli zaktualizujesz połączenia lub chcesz zmienić miejsce przechowywania danych, usuń, a następnie ponownie utwórz hosty funkcji za pomocą zaktualizowanej konfiguracji.

Usuwanie hostów możliwości

Ostrzeżenie

Usunięcie hosta możliwości będzie miało wpływ na wszystkich agentów, którzy od niego zależą. Przed kontynuowaniem upewnij się, że rozumiesz wpływ. Jeśli na przykład usuniesz hosta możliwości dla projektu i konta, agenci w twoim projekcie nie będą już mieli dostępu do plików, zasobów wątków i wektorów, do których wcześniej mieli dostęp.

Usuwanie hosta możliwości na poziomie konta

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

Usuń hosta funkcjonalności na poziomie projektu

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

Rozwiązywanie problemów

Jeśli występują problemy podczas tworzenia hostów możliwości, ta sekcja zawiera rozwiązania najczęstszych problemów i błędów.

Błędy HTTP 409 Konflikt

Problem: Wiele hostów na każdy zakres

Objawy: Podczas próby utworzenia hosta funkcji występuje błąd 409 Conflict, mimo że uważasz, że zakres jest pusty.

Komunikat o błędzie:

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

Przyczyna: Każde konto i każdy projekt mogą mieć tylko jednego aktywnego hosta funkcji. Próbujesz utworzyć host funkcji o innej nazwie, gdy jeden już istnieje w tym samym zakresie.

Rozwiązanie:

  1. Sprawdź istniejące hosty funkcjonalności — Wykonaj zapytanie zakresu, aby zobaczyć, co już istnieje
  2. Użyj spójnego nazewnictwa — upewnij się, że używasz tej samej nazwy we wszystkich żądaniach dla tego samego zakresu
  3. Przejrzyj wymagania — ustal, czy istniejący host funkcjonalności spełnia Twoje potrzeby

Kroki weryfikacji: Użyj żądań GET w sekcji Weryfikowanie konfiguracji, aby potwierdzić, czy host funkcjonalności już istnieje w docelowym zakresie.

Problem: Współbieżne operacje w toku

Objawy: Zostanie wyświetlony błąd 409 Konflikt wskazujący, że inna operacja jest obecnie uruchomiona.

Komunikat o błędzie:

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

Przyczyna: Próbujesz utworzyć hosta funkcji, podczas gdy inna operacja (aktualizacja, usuwanie, modyfikowanie) jest w toku w tym samym zakresie.

Rozwiązanie:

  1. Poczekaj na zakończenie bieżącej operacji — sprawdź stan bieżących operacji
  2. Monitorowanie postępu operacji — użyj interfejsu API operacji, aby śledzić ukończenie.
  3. Implementowanie logiki ponawiania prób — używanie wycofywania wykładniczego w przypadku konfliktów tymczasowych

Monitorowanie operacji:

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

Najlepsze rozwiązania dotyczące zapobiegania konfliktom

1. Sprawdzanie poprawności przed żądaniem

Przed wprowadzeniem zmian zawsze sprawdź bieżący stan:

  • Zapytaj istniejące hosty funkcji w docelowym zakresie
  • Sprawdź bieżące operacje
  • Omówienie bieżącej konfiguracji

2. Zaimplementuj logikę ponawiania przy użyciu wycofywania wykładniczego

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. Omówienie zachowania idempotentnego

System obsługuje idempotentne żądania tworzenia:

  • Ta sama nazwa i ta sama konfiguracja → Zwraca istniejący zasób (200 OK)
  • Ta sama nazwa i inna konfiguracja → Zwraca 400 nieprawidłowych żądań
  • Inna nazwa → zwraca 409 Konflikt

4. Przepływ zmiany konfiguracji

Ponieważ aktualizacje nie są obsługiwane, postępuj zgodnie z tą sekwencją zmian konfiguracji:

  1. Usuń istniejącego hosta funkcji
  2. Poczekaj na zakończenie usuwania
  3. Tworzenie nowego hosta możliwości z żądaną konfiguracją

Typowe scenariusze

  • Programowanie i testowanie: użyj zasobów zarządzanych przez firmę Microsoft. Nie jest wymagana żadna konfiguracja hosta funkcji.
  • Produkcja z wymaganiami dotyczącymi zgodności: tworzenie hostów funkcjonalności, korzystając z własnych usług Azure Cosmos DB, Storage i AI Search.
  • Współużytkowane zasoby między projektami: skonfiguruj wartości domyślne na poziomie konta, a następnie przesłoń je na poziomie projektu zgodnie z potrzebami.

Dalsze kroki

  • Last updated on