Szybki start: nawiązywanie połączenia z usługą Foundry IQ (Wyszukiwanie AI platformy Azure)

Uwaga / Notatka

Usługa Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie indeksowanie i interfejsy API zapytań wraz ze źródłem wiedzy wyższego poziomu i interfejsami API bazy wiedzy na potrzeby pobierania zarządzanego. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

W tym przewodniku Szybki start użyjesz kontroli dostępu opartej na rolach (RBAC) i Microsoft Entra ID, aby nawiązać bezkluczowe połączenie z usługą IQ (Wyszukiwanie AI platformy Azure). Następnie używasz języka Python w programie Visual Studio Code do interakcji z usługą.

Połączenia bez kluczy zapewniają zwiększone zabezpieczenia dzięki szczegółowym uprawnieniam i uwierzytelnianiu opartego na tożsamościach. Nie zalecamy kluczy interfejsu API zapisanych na stałe w kodzie, ale jeśli je preferujesz, zobacz Łączenie z usługą Foundry IQ przy użyciu kluczy.

Wymagania wstępne

Konfigurowanie dostępu opartego na rolach

W tej sekcji włączysz kontrolę dostępu opartą na rolach w usłudze IQ usługi Foundry (Wyszukiwanie AI platformy Azure) i przypiszesz niezbędne role do tworzenia, ładowania i wykonywania zapytań dotyczących obiektów wyszukiwania. Aby uzyskać więcej informacji na temat tych kroków, zobacz Nawiązywanie połączenia z usługą Foundry IQ przy użyciu ról.

Aby skonfigurować dostęp:

  1. Przejdź do usługi Foundry IQ w portalu Azure.

  2. W okienku po lewej stronie wybierz pozycję Klucze ustawień>.

  3. Wybierz Kontrola dostępu oparta na rolach (RBAC) lub Obie, jeśli potrzebujesz czasu na przeniesienie klientów do RBAC.

    Zrzut ekranu przedstawiający opcje kontroli dostępu w portalu Azure.

  4. W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).

  5. Wybierz Dodaj>Dodaj przypisanie roli.

    Zrzut ekranu przedstawiający menu rozwijane służące do dodawania przypisania roli w portalu Azure.

  6. Przypisz rolę Współautor usługi wyszukiwania do konta użytkownika lub tożsamości zarządzanej.

  7. Powtórz przypisanie roli dla współautora danych indeksu wyszukiwania.

Uzyskiwanie informacji o usłudze

W tej sekcji pobierzesz identyfikator subskrypcji i punkt końcowy usługi Foundry IQ. Jeśli masz tylko jedną subskrypcję, pomiń identyfikator subskrypcji i pobierz tylko punkt końcowy. Używasz tych wartości w pozostałych sekcjach tego przewodnika Szybki Start.

Aby uzyskać informacje o usłudze:

  1. Przejdź do usługi Foundry IQ w portalu Azure.

  2. W okienku po lewej stronie wybierz pozycję Przegląd.

  3. Zanotuj identyfikator subskrypcji i punkt końcowy.

    Zrzut ekranu przedstawiający identyfikator subskrypcji i punkt końcowy w portalu Azure.

Zaloguj się do Azure

Przed nawiązaniem połączenia z usługą IQ rozwiązania Foundry użyj Azure CLI, aby zalogować się do subskrypcji zawierającej usługę. Ten krok ustanawia tożsamość Microsoft Entra, której DefaultAzureCredential używa do uwierzytelniania żądań w następnej sekcji.

Aby się zalogować:

  1. W systemie lokalnym otwórz narzędzie wiersza polecenia.

  2. Sprawdź aktywną subskrypcję i dzierżawę w środowisku lokalnym.

    az account show
    
  3. Jeśli aktywna subskrypcja i dzierżawca nie są prawidłowe dla usługi Foundry IQ, uruchom następujące polecenia, aby zaktualizować ich wartości. Identyfikator subskrypcji można znaleźć na stronie Przegląd usługi Foundry IQ w portalu Azure. Aby znaleźć identyfikator dzierżawcy, wybierz nazwę subskrypcji na stronie Przegląd, a następnie znajdź wartość Grupa zarządzania nadrzędna.

     az account set --subscription <your-subscription-id>
    
     az login --tenant <your-tenant-id>
    

Połącz się z Foundry IQ

Uwaga / Notatka

W tej sekcji przedstawiono podstawowy wzorzec języka Python dla połączeń bez klucza. Aby uzyskać kompleksowe wskazówki, zobacz konkretny Szybki start lub samouczek, taki jak Szybki start: Agentowe pobieranie danych.

Notesy Python można używać w Visual Studio Code do wysyłania żądań do usługi Foundry IQ. W przypadku uwierzytelniania żądań użyj DefaultAzureCredential klasy z biblioteki tożsamości platformy Azure.

Aby nawiązać połączenie przy użyciu języka Python:

  1. W systemie lokalnym otwórz program Visual Studio Code.

  2. Utwórz plik .ipynb.

  3. Utwórz komórkę kodu, aby zainstalować biblioteki azure-identity i azure-search-documents .

    pip install azure-identity azure-search-documents
    
  4. Utwórz kolejną komórkę kodu, aby uwierzytelnić się i nawiązać połączenie z usługą IQ usługi Foundry.

    import json
    from azure.identity import DefaultAzureCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
    credential = DefaultAzureCredential()
    client = SearchIndexClient(endpoint = service_endpoint, credential = credential)
    
    # List existing indexes
    indexes = client.list_indexes()
    
    for index in indexes:
       index_dict = index.as_dict()
       print(json.dumps(index_dict, indent = 2))
    
  5. Ustaw service_endpoint na wartość uzyskaną w Pobieranie informacji o usłudze.

  6. Wybierz opcję Uruchom wszystko, aby uruchomić obie komórki kodu.

    Dane wyjściowe powinny zawierać listę istniejących indeksów (jeśli istnieją) w usłudze Foundry IQ, co wskazuje na pomyślne połączenie.

Rozwiązywanie problemów z błędami 401

Jeśli wystąpi błąd 401, wykonaj następujące kroki rozwiązywania problemów:

  • Ponownie skonfiguruj dostęp oparty na rolach. Usługa Foundry IQ musi mieć włączone opcje Kontrola dostępu oparta na rolach lub Obie. Zasady na poziomie subskrypcji lub grupy zasobów mogą zastąpić przypisania ról.

  • Ponownie zaloguj się do platformy Azure. Musisz zalogować się do subskrypcji, która zawiera usługę Foundry IQ.

  • Upewnij się, że zmienna punktu końcowego jest owinięta w cudzysłowy.

  • Jeśli wszystko inne nie powiedzie się, uruchom ponownie urządzenie, aby usunąć buforowane tokeny, a następnie powtórz kroki opisane w tym przewodniku Szybki start, zaczynając od pozycji Zaloguj się do platformy Azure.

W tym przewodniku Szybki start użyjesz kontroli dostępu opartej na rolach (RBAC) i Microsoft Entra ID, aby nawiązać bezkluczowe połączenie z usługą IQ (Wyszukiwanie AI platformy Azure). Następnie użyjesz interfejsu REST w programie Visual Studio Code do interakcji z usługą.

Połączenia bez kluczy zapewniają zwiększone zabezpieczenia dzięki szczegółowym uprawnieniam i uwierzytelnianiu opartego na tożsamościach. Nie zalecamy zakodowanych na stałe kluczy interfejsu API, ale jeśli je wolisz, zobacz Łączenie z usługą Foundry IQ przy użyciu kluczy.

Wymagania wstępne

Konfigurowanie dostępu opartego na rolach

W tej sekcji włączysz kontrolę dostępu opartą na rolach w usłudze IQ usługi Foundry (Wyszukiwanie AI platformy Azure) i przypiszesz niezbędne role do tworzenia, ładowania i wykonywania zapytań dotyczących obiektów wyszukiwania. Aby uzyskać więcej informacji na temat tych kroków, zobacz Nawiązywanie połączenia z usługą Foundry IQ przy użyciu ról.

Aby skonfigurować dostęp:

  1. Przejdź do usługi Foundry IQ w portalu Azure.

  2. W okienku po lewej stronie wybierz pozycję Klucze ustawień>.

  3. Wybierz Kontrola dostępu oparta na rolach (RBAC) lub Obie, jeśli potrzebujesz czasu na przeniesienie klientów do RBAC.

    Zrzut ekranu przedstawiający opcje kontroli dostępu w portalu Azure.

  4. W okienku po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami).

  5. Wybierz Dodaj>Dodaj przypisanie roli.

    Zrzut ekranu przedstawiający menu rozwijane służące do dodawania przypisania roli w portalu Azure.

  6. Przypisz rolę Współautor usługi wyszukiwania do konta użytkownika lub tożsamości zarządzanej.

  7. Powtórz przypisanie roli dla współautora danych indeksu wyszukiwania.

Uzyskiwanie informacji o usłudze

W tej sekcji pobierzesz identyfikator subskrypcji i punkt końcowy usługi IQ rozwiązania Foundry. Jeśli masz tylko jedną subskrypcję, pomiń identyfikator subskrypcji i pobierz tylko punkt końcowy. Używasz tych wartości w pozostałych sekcjach tego przewodnika Szybki Start.

Aby uzyskać informacje o usłudze:

  1. Przejdź do usługi Foundry IQ w portalu Azure.

  2. W okienku po lewej stronie wybierz pozycję Przegląd.

  3. Zanotuj identyfikator subskrypcji i punkt końcowy.

    Zrzut ekranu przedstawiający identyfikator subskrypcji i punkt końcowy w portalu Azure.

Zaloguj się do Azure

Przed nawiązaniem połączenia z usługą IQ rozwiązania Foundry użyj Azure CLI, aby zalogować się do subskrypcji zawierającej usługę.

Aby się zalogować:

  1. W systemie lokalnym otwórz narzędzie wiersza polecenia.

  2. Sprawdź aktywną subskrypcję i dzierżawę w środowisku lokalnym.

    az account show
    
  3. Jeśli aktywna subskrypcja i dzierżawca nie są prawidłowe dla usługi Foundry IQ, uruchom następujące polecenia, aby zaktualizować ich wartości. Identyfikator subskrypcji można znaleźć na stronie Przegląd usługi Foundry IQ w witrynie Azure Portal. Aby znaleźć identyfikator dzierżawcy, wybierz nazwę subskrypcji na stronie Przegląd, a następnie znajdź wartość Grupa zarządzania nadrzędna.

     az account set --subscription <your-subscription-id>
    
     az login --tenant <your-tenant-id>
    

Uzyskiwanie tokenu

Wywołania interfejsu API REST wymagają dołączenia tokenu Microsoft Entra ID. Ten token służy do uwierzytelniania żądań w następnej sekcji.

Aby uzyskać token:

  1. Za pomocą tego samego narzędzia wiersza polecenia wygeneruj token dostępu.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
    
  2. Zanotuj dane wyjściowe tokenu.

Połącz się z Foundry IQ

Uwaga / Notatka

W tej sekcji przedstawiono podstawowy wzorzec REST dla połączeń bez kluczy. Aby uzyskać kompleksowe wskazówki, zobacz konkretny Szybki start lub samouczek, taki jak Szybki start: Agentowe pobieranie danych.

Możesz użyć rozszerzenia REST Client w Visual Studio Code do wysyłania żądań do usługi Foundry IQ. W przypadku uwierzytelniania żądań dołącz Authorization nagłówek zawierający wcześniej wygenerowany token Microsoft Entra ID.

Aby nawiązać połączenie przy użyciu interfejsu REST:

  1. W systemie lokalnym otwórz program Visual Studio Code.

  2. Utwórz plik .rest lub .http.

  3. Wklej następujące zmienne i żądanie do pliku.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
    @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
    
    ### List existing indexes
    GET {{baseUrl}}/indexes?api-version=2026-10-01  HTTP/1.1
       Content-Type: application/json
       Authorization: Bearer {{token}}
    
  4. Ustaw @baseUrl na wartość uzyskaną w Pobieranie informacji o usłudze.

  5. Ustaw @token do wartości, którą uzyskałeś w Uzyskiwanie tokenu.

  6. W obszarze ### List existing indexeswybierz pozycję Wyślij żądanie.

    Powinno się otrzymać odpowiedź HTTP/1.1 200 OK, wskazującą na pomyślne połączenie z usługą Foundry IQ.

Rozwiązywanie problemów z błędami 401

Jeśli wystąpi błąd 401, wykonaj następujące kroki rozwiązywania problemów:

  • Ponownie skonfiguruj dostęp oparty na rolach. Usługa Foundry IQ musi mieć włączoną funkcję kontroli dostępu opartej na rolach lub Oba. Zasady na poziomie subskrypcji lub grupy zasobów mogą zastąpić przypisania ról.

  • Ponownie zaloguj się do platformy Azure. Musisz zalogować się do subskrypcji zawierającej usługę Foundry IQ.

  • Upewnij się, że zmienne punktu końcowego i tokenu nie mają otaczających cudzysłowów ani dodatkowych spacji.

  • Upewnij się, że token nie ma symbolu @ w nagłówku żądania. Jeśli na przykład zmienna to @token, odwołanie w żądaniu powinno mieć wartość {{token}}.

  • Jeśli wszystko inne nie powiedzie się, uruchom ponownie urządzenie, aby usunąć buforowane tokeny, a następnie powtórz kroki opisane w tym przewodniku Szybki start, zaczynając od pozycji Zaloguj się do platformy Azure.