GuidesOneMux

Proteja as chaves da API da OpenAI em um fluxo de perguntas e respostas sobre documentos

Um padrão prático de segurança para responder a perguntas sobre documentos com a OpenAI: separe credenciais, restrinja permissões, oculte dados nos logs e faça a rotação segura das chaves, preservando a atribuição das fontes.

AI

Resumo · TL;DR

Em um aplicativo de perguntas e respostas sobre documentos, mantenha a credencial da aplicação OpenAI em um repositório confiável de segredos no servidor, nunca no navegador, em um sandbox, arquivo de código-fonte ou log. Conceda a cada carga de trabalho apenas o acesso necessário, oculte dados sensíveis nos logs e faça a rotação das credenciais seguindo um procedimento documentado de sobreposição e revogação. Retorne referências às fontes com cada resposta para que os usuários possam verificar as afirmações nos documentos recuperados.

Principais pontos

  • Mantenha a chave da aplicação OpenAI fora do código gerado por agentes e de outros ambientes de execução não confiáveis.
  • Use um projeto dedicado ou uma fronteira de carga de trabalho e conceda apenas as permissões de API necessárias ao aplicativo.
  • Registre IDs de solicitação, tempos e identificadores de fontes, em vez de credenciais, trechos de documentos ou prompts completos.
  • Retorne identificadores de documentos e referências a páginas ou seções junto com as respostas; não trate uma resposta fluente como prova.
  • Faça a rotação implantando uma credencial substituta, verificando o tráfego e, em seguida, revogando a antiga; revogue-a imediatamente se houver suspeita de exposição.
Nesta página (6)

Um sistema de perguntas e respostas sobre documentos precisa fazer bem duas coisas: responder com base no material certo e manter as credenciais fora do fluxo de processamento desse material. A opção mais segura por padrão é fazer com que um servidor confiável da aplicação chame a OpenAI, mantendo a recuperação de conteúdo e o tratamento das citações como partes explícitas do seu próprio fluxo de trabalho. Não coloque a chave da aplicação em um navegador, documento, prompt, repositório de código-fonte ou sandbox acessível a agentes.

Comece definindo uma fronteira de confiança

Um fluxo típico é: o usuário faz uma pergunta; sua aplicação recupera trechos relevantes de um repositório de documentos autorizado; o servidor envia a pergunta e os trechos selecionados à OpenAI; a aplicação retorna a resposta com referências a esses trechos. A chave deve ficar no servidor, em um repositório gerenciado de segredos ou em uma configuração protegida equivalente — não em código enviado ao usuário nem em uma carga de trabalho capaz de inspecionar o próprio ambiente.

As orientações de segurança de sandbox da OpenAI alertam que o código gerado por agentes pode acessar arquivos, credenciais e recursos de rede disponíveis no ambiente de execução. Elas recomendam cargas de trabalho isoladas, ambientes separados quando os dados não devem ser compartilhados, projetos dedicados da OpenAI para aplicações ou cargas de trabalho e manter a chave de API da aplicação fora do ambiente. Também recomendam não incorporar chaves em imagens, código-fonte ou logs. Consulte as orientações de segurança de sandbox da OpenAI.

Em perguntas e respostas sobre documentos, isso significa tratar documentos enviados e código gerado pelo modelo como entradas não confiáveis. Um processo de recuperação deve receber apenas os documentos e as ferramentas necessários para a tarefa. Ele não deve herdar uma credencial irrestrita da aplicação só porque precisa enviar uma pergunta para inferência.

Limite permissões e separe credenciais

Crie um projeto separado ou uma fronteira de credenciais para essa aplicação, em vez de compartilhar uma chave de uso geral entre cargas de trabalho não relacionadas. Aplique as permissões mais restritas disponíveis para as operações de API que sua implementação realmente usa. As orientações da OpenAI citadas especificam api.agents.read e api.agents.write para sessões, api.responses.write para inferência e api.vaults.read e api.vaults.write para o gerenciamento de vaults. Esses são exemplos para os casos de uso documentados da Agents API; não conceda todas as permissões por padrão. Confirme quais permissões são necessárias para as APIs que você realmente chama.

Se um ambiente executor precisar se conectar à OpenAI, o guia descreve o uso de uma chave de ambiente separada para essa conexão. Segundo o guia, essa chave permite conectar ambientes e não pode autorizar outras ações de API. Mantenha-a separada da chave da aplicação. Para serviços de terceiros, mantenha as credenciais na aplicação ou em um proxy confiável; não injete segredos de longa duração em um ambiente onde o código gerado possa lê-los.

Oculte dados nos logs sem perder valor operacional

Os logs ajudam a diagnosticar recuperações vazias, solicitações malsucedidas e citações ausentes, mas prompts e documentos completos podem conter informações pessoais, confidenciais ou comercialmente sensíveis. Registre apenas o que sua equipe precisa para operar o serviço, por exemplo:

  • Um ID de solicitação, data e hora, status e latência.
  • O modelo e a versão da aplicação, se forem úteis para depuração.
  • IDs internos de documentos e referências a páginas ou seções, em vez do texto completo recuperado.
  • Uma categoria de erro com dados ocultos, não cabeçalhos de solicitação nem valores secretos.

