Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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
Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Um serviço Foundry IQ em qualquer região ou camada.
A CLI do Azure para autenticação sem uso de chave com a Microsoft Entra ID.
Visual Studio Code com a extensão Python e o pacote Jupyter.
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:
Vá para o serviço de IQ do Foundry no portal do Azure.
No painel esquerdo, selecione Chaves de Configurações>.
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).
No painel esquerdo, selecione Controle de acesso (IAM).
Selecione Adicionar>Adicionar atribuição de função.
Atribua a função Colaborador do Serviço de Pesquisa à sua conta de usuário ou identidade gerenciada.
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:
Vá para o serviço de IQ do Foundry no Azure portal.
No painel esquerdo, selecione Visão geral.
Anote o ID da assinatura e o endpoint.
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:
No sistema local, abra uma ferramenta de linha de comando.
Verifique a assinatura e o locatário ativos no seu ambiente local.
az account showSe 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:
No seu sistema local, abra o Visual Studio Code.
Crie um arquivo do
.ipynb.Crie uma célula de código para instalar as bibliotecas
azure-identityeazure-search-documents.pip install azure-identity azure-search-documentsCrie 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))Defina
service_endpointcomo o valor obtido em Obter informações de serviço.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
Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Um serviço de IQ do Foundry em qualquer região ou camada.
A CLI do Azure para autenticação sem uso de chave com a Microsoft Entra ID.
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:
Vá para o serviço de IQ do Foundry no portal do Azure.
No painel esquerdo, selecione Chaves de Configurações>.
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).
No painel esquerdo, selecione Controle de acesso (IAM).
Selecione Adicionar>Adicionar atribuição de função.
Atribua a função Colaborador do Serviço de Pesquisa à sua conta de usuário ou identidade gerenciada.
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:
Vá para o serviço de IQ do Foundry no portal do Azure.
No painel esquerdo, selecione Visão geral.
Anote o ID da assinatura e o endpoint.
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:
No sistema local, abra uma ferramenta de linha de comando.
Verifique a assinatura e o locatário ativos no seu ambiente local.
az account showSe 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:
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 tsvAnote 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:
No seu sistema local, abra o Visual Studio Code.
Criar um arquivo em
.restou.http.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}}Defina
@baseUrlcomo o valor obtido em Obter informações de serviço.Defina
@tokencomo o valor obtido no token Get.Em ,
### List existing indexesselecione Enviar Solicitação.Você deve receber uma
HTTP/1.1 200 OKresposta, 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.