Criar repositórios de documentos de IA com o Azure Cosmos DB for NoSQL
Projete partições e taxa de transferência, conecte-se com segurança pelo SDK do Python, implemente CRUD e concorrência otimista e escreva consultas SQL eficientes para recomendação e RAG.
Tempo de estudo sugerido: 95 minutos • Nível intermediário • Reescrita autoral completa com versão resumida de cada tópico, avaliação comentada e laboratório RAG guiado
Por João Ricardo Dutra••Conteúdo autoral completo
1. Relacionar um repositório flexível ao padrão de acesso da IA
Mecanismos de recomendação e soluções de geração aumentada por recuperação costumam guardar catálogos, preferências, histórico de interação, saídas de modelos e fragmentos de documentos em . O for combina esquema flexível, indexação automática, distribuição global e taxa de transferência escalável de modo independente do armazenamento.
O projeto ainda deve nascer dos padrões de acesso. É preciso organizar contas, bancos de dados, contêineres e itens; escolher uma chave de partição que distribua a carga; decidir entre taxa manual e escala automática; autenticar com segurança; e preferir leituras pontuais ou consultas direcionadas. A indexação padrão cobre propriedades automaticamente, mas alguns ORDER BY exigem índices compostos.
Explicar a hierarquia e os limites de configuração.
Implementar acesso seguro pelo e operações .
Escolher entre leitura pontual e consulta conforme identificadores e filtros.
Criar consultas semelhantes a SQL com projeção, filtro, ordenação, agregação e controle de RUs.
Resumo do tópico
Comece pelos padrões de leitura e gravação da carga de IA e alinhe modelo, partição, taxa, autenticação e consulta.
2. Navegar pela hierarquia de conta, banco, contêiner e item
A conta do é o limite superior de gerenciamento e fornece um exclusivo aos SDKs e . Nela ficam nível de consistência padrão, política de rede e regiões replicadas. Contas separadas podem isolar produção, homologação e desenvolvimento.
Bancos de dados são namespaces lógicos para contêineres relacionados e podem compartilhar taxa de transferência. Contêineres guardam itens e formam o limite principal de escalabilidade: cada um define uma chave de partição e aceita documentos com formatos diferentes. Os itens representam os registros da aplicação.
A configuração desce da conta aos contêineres; os itens carregam os dados da aplicação.
Resumo do tópico
A conta fornece e opções globais, bancos agrupam contêineres, contêineres particionam e escalam, e itens armazenam .
3. Selecionar uma chave de partição adequada à distribuição e às consultas
O caminho da chave aponta para uma propriedade , enquanto cada valor forma uma partição lógica. O serviço aplica aos valores e mapeia partições lógicas em partições físicas gerenciadas. A combinação de id e valor da chave identifica o item. Como a chave do contêiner não muda no local, a decisão exige análise antecipada.
Escolha uma propriedade estável e presente em todos os itens.
Prefira alta cardinalidade e distribuição uniforme de armazenamento e RUs.
Alinhe a chave a filtros de igualdade e leituras pontuais frequentes.
Use userId ou tenantId quando a atividade se agrupar naturalmente.
Evite booleanos, categorias muito desiguais e valores apenas temporais que criem partições quentes.
Um catálogo pode usar categoryId se as categorias forem equilibradas; de interação frequentemente se beneficiam de userId. Caminhos aninhados como //region são válidos. Para trocar a chave, crie outro contêiner e migre ou copie os dados.
Resumo do tópico
Uma boa chave é imutável, possui alta cardinalidade, distribui uso e aparece nas operações dominantes.
4. Provisionar taxa manual ou escala automática em RU/s
Unidades de Solicitação normalizam CPU, memória e E/S consumidas por leituras, gravações, consultas e procedimentos armazenados. A taxa é expressa em RU/s. A taxa dedicada ao contêiner reserva capacidade; a taxa do banco permite compartilhamento entre contêineres com picos em momentos diferentes.
Opções de taxa de transferência.
Modo
Comportamento
Quando usar
Manual
Mantém RU/s fixas; contêiner dedicado começa em 400 RU/s.
Demanda previsível e estável.
Escala automática
Varia de 10% do máximo configurado até esse máximo; o máximo inicial é pelo menos 1.000 RU/s.
Inferência, promoções ou geram picos.
Compartilhada no banco
Distribui um conjunto entre vários contêineres.
Os padrões de uso se complementam.
Chaves equilibradas permitem que armazenamento e taxa escalem horizontalmente sem concentrar solicitações.
Resumo do tópico
Escolha escopo e modo conforme variação, isolamento e custo; monitore limitação 429 e partições quentes.
5. Entender itens, propriedades do sistema, indexação e custo
Todo item fornece id, que deve ser único dentro da partição lógica. id mais chave identifica o registro no contêiner. O serviço adiciona _rid para identidade interna, _self para do recurso, _etag para concorrência otimista, _ts para a última atualização em tempo Unix e o caminho legado _attachments.
A indexação automática agiliza consultas flexíveis, porém acrescenta custo de gravação. Tamanho do item, quantidade de propriedades, política de índice, consistência, filtros, ordenação, agregação, projeção e número de partições alteram as RUs. Uma leitura pontual de 1 KB custa aproximadamente 1 RU; agregações entre partições podem custar muito mais. Leia x-ms--charge e acompanhe ou insights do Cosmos DB.
Resumo do tópico
Use ids e do sistema deliberadamente e meça a cobrança de RUs em vez de estimar por intuição.
6. Conectar pelo e escolher a autenticação de produção
Existem SDKs oficiais para .NET, Python, JavaScript, Java e Go. CosmosClient é o ponto de entrada e administra conexões, roteamento, e atualização de . O pacote -cosmos do Python segue os mesmos conceitos dos demais SDKs.
Chaves de conta são segredos compartilhados com acesso amplo. As chaves primária e secundária permitem rotação, mas são difíceis de limitar e auditar. Em produção, prefira com de privilégio mínimo para usuários, grupos, entidades de serviço ou identidades gerenciadas. Cosmos DB Built-in Data Reader concede leitura; Cosmos DB Built-in Data Contributor concede leitura/gravação. DefaultAzureCredential usa ou localmente e quando implantado.
Crie CosmosClient com o da conta e prefira com limitado a distribuir chaves.
7. Reutilizar clientes e criar recursos de forma idempotente
Mantenha uma única instância de CosmosClient durante a aplicação. Recriá-la em cada solicitação perde pools e roteamento em , aumenta a variação de latência e pode esgotar conexões. No Flask ou FastAPI, inicialize no startup e reutilize clientes de banco e contêiner.
get_database_client() e get_container_client() devolvem referências leves sem validar a rede. create_database() e create_container() falham se o identificador já existir; as variantes *_if_not_exists tornam startup e testes idempotentes. O contêiner exige PartitionKey; offer_throughput define capacidade manual e ThroughputProperties configura escala automática.
Reutilize um cliente único, reconheça referências preguiçosas e escolha conscientemente criação estrita ou idempotente.
8. Criar, fazer upsert, substituir e proteger atualizações concorrentes
create_item() insere um item e retorna 409 se o mesmo id e chave já existirem. upsert_item() insere ou substitui, adequado a atualização de e sincronização. replace_item() exige um registro existente e mantém a ausência como erro.
_etag muda a cada alteração. Envie o valor lido em if_match durante a substituição; divergência gera CosmosAccessConditionFailedError e prova que outro processo modificou o item. Releia e reavalie a atualização em vez de apagar silenciosamente dados recentes.
from azure.cosmos import exceptions
item = chunks.read_item(item="policy-42-chunk-3", partition_key="contoso")
item["reviewed"] = True
try:
chunks.replace_item(
item=item["id"],
body=item,
if_match=item["_etag"]
)
except exceptions.CosmosAccessConditionFailedError:
print("The item changed; read it again before retrying.")
Resumo do tópico
Use create para unicidade, upsert para inserir ou substituir e replace com _etag para impedir perda de atualizações.
9. Preferir leituras pontuais e registrar de resposta
read_item() oferece a menor latência e cobrança para um documento conhecido, pois id e chave roteiam diretamente à partição lógica. Modele identificadores para perfis, inferências em e configurações frequentes. Trate CosmosResourceNotFoundError para calcular um miss, devolver padrão ou comunicar ausência.
delete_item() também exige id e chave. O item removido deixa de ocupar armazenamento, embora a operação consuma RUs. Registre x-ms--charge e x-ms-activity-id. O identificador de atividade ajuda a correlacionar falhas com o suporte Microsoft.
Resumo do tópico
Quando id e chave forem conhecidos, use read_item ou delete_item e registre RUs e activity ID.
10. Criar consultas SELECT e WHERE sobre documentos
A linguagem lembra SQL, mas opera em um contêiner e percorre propriedades . FROM introduz o alias, SELECT define o formato e WHERE filtra. Projete somente os campos consumidos pela IA para reduzir resposta e processamento.
Use =, !=, <, >, <= e >= para comparação.
Combine predicados com AND, OR e NOT.
Aplique CONTAINS, STARTSWITH, ENDSWITH, UPPER e LOWER a textos.
Use BETWEEN para intervalos e IN ou NOT IN para conjuntos.
Lembre que comparação textual distingue maiúsculas por padrão.
O iterador pode executar várias solicitações ao consumir resultados. SELECT * é prático para inspeção, mas raramente é o melhor contrato de uma de inferência ou recuperação.
Resumo do tópico
Filtre com a linguagem semelhante a SQL e devolva uma projeção deliberada, considerando a execução paginada.
11. Parametrizar valores e rotear para uma partição
Nunca concatene entrada externa ao texto da consulta. Parâmetros @ mantêm estrutura e dados separados, evitam injeção e permitem reutilizar planos. Informe partition_key quando conhecida; um predicado de igualdade também favorece o roteamento.
query = """
SELECT c.id, c.sourceId, c.text
FROM c
WHERE c.tenantId = @tenant AND c.sourceId = @source
ORDER BY c.position
"""
parameters = [
{"name": "@tenant", "value": "contoso"},
{"name": "@source", "value": "policy-42"}
]
results = chunks.query_items(
query=query,
parameters=parameters,
partition_key="contoso",
max_item_count=25
)
Consultas entre partições fazem fan-out quando a chave não pode ser deduzida. Para buscas globais, habilite enable_cross_partition_query=True e monitore latência e RUs. Aumentar a taxa pode reduzir limitação, mas não corrige uma consulta que ignora uma chave disponível.
Resumo do tópico
Parametrize toda entrada externa e direcione a consulta a uma partição sempre que o padrão fornecer a chave.
12. Ordenar, paginar, moldar, agregar e medir consultas
ORDER BY ordena em sentido crescente ou decrescente e pode exigir índice correspondente. Em grandes conjuntos, use max_item_count e percorra páginas; uma pode devolver o de continuação opaco. Páginas maiores reduzem viagens e páginas menores economizam memória.
Projeções renomeiam campos, calculam expressões, criam aninhado ou usam VALUE para desembrulhar escalares e arrays. COUNT, SUM, AVG, MIN e MAX resumem, mas podem varrer muitos itens. ARRAY_CONTAINS testa associação; JOIN ... IN achata elementos de arrays.
SELECT VALUE {
"chunkId": c.id,
"content": c.text,
"hasEmbedding": IS_DEFINED(c.embedding)
}
FROM c
WHERE c.tenantId = @tenant
SELECT COUNT(1) AS totalChunks, MAX(c.position) AS lastPosition
FROM c
WHERE c.tenantId = @tenant AND c.sourceId = @source
SELECT c.id, tag
FROM c
JOIN tag IN c.tags
WHERE tag IN ("security", "governance")
Filtre cedo e de forma restritiva.
Retorne apenas propriedades usadas.
Use a chave e TOP quando possível.
Alinhe índices, inclusive compostos, às consultas medidas.
Leia x-ms--charge por página e examine métricas de consulta e índice.
Resumo do tópico
Controle tamanho, roteamento, paginação, projeção, agregação, arrays e índices enquanto mede o custo real.
13. Laboratório guiado: criar um repositório RAG
O exercício de aproximadamente 30 minutos provisiona conta, banco e contêiner do for para documentos divididos em fragmentos. Cada fragmento leva consultados antes de fornecer contexto fundamentado ao modelo de linguagem. Funções Python armazenam e recuperam dados, e um aplicativo Flask valida o fluxo pela SQL do Cosmos DB.
Baixe o projeto inicial e revise a implantação.
Implante conta, banco, contêiner e estratégia de partição.
Implemente funções Python de gravação e recuperação.
Consulte o contexto relevante e entregue-o à aplicação RAG.
Teste a interface Flask e remova recursos cobrados.
Pré-requisitos: assinatura do com permissão, , atual e Python 3.12 ou posterior.
O banco compõe a camada de recuperação; relevância e partição determinam a eficiência da montagem do contexto.
Resumo do tópico
O laboratório conecta esquema, implantação, do Python, consulta SQL e cliente Flask em um padrão RAG funcional.
