ai-agents-for-beginners

Guia de Configuração do Azure AI Search

Este guia irá ajudá-lo a configurar o Azure AI Search usando o portal do Azure. Siga os passos abaixo para criar e configurar seu serviço Azure AI Search.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte:

Uma assinatura do Azure. Se você não tiver uma assinatura do Azure, pode criar uma conta gratuita em Azure Free Account.

Passo 1: Crie uma Conta de Armazenamento do Azure

Siga esta instrução, Create an Azure storage account, para criar uma nova Conta de Armazenamento do Azure. NOTA: Certifique-se de que o tipo da Conta de Armazenamento seja Standard General Purpose V2.

Passo 2: Crie um Serviço Azure AI Search

Faça login no portal Azure.
No painel de navegação à esquerda, clique em Criar um recurso.
Na caixa de pesquisa, digite “Azure AI Search” e selecione Azure AI Search na lista de resultados.
Clique no botão Criar.
Na aba Básicos, forneça as seguintes informações:
- Assinatura: Selecione sua assinatura do Azure.
- Grupo de recursos: Crie um novo grupo de recursos ou selecione um existente.
- Nome do recurso: Insira um nome único para o seu serviço de busca.
- Região: Selecione a região mais próxima dos seus usuários.
- Camada de preço: Escolha uma camada de preço que atenda às suas necessidades. Você pode começar com a camada Gratuita para testes.
Clique em Revisar + criar.
Revise as configurações e clique em Criar para criar o serviço de busca.

Passo 3: Comece a usar o Azure AI Search

Quando a implantação for concluída, navegue até o seu serviço de busca no portal do Azure.
No painel de visão geral do serviço de busca, copie a URL. Ela deve parecer com https://<service-name>.search.windows.net.
(Recomendado) Habilite o acesso sem chave com Microsoft Entra ID (RBAC) conforme mostrado no Passo 4 abaixo — nenhuma chave necessária. Os exemplos neste guia criam/atualizam índices e enviam documentos, o que requer os papéis Search Service Contributor e Search Index Data Contributor (ou, para autenticação baseada em chave, a chave administrativa primária — não a chave de consulta). Somente se você não puder usar RBAC, abra o painel Configurações > Chaves e copie a chave administrativa primária.
Siga os passos na página do Guia Rápido para criar um índice, enviar dados e realizar uma busca.

Passo 4: Use as Ferramentas do Azure AI Search

O Azure AI Search integra-se com várias ferramentas para aprimorar suas capacidades de busca. Você pode usar o Azure CLI, SDK para Python, SDK para .NET e outras ferramentas para configurações e operações avançadas.

Usando Azure CLI

Instale o Azure CLI seguindo as instruções em Install Azure CLI.
Faça login no Azure CLI usando o comando:
```
az login
```

(Recomendado) Habilite o acesso sem chave com Microsoft Entra ID (RBAC):

 az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey
 az role assignment create --assignee <your-user-or-principal-id> --role "Search Service Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)
 az role assignment create --assignee <your-user-or-principal-id> --role "Search Index Data Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)
 # az search service show não tem campo "endpoint"; construa a URL a partir do nome do serviço.
 export AZURE_SEARCH_SERVICE_ENDPOINT="https://<service-name>.search.windows.net"

Com o RBAC habilitado, os exemplos de SDK para Python e .NET abaixo autenticam com DefaultAzureCredential, que usa sua sessão az login durante o desenvolvimento local — nenhuma chave administrativa necessária. Veja Conectar ao Azure AI Search usando papéis.

(Alternativa) Autenticação baseada em chave — somente se você não puder usar RBAC, armazene também a chave administrativa:

Armazene tanto o endpoint quanto a chave API da instância Azure AI Search em variáveis de ambiente.

```bash
# zsh/bash
# az search service show não tem campo "endpoint"; construa a URL a partir do nome do serviço.
export AZURE_SEARCH_SERVICE_ENDPOINT="https://<service-name>.search.windows.net"
export AZURE_SEARCH_API_KEY=$(az search admin-key show -g <resource-group> --service-name <service-name> --query "primaryKey" -o tsv)
```

```powershell
# PowerShell
# az search service show não tem campo "endpoint"; construa a URL a partir do nome do serviço.
$env:AZURE_SEARCH_SERVICE_ENDPOINT = "https://<service-name>.search.windows.net"
$env:AZURE_SEARCH_API_KEY = $(az search admin-key show -g <resource-group> --service-name <service-name> --query "primaryKey" -o tsv)
```

Usando SDK Python

Instale a biblioteca cliente Azure Cognitive Search e Azure Identity para Python:
```
pip install azure-search-documents azure-identity
```

Use o seguinte código Python para criar um índice e enviar documentos:

 import os
 from azure.identity import DefaultAzureCredential
 from azure.search.documents import SearchClient
 from azure.search.documents.indexes import SearchIndexClient
 from azure.search.documents.indexes.models import SearchIndex, SimpleField, edm

 service_endpoint = os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT")
 index_name = "sample-index"

 # Sem chave (recomendado): usa sua identidade `az login` via RBAC do Entra ID.
 # Requer os papéis "Colaborador do Serviço de Pesquisa" e "Colaborador de Dados do Índice de Pesquisa".
 credential = DefaultAzureCredential()
 # Alternativa (autenticação baseada em chave):
 # from azure.core.credentials import AzureKeyCredential
 # credential = AzureKeyCredential(os.getenv("AZURE_SEARCH_API_KEY"))
 index_client = SearchIndexClient(service_endpoint, credential)

 fields = [
     SimpleField(name="id", type=edm.String, key=True),
     SimpleField(name="content", type=edm.String, searchable=True),
 ]

 index = SearchIndex(name=index_name, fields=fields)

 index_client.create_index(index)

 search_client = SearchClient(service_endpoint, index_name, credential)

 documents = [
     {"id": "1", "content": "Hello world"},
     {"id": "2", "content": "Azure Cognitive Search"}
 ]

 search_client.upload_documents(documents)

Usando SDK .NET

Execute o seguinte comando para criar um índice e enviar documentos:
```
 dotnet run ./AzureSearch.cs
```
O exemplo .NET abaixo usa DefaultAzureCredential, que pode usar seu login no Azure CLI a partir do az login durante o desenvolvimento local.

Aqui está o código .NET do AzureSearch.cs:

 #:package Azure.Search.Documents@11.*
 #:package Azure.Identity@1.21.0
 #:property PublishAot=false

 using Azure;
 using Azure.Identity;
 using Azure.Search.Documents;
 using Azure.Search.Documents.Indexes;
 using Azure.Search.Documents.Indexes.Models;

 var serviceEndpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_SEARCH_SERVICE_ENDPOINT")!);
 var indexName = "sample-index";

 // Keyless (recommended): uses your `az login` identity via Entra ID RBAC.
 // Requires the "Search Service Contributor" and "Search Index Data Contributor" roles.
 var credential = new DefaultAzureCredential();
 // Fallback (key-based auth): the `using Azure;` directive above already imports
 // AzureKeyCredential; replace the credential line above with:
 // var credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_SEARCH_API_KEY")!);
 var indexClient = new SearchIndexClient(serviceEndpoint, credential);

 var fields = new List<SearchField>()
 {
     new SimpleField("id", SearchFieldDataType.String) { IsKey = true },
     new SearchableField("content")
 };

 var index = new SearchIndex(name: indexName, fields: fields);

 var response = await indexClient.CreateOrUpdateIndexAsync(index);
 Console.WriteLine($"Index '{response.Value.Name}' ready.");

 var searchClient = new SearchClient(serviceEndpoint, indexName, credential);

 var documents = new[]
 {
     new { id = "1", content = "Hello world" },
     new { id = "2", content = "Azure Cognitive Search" }
 };

 var result = await searchClient.UploadDocumentsAsync(documents);
 Console.WriteLine($"Uploaded {result.Value.Results.Count} documents to index '{response.Value.Name}'.");

Para informações mais detalhadas, consulte a seguinte documentação:

Conclusão

Você configurou com sucesso o Azure AI Search usando o portal do Azure e ferramentas integradas. Agora você pode explorar recursos e capacidades mais avançadas do Azure AI Search para aprimorar suas soluções de busca.

Para mais assistência, visite a documentação do Azure Cognitive Search.

Aviso Legal: Este documento foi traduzido usando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução.

This site is open source. Improve this page.