Início Rápido: Conectar-se a um serviço de IQ do Foundry (Pesquisa de IA do Azure )

Observação

Foundry IQ (Pesquisa de IA do Azure) disponibiliza APIs de indexação e consulta diretas, além de APIs de nível mais elevado voltadas para fontes de conhecimento e bases de conhecimento, visando a recuperação gerenciada de informações. Use o portal do Azure, as APIs REST ou SDKs do Azure para configurar esses recursos ou conectar agentes a bases de conhecimento no portal Microsoft Foundry.

Neste início rápido, você usará o RBAC (controle de acesso baseado em função) e Microsoft Entra ID para estabelecer uma conexão sem chave com seu serviço de IQ do Foundry (Pesquisa de IA do Azure ). Em seguida, você usa o Python no Visual Studio Code para interagir com seu serviço.

Conexões sem chave fornecem segurança aprimorada por meio de permissões granulares e autenticação baseada em identidade. Não recomendamos chaves de API codificadas, mas, se preferir, consulte Conectar ao IQ do Foundry usando chaves.

Pré-requisitos

Configurar o acesso baseado em função

Nesta seção, você habilitará o RBAC em seu serviço de IQ de Pesquisa (Pesquisa de IA do Azure ) e atribuirá as funções necessárias para criar, carregar e consultar objetos de pesquisa. Para mais informações sobre essas etapas, consulte Conectar ao Foundry IQ usando funções.

Para configurar o acesso:

  1. Vá para o serviço de IQ do Foundry no portal do Azure.

  2. No painel esquerdo, selecione Chaves de Configurações>.

  3. Selecione Controle de Acesso Baseado em Funções (RBAC) ou Ambos se precisar de tempo para fazer a transição dos clientes para o Controle de Acesso Baseado em Funções (RBAC).

    Captura de tela das opções de controle de acesso no portal do Azure.

  4. No painel esquerdo, selecione Controle de acesso (IAM).

  5. Selecione Adicionar>Adicionar atribuição de função.

    Captura de tela do menu suspenso para adicionar uma atribuição de função no portal Azure.

  6. Atribua a função Colaborador do Serviço de Pesquisa à sua conta de usuário ou identidade gerenciada.

  7. Repita a atribuição de função para o Colaborador de Dados do Índice de Pesquisa.

Obter informações de serviço

Nesta seção, você recupera a ID da assinatura e o ponto de extremidade do serviço Foundry IQ. Se você tiver apenas uma assinatura, ignore a ID da assinatura e recupere apenas o ponto de extremidade. Você usará esses valores nas seções restantes deste início rápido.

Para obter suas informações de serviço:

  1. Vá para o serviço de IQ do Foundry no Azure portal.

  2. No painel esquerdo, selecione Visão geral.

  3. Anote o ID da assinatura e o endpoint.

    Captura de tela da ID da assinatura e do ponto de extremidade no portal do Azure.

Entrar no Azure

Antes de se conectar ao serviço de IQ do Foundry, use o CLI do Azure para entrar na assinatura que contém seu serviço. Esta etapa estabelece sua identidade do Microsoft Entra, que DefaultAzureCredential usa para autenticar solicitações na próxima seção.

Para entrar:

  1. No sistema local, abra uma ferramenta de linha de comando.

  2. Verifique a assinatura e o locatário ativos no seu ambiente local.

    az account show
    
  3. Se a assinatura ativa e o locatário não forem válidos para o serviço de IQ do Foundry, execute os comandos a seguir para atualizar seus valores. Você pode encontrar a ID da assinatura na página visão geral do serviço IQ do Foundry no portal do Azure. Para encontrar a ID do locatário, selecione o nome da sua assinatura na página Visão geral e localize o valor Grupo de gerenciamento pai.

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

Conecte-se à Foundry IQ

Observação

Esta seção ilustra o padrão python básico para conexões sem chave. Para obter diretrizes abrangentes, consulte um guia de início rápido ou tutorial específico, como Quickstart: Recuperação Agêntica.

Você pode usar notebooks Python no Visual Studio Code para enviar solicitações ao seu serviço Foundry IQ. Para autenticação de solicitação, use a DefaultAzureCredential classe da biblioteca de Identidade do Azure.

Para se conectar usando o Python:

  1. No seu sistema local, abra o Visual Studio Code.

  2. Crie um arquivo do .ipynb .

  3. Crie uma célula de código para instalar as bibliotecas azure-identity e azure-search-documents.

    pip install azure-identity azure-search-documents
    
  4. Crie outra célula de código para autenticar e conectar-se ao serviço Foundry IQ.

    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. Defina service_endpoint como o valor obtido em Obter informações de serviço.

  6. Selecione Executar Tudo para executar ambas as células de código.

    A saída deve listar os índices existentes (se houver) em seu serviço Foundry IQ, indicando uma conexão bem-sucedida.

Solucionar erros 401

Se você encontrar um erro 401, siga estas etapas de solução de problemas:

  • Revise Configurar acesso baseado em função. Seu serviço de IQ do Foundry deve ter controle de acesso baseado em função ou ambos habilitados. Políticas no nível de assinatura ou de grupo de recursos podem substituir suas atribuições de função.

  • Revise Entrar no Azure. Você deve efetuar login na assinatura que contém seu serviço Foundry IQ.

  • Verifique se a variável de endpoint está com aspas ao redor.

  • Se tudo falhar, reinicie o dispositivo para remover tokens armazenados em cache e repita as etapas neste início rápido, começando com a entrada no Azure.

Neste início rápido, você usará o RBAC (controle de acesso baseado em função) e Microsoft Entra ID para estabelecer uma conexão sem chave com seu serviço de IQ do Foundry (Pesquisa de IA do Azure ). Em seguida, use REST no Visual Studio Code para interagir com seu serviço.

Conexões sem chave fornecem segurança aprimorada por meio de permissões granulares e autenticação baseada em identidade. Não recomendamos chaves de API codificadas, mas, se preferir, consulte Conectar ao IQ do Foundry usando chaves.

Pré-requisitos

Configurar o acesso baseado em função

Nesta seção, você habilitará o RBAC em seu serviço de IQ de Pesquisa (Pesquisa de IA do Azure ) e atribuirá as funções necessárias para criar, carregar e consultar objetos de pesquisa. Para obter mais informações sobre essas etapas, consulte Conectar-se ao Foundry IQ usando funções.

Para configurar o acesso:

  1. Vá para o serviço de IQ do Foundry no portal do Azure.

  2. No painel esquerdo, selecione Chaves de Configurações>.

  3. Selecione Controle de Acesso Baseado em Funções (RBAC) ou Ambos se precisar de tempo para fazer a transição dos clientes para o Controle de Acesso Baseado em Funções (RBAC).

    Captura de tela das opções de controle de acesso no portal do Azure.

  4. No painel esquerdo, selecione Controle de acesso (IAM).

  5. Selecione Adicionar>Adicionar atribuição de função.

    Captura de tela do menu suspenso para adicionar uma atribuição de função no portal Azure.

  6. Atribua a função Colaborador do Serviço de Pesquisa à sua conta de usuário ou identidade gerenciada.

  7. Repita a atribuição de função para o Colaborador de Dados do Índice de Pesquisa.

Obter informações de serviço

Nesta seção, você recupera a ID da assinatura e o ponto de extremidade do serviço Foundry IQ. Se você tiver apenas uma assinatura, ignore a ID da assinatura e recupere apenas o ponto de extremidade. Você usará esses valores nas seções restantes deste início rápido.

Para obter suas informações de serviço:

  1. Vá para o serviço de IQ do Foundry no portal do Azure.

  2. No painel esquerdo, selecione Visão geral.

  3. Anote o ID da assinatura e o endpoint.

    Captura de tela da ID da assinatura e do ponto de extremidade no portal do Azure.

Entrar no Azure

Antes de se conectar ao serviço de IQ do Foundry, use o CLI do Azure para entrar na assinatura que contém seu serviço.

Para entrar:

  1. No sistema local, abra uma ferramenta de linha de comando.

  2. Verifique a assinatura e o locatário ativos no seu ambiente local.

    az account show
    
  3. Se a assinatura ativa e o locatário não forem válidos para o serviço de IQ do Foundry, execute os comandos a seguir para atualizar seus valores. Você pode encontrar a ID da assinatura na página visão geral do serviço IQ do Foundry no portal do Azure. Para encontrar a ID do locatário, selecione o nome da sua assinatura na página Visão geral e localize o valor Grupo de gerenciamento pai.

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

Obter o token

As chamadas à API REST exigem a inclusão de um token de ID do Microsoft Entra. Use esse token para autenticar solicitações na próxima seção.

Para obter seu token:

  1. Usando a mesma ferramenta de linha de comando, gere um token de acesso.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
    
  2. Anote a saída do token.

Conecte-se à Foundry IQ

Observação

Esta seção ilustra o padrão REST básico para conexões sem chave. Para obter diretrizes abrangentes, consulte um guia de início rápido ou tutorial específico, como Quickstart: Recuperação Agêntica.

Você pode usar a extensão rest client em Visual Studio Code para enviar solicitações para seu serviço de IQ do Foundry. Para autenticação de solicitação, inclua um cabeçalho Authorization com o token do Microsoft Entra ID gerado anteriormente.

Para se conectar usando REST:

  1. No seu sistema local, abra o Visual Studio Code.

  2. Criar um arquivo em .rest ou .http.

  3. Cole as variáveis e a requisição a seguir no arquivo.

    @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. Defina @baseUrl como o valor obtido em Obter informações de serviço.

  5. Defina @token como o valor obtido no token Get.

  6. Em , ### List existing indexesselecione Enviar Solicitação.

    Você deve receber uma HTTP/1.1 200 OK resposta, indicando uma conexão bem-sucedida com seu serviço Foundry IQ.

Solucionar erros 401

Se você encontrar um erro 401, siga estas etapas de solução de problemas:

  • Revise Configurar acesso baseado em função. Seu serviço Foundry IQ deve estar com o controle de acesso baseado em funções ou ambos habilitados. Políticas no nível de assinatura ou de grupo de recursos podem substituir suas atribuições de função.

  • Revise Entrar no Azure. Você deve entrar na assinatura que contém seu serviço Foundry IQ.

  • Verifique se as variáveis de endpoint e token não têm aspas ou espaços extras em volta.

  • Verifique se o token não tem o @ símbolo no cabeçalho da solicitação. Por exemplo, se a variável for @token, a referência na solicitação deverá ser {{token}}.

  • Se tudo falhar, reinicie o dispositivo para remover tokens armazenados em cache e repita as etapas neste início rápido, começando com a entrada no Azure.