Configuração de Aplicativos do Azure para IA: Python, rótulos, sinalizadores e Cofre de Chaves
Externalize configurações de aplicações de IA, componha substituições por ambiente, altere comportamentos com sinalizadores de recursos, atualize valores com consistência e exponha segredos do Cofre de Chaves por um único caminho.
Tempo de estudo sugerido: 120 minutos • Nível intermediário • Reescrita autoral completa com versão resumida de cada tópico, avaliação comentada e laboratório Python guiado
Por João Ricardo Dutra••Conteúdo autoral completo
1. Cenário e objetivos de aprendizagem
Um de documentos com IA usa o para extração, para documentos e para entrada. Desenvolvimento, homologação e produção têm de modelo, tamanhos de lote, intervalos de repetição e detalhes de conexão diferentes. Quando esses valores ficam espalhados por , variáveis de ambiente e scripts, uma alteração pode exigir commit, nova imagem e reimplantação — e uma substituição esquecida pode interromper a versão.
Conectar código Python à do com .
Organizar padrões e variantes de ambiente com chaves, rótulos, seletores e prefixos.
Controlar modelos ou etapas com sinalizadores de recursos sem reimplantar.
Resolver segredos do pelo mesmo provedor semelhante a dicionário.
Classificar cada valor por sensibilidade, ciclo de vida e necessidade de acesso.
Resumo rápido
O objetivo é manter um plano de configuração centralizado fora do código, permitir mudanças controladas em execução e reservar outra fronteira de segurança para credenciais.
2. Por que a atende cargas de IA
A do é um armazenamento gerenciado de pares chave-valor para configurações e sinalizadores de recursos. Ela separa decisões operacionais do binário: lotes, repetições, tempos limite, implantações de modelo e rotas mudam sem reconstruir o contêiner. Rótulos criam variantes, o gerenciamento de recursos controla ativação, instantâneos preservam um ponto no tempo e referências do mantêm um caminho único sem retirar o segredo do cofre.
Isso ajuda a reduzir desvio de configuração e a atender atualizações sem indisponibilidade, mas não elimina o risco. Validação, publicação atômica por sentinela, observabilidade e reversão continuam obrigatórias.
Resumo rápido
O serviço centraliza configurações não confidenciais e estado de recursos; operações seguras ainda exigem validação, atualização coordenada e reversão.
3. Modelo de dados de uma configuração
Propriedades de uma configuração
Propriedade
Significado e uso
Chave
Identificador Unicode sensível a maiúsculas. Use : ou / para hierarquia, como DocPipeline:OpenAI:.
Valor
Texto Unicode, ou referência. Chave e valor juntos não podem ultrapassar 10 KB.
Rótulo
Variante opcional de ambiente, região ou versão. A ausência é o rótulo nulo, normalmente usado como padrão.
Tipo de conteúdo
Indica como interpretar o valor, por exemplo application/ ou o tipo de referência do .
Marcas
opcionais para filtrar e organizar; não substituem rótulos nem controles de acesso.
válido com tipo application/ é desserializado pelo provedor Python atual. Como o serviço não impõe uma hierarquia, a convenção de nomes é um contrato arquitetural da equipe.
Resumo rápido
Uma configuração inclui chave, valor, rótulo, tipo de conteúdo e marcas; essas propriedades definem variante, interpretação e descoberta.
4. Instalação do provedor Python e carregamento
-appconfiguration-provider oferece load() sobre o do e devolve AzureAppConfigurationProvider, que se comporta como um mapeamento Python. -identity fornece credenciais sem senha e featuremanagement avalia sinalizadores. Carregar o conjunto selecionado de uma vez reduz chamadas em comparação com buscas individuais.
Por padrão, load() lê todos os pares sem rótulo. O segue ://<nome-do-armazenamento>.azconfig.io. Guarde apenas esse em configuração comum; não coloque a cadeia de conexão no código-fonte.
Resumo rápido
Instale provedor e identidade, conecte ao e use o resultado com operações normais de dicionário.
5. Autenticação com e do
DefaultAzureCredential pode usar CLI do ou localmente e no ,, ou . A autenticação do é recomendada porque a aplicação implantada não precisa armazenar cadeia de conexão.
Atribuições com privilégio mínimo
Chamador
Função
Finalidade
Aplicação em execução
Data Reader
Ler pares, sinalizadores e de referências.
Operador ou CI/CD controlado
Criar e alterar configurações; não conceder ao runtime somente leitura.
Runtime que resolve referências
Secrets User em cada cofre
Ler o segredo apontado pela referência.
Uma cadeia de conexão é uma credencial. Se inevitável, proteja-a no ; caso contrário, prefira , e funções limitadas ao armazenamento e ao cofre necessários.
Resumo rápido
A autenticação identifica a carga; o concede leitura à e, quando preciso, leitura de segredos no .
6. Seleção de chaves e remoção de prefixos
SettingSelector restringe o carregamento. key_filter aceita chave exata ou padrão como DocPipeline:*, e label_filter seleciona uma variante. O filtro impede que uma aplicação leia configurações alheias de um armazenamento compartilhado ou sofra colisões.
trim_prefixes remove o depois da leitura. Assim, DocPipeline:OpenAI: vira OpenAI: no código. Preserve o prefixo exclusivo no armazenamento e retire-o somente na fronteira da aplicação.
Os seletores definem e rótulo; seletores posteriores substituem valores anteriores da mesma chave já sem prefixo.
Resumo rápido
Filtre na origem e remova apenas o da aplicação para manter o armazenamento organizado e o código legível.
7. Composição de padrões e substituições por rótulo
A mesma chave pode ter rótulos Development, Staging e Production. A variante sem rótulo fornece o padrão. Carregue primeiro o rótulo nulo e depois o ambiente atual: se ambos retornarem a mesma chave, o último vence; chaves sem substituição mantêm o padrão.
environment = os.getenv("APP_ENVIRONMENT", "Development")
config = load(
endpoint=endpoint,
credential=credential,
selects=[
SettingSelector(key_filter="DocPipeline:*", label_filter="\0"),
SettingSelector(key_filter="DocPipeline:*", label_filter=environment),
],
trim_prefixes=["DocPipeline:"],
)
# The environment-labeled value wins when both selectors return the same key.
batch_size = int(config["Pipeline:BatchSize"])
A ordem dos seletores faz parte da correção. O código sempre lê :BatchSize, sem nomes de variáveis por ambiente nem condicionais. Rótulos também podem representar região ou versão, mas várias dimensões independentes em um único esquema geram ambiguidade.
Resumo rápido
Rótulo nulo primeiro e ambiente depois produzem uma configuração completa com apenas as diferenças intencionais substituindo os padrões.
8. de chaves autoexplicativo
Adote um delimitador e agrupe por componente: OpenAI:, OpenAI:DeploymentName, OpenAI:MaxTokens, CosmosDB:DatabaseName, CosmosDB:ContainerName, :BatchSize, :RetryCount e :TimeoutSeconds. Um serviço que precisa apenas do modelo seleciona OpenAI:* depois do prefixo da aplicação.
Use nomes semânticos estáveis, sem Prod ou Dev na chave.
Use rótulos para ambiente e prefixos para propriedade da aplicação ou componente.
Mantenha , implantações, dimensões, nomes de fila, contêiner e banco e regras de rota como configurações não confidenciais.
Use marcas para inventário; composição em execução depende de seletores e rótulos.
Resumo rápido
Nomes hierárquicos consistentes facilitam navegação e seleção e deixam a identificação do ambiente fora das chaves.
9. Atualização consistente com chave sentinela
A atualização dinâmica é por consulta e orientada à atividade, não um envio automático ao processo. Configure WatchKey e chame config.refresh() em requisição, loop de trabalho ou retorno agendado. refresh_interval é o intervalo mínimo; uma chamada antecipada retorna sem consultar o serviço.
from azure.appconfiguration.provider import WatchKey
config = load(
endpoint=endpoint,
credential=credential,
selects=selects,
refresh_on=[WatchKey("DocPipeline:Sentinel", label=environment)],
refresh_interval=60,
)
# Call from an active request, worker loop, or scheduled callback.
# Before the interval elapses, this returns without contacting the store.
config.refresh()
A sentinela permite alterar vários valores e atualizá-la por último. Quando seu muda, o provedor recarrega o conjunto selecionado e evita uma configuração parcial. Se a atualização falhar, o conhecido continua em uso e outra tentativa ocorre depois do intervalo.
Resumo rápido
Publique as configurações primeiro e a sentinela por último; a atividade da aplicação chama refresh e recarrega o conjunto quando o intervalo permite.
10. Sinalizadores de recursos e seu armazenamento
Um sinalizador tem nome, estado habilitado e filtros ou variantes opcionais. A o armazena sob o prefixo reservado .appconfig.featureflag/ e o tipo application/vnd.microsoft.appconfig.ff+;charset=, mas o provedor e a biblioteca abstraem essa representação.
Sinalizadores separam o ciclo do recurso do ciclo de implantação. Eles podem liberar um novo modelo de embeddings, ignorar classificação defeituosa, ativar etapas progressivamente ou dividir um experimento. São controle operacional, não autorização, portanto não constituem fronteira de segurança.
Resumo rápido
Sinalizadores expõem ou ocultam comportamentos já implantados; identidade e controle de acesso continuam responsáveis pela segurança.
11. Avaliação e atualização com FeatureManager
No provedor Python atual, feature_flag_enabled=True carrega e feature_flag_refresh_enabled=True atualiza os sinalizadores. O nome singular do primeiro parâmetro corresponde à referência vigente da Microsoft. FeatureManager recebe o provedor e is_enabled() avalia o sinalizador no caminho protegido.
from featuremanagement import FeatureManager
config = load(
endpoint=endpoint,
credential=credential,
selects=selects,
feature_flag_enabled=True,
feature_flag_refresh_enabled=True,
refresh_on=[WatchKey("DocPipeline:Sentinel", label=environment)],
refresh_interval=30,
)
features = FeatureManager(config)
config.refresh()
if features.is_enabled("UseNewEmbeddingsModel"):
process_with_new_model(document)
else:
process_with_current_model(document)
A atualização de sinalizadores é independente da atualização comum: mudança em um sinalizador não força recarga dos pares e vice-versa. Uma chamada a config.refresh() avança cada ciclo habilitado que estiver elegível.
Resumo rápido
FeatureManager avalia sinalizadores do provedor; carregamento e atualização são explícitos e usam um ciclo separado das configurações comuns.
12. Padrões de liberação controlada para IA
Padrão em execução
Padrão
Uso em IA
Proteção operacional
Liberação progressiva de modelo
Direcionar parte do tráfego a nova implantação de embeddings ou inferência.
Começar internamente, medir qualidade e latência e só então ampliar.
Interruptor de emergência
Ignorar uma etapa que produz classificação ou saída incorreta.
Testar e observar o caminho alternativo antes do incidente.
Experimento A/B
Dividir solicitações entre processamento atual e experimental.
Registrar atribuição, entradas, saídas, custo e qualidade.
Ativação por etapas
Habilitar extração, enriquecimento, indexação e disponibilização uma a uma.
Validar cada etapa e preservar reversão.
O mesmo artefato contém os dois caminhos; o operador muda a exposição e observa o resultado.
Resumo rápido
Sinalizadores funcionam melhor com liberação mensurada, alternativa testada e telemetria que comprova a segurança do novo caminho.
13. Criação e resolução de referências do
Uma referência do é um par cujo valor contém o do segredo e cujo tipo é application/vnd.microsoft.appconfig.keyvaultref+;charset=. A guarda do cofre, nome, versão opcional e , não uma cópia criptografada. A chave ainda aceita rótulos, seletores e composição.
sem versão resolve a versão mais recente e normalmente adota rotação sem mudar a referência; versionado fixa deliberadamente uma versão. O provedor resolve quando recebe keyvault_credential, configurações de cliente por cofre ou um resolvedor de segredos.
A aplicação vê um mapeamento único, enquanto armazenamento e cofre mantêm funções e responsabilidades separadas.
Resumo rápido
Guarde apenas o na , resolva com identidade autorizada e omita a versão quando a adoção automática da rotação for desejada.
14. Autorização dupla e atualização de segredos rotacionados
A identidade precisa de Data Reader no armazenamento e Secrets User em cada cofre referenciado. Acesso a apenas um serviço não basta. keyvault_client_configs permite credenciais diferentes por quando uma única identidade não deve alcançar todos os cofres.
secret_refresh_interval determina com que frequência chamadas elegíveis a config.refresh() resolvem novamente os segredos, mesmo que o não tenha mudado. É independente do intervalo comum. Defina-o pela rotação e defasagem tolerada e calcule o volume total de solicitações para muitas referências e réplicas.
Resumo rápido
A resolução atravessa duas autorizações; a atualização do segredo tem intervalo e orçamento de requisições próprios.
15. Escolha do serviço para cada valor
Regra de posicionamento
Tipo de valor
Serviço e representação
Exemplos
Comportamento não confidencial
, chave-valor direta
, implantação, dimensões, lote, repetição, tempo limite, , nomes de fila, contêiner ou banco.
Ativação de recurso
, sinalizador
UseNewEmbeddingsModel, EnableBatchProcessing.
Credencial ou valor que concede acesso
Segredo no via referência
Chave de ,, senha, cadeia com credencial, chave de conta, segredo de .
Material criptográfico
Chave ou certificado no , geralmente com específico
Chave de criptografia, certificado e chave privada.
A sensibilidade é o teste principal: se o valor isolado concede acesso ou permite operação indevida, ele vai para o . Ele acrescenta criptografia apoiada por , auditoria de cada acesso em de diagnóstico, expiração, rotação automatizada, exclusão reversível e proteção contra limpeza. A usa no nível do armazenamento e oferece rótulos, sinalizadores, instantâneos e maior taxa para valores de comportamento.
Resumo rápido
Comportamento fica na ; credenciais e material criptográfico ficam no , unidos por referências quando útil.
16. Arquitetura complementar e antipadrões
Use a como ponto de entrada e o como back-end seguro dos valores confidenciais. Operadores gerenciam chaves e referências juntos, rótulos compõem ambos e a aplicação recebe um mapeamento, mas o segredo permanece protegido e auditado no cofre.
Não armazene segredos diretamente na : faltam os controles de ciclo, auditoria e criptografia próprios do cofre.
Não coloque toda configuração comum no : perdem-se rótulos, sinalizadores, instantâneos e throughput próprio de configuração.
Não duplique o valor nos dois serviços: as cópias divergem; mantenha uma fonte de verdade e uma referência.
Não mantenha valores fixos no código depois da adoção: isso contorna atualização e governança.
Não use intervalos agressivos sem medir volume, limitação e custo.
Resumo rápido
Um ponto de entrada e uma fonte segura evitam duplicação, controles inadequados e reimplantação desnecessária.
17. Exercício guiado com Flask
O exercício de origem provisiona uma e um com dados de exemplo e completa um aplicativo Flask em Python que compõe rótulos, resolve referências, lista propriedades e e aciona atualização por sentinela. Reserve cerca de 30 minutos e use assinatura do ,, Python 3.12 ou superior e a CLI do mais recente.
Baixe o projeto inicial e crie um ambiente virtual.
Crie os serviços com valores padrão e rotulados e uma referência de segredo.
Conceda às identidades as funções necessárias nos dois recursos.
Complete seletores, remoção de prefixo, DefaultAzureCredential, resolução e atualização.
Execute o Flask, inspecione valores e sem imprimir credenciais e confirme substituições.
Altere vários valores, publique a sentinela por último, atualize e confirme o novo conjunto consistente.
Rotacione o segredo sem versão, aguarde ou acione a atualização elegível e confirme a mudança sem alterar a referência.
Exclua recursos e atribuições temporárias.
# Required environment
export AZURE_APPCONFIG_ENDPOINT="https://<store>.azconfig.io"
export APP_ENVIRONMENT="Development"
# Authenticate the developer identity locally.
az login
# Start the completed Python 3.12+ Flask starter.
python -m flask --app app run
# In another terminal, change one or more settings, then update Sentinel.
# Return to the app and trigger its refresh operation to observe the new set.
Resumo rápido
O laboratório comprova provisionamento, autorização, leitura, composição, resolução, inspeção, atualização, rotação, verificação e limpeza.
18. Revisão da avaliação, checklist e referências
Decisões da avaliação
Pergunta
Melhor resposta
Motivo
Padrão e Production retornam :BatchSize
Valor de Production
O seletor posterior substitui o anterior.
O que a referência armazena?
, e tipo de conteúdo
O valor permanece no cofre.
Onde guardar gpt-4o como implantação?
Chave-valor comum na
Controla comportamento e não concede acesso.
Quais funções resolvem uma referência?
Data Reader e Secrets User
É necessário ler o ponteiro e depois o segredo.
Como efetivar atualização por sentinela?
A aplicação chama refresh após a mudança e quando o intervalo permite
A atualização é orientada à atividade.
Checklist final de projeto
Use hierarquia estável e rótulos em vez de ambiente nas chaves.
Carregue somente o prefixo necessário e aplique padrões antes das substituições.
Use , e menor privilégio.
Publique o conjunto antes da sentinela.
Trate sinalizadores como controles operacionais com telemetria e alternativa.
Use referência sem versão quando desejar adoção automática da rotação.
Defina separadamente os intervalos de configuração, sinalizadores e segredos.
Monitore falhas de atualização, estado obsoleto, exposição, erros do cofre, limitação e reversão.