Por padrão, nunca registre cabeçalhos de autorização, chaves de API, prompts completos de usuários ou trechos integrais de documentos. Se precisar depurar temporariamente o conteúdo, use um processo controlado e com prazo definido, restrições de acesso e uma data clara para exclusão. Verifique também os sistemas da aplicação, do proxy, de rastreamento e de relatórios de erros: ocultar dados no logger principal da aplicação não sanitiza automaticamente outros pontos de captura.

Um padrão ilustrativo de registro em log é:

log_event(
    request_id="generated-request-id",
    outcome="success",
    retrieved_sources=["policy-17:p4", "handbook-03:section-2"],
    credential="[never include]",
    prompt="[omit or redact]",
    passage_text="[omit or redact]"
)

Este é um pseudocódigo, não um exemplo testado do OpenAI SDK. Adapte-o ao seu sistema de logs e verifique se os segredos são removidos antes que os eventos saiam do processo da aplicação.

Faça da atribuição de fontes parte do contrato da resposta

Não peça ao modelo que invente citações depois de responder. Preserve os metadados das fontes durante a recuperação, associe cada trecho ao ID do documento e à página, seção ou URL correspondente e forneça esses metadados à etapa de geração da resposta. Exija o formato de resposta esperado pela sua aplicação: uma resposta acompanhada de referências extraídas somente do conjunto recuperado. Em seguida, valide as referências no código da aplicação antes de exibi-las.

Se a recuperação não retornar trechos relevantes, informe que os documentos disponíveis não dão suporte a uma resposta ou peça ao usuário que restrinja a pergunta. Se uma afirmação da resposta não puder ser associada a uma fonte retornada, identifique-a como não fundamentada ou omita-a. Uma citação só é útil se o local referenciado existir e contiver evidências para a afirmação. A implementação exata da recuperação e do formato de resposta depende das APIs escolhidas; as orientações de segurança citadas aqui não definem uma implementação de perguntas e respostas sobre documentos nem de citações.

Defina um procedimento de rotação de credenciais

Documente as etapas antes de um incidente. Um procedimento prático é:

  1. Identifique a aplicação, o projeto, a entrada no repositório de segredos e os serviços que usam a credencial atual.
  2. Crie uma credencial substituta com o mesmo acesso mínimo necessário e armazene-a no repositório de segredos aprovado.
  3. Implante a substituta por meio de uma alteração controlada de configuração. Evite exibi-la durante a implantação ou colocá-la em artefatos de build.
  4. Envie uma pergunta de teste pelo fluxo normal. Confirme que a inferência funciona, que as citações continuam resolvendo e que os logs não contêm segredos nem texto de documentos.
  5. Monitore os erros e, depois de confirmar que a substituta está em uso, revogue a credencial antiga. Remova cópias obsoletas dos sistemas de implantação e dos ambientes de desenvolvimento local.
  6. Se houver suspeita de exposição, revogue imediatamente a credencial afetada, investigue o acesso e os logs e emita uma substituta. Não espere pela próxima rotação programada.

As orientações da OpenAI dizem para rotacionar ou revogar as chaves quando necessário e revogar credenciais imediatamente se houver suspeita de exposição. Sua organização deve definir o próprio intervalo de rotação com base nos riscos, nas políticas e nas restrições operacionais; a fonte citada não estabelece uma periodicidade universal.

Lista de verificação antes do lançamento

  • A chave da aplicação fica no servidor e é inacessível a navegadores e ao código gerado por agentes.
  • A carga de trabalho está isolada de forma adequada, com um projeto ou ambiente dedicado quando necessário.
  • As permissões estão limitadas às operações necessárias à aplicação.
  • Os logs excluem chaves, cabeçalhos de autorização, prompts brutos e trechos recuperados completos.
  • As respostas incluem referências validadas aos documentos recuperados.
  • Há uma pessoa responsável capaz de implantar uma credencial substituta e revogar a antiga.

A escolha central do projeto é simples: manter as credenciais fora do ambiente de processamento de documentos e garantir que as citações possam ser rastreadas até as fontes recuperadas. Isso reduz o impacto de uma carga de trabalho comprometida e permite que os usuários verifiquem em que a resposta se baseia.

Perguntas frequentes

Posso colocar uma chave da API da OpenAI em um app de perguntas e respostas sobre documentos baseado em navegador?

Não exponha a chave da aplicação ao código do navegador. Faça as solicitações à OpenAI por meio de um componente confiável no servidor, que obtenha a chave de uma configuração protegida ou de um gerenciador de segredos.

Devo registrar prompts e trechos de documentos recuperados para depurar respostas?

Evite fazer isso por padrão. Prefira IDs de solicitação, status, tempos e identificadores de fontes. Se uma depuração temporária do conteúdo for necessária, restrinja o acesso, defina um prazo para exclusão e garanta que as credenciais nunca sejam capturadas.

Com que frequência devo rotacionar as chaves da API da OpenAI?

As orientações de segurança da OpenAI citadas recomendam rotacionar ou revogar as chaves quando necessário, mas não especificam um intervalo universal. Defina uma periodicidade com base nos riscos e nas políticas da organização e revogue a chave imediatamente se houver suspeita de exposição.

Como posso tornar confiáveis as citações em perguntas e respostas sobre documentos?

Preserve os IDs dos documentos e os metadados de página, seção ou URL durante a recuperação, limite as referências ao conjunto de fontes recuperadas e valide cada referência antes de exibi-la. Não dependa do modelo para inventar citações.

Artigos relacionados