Orientação de solução de problemas para fluxo rápido

2025-06-20

Este artigo aborda perguntas frequentes sobre o uso do prompt flow.

Por que a execução falhou com a mensagem de erro "Nenhum módulo chamado XXX"?

Esse tipo de erro está relacionado a uma sessão de computação que não tem pacotes necessários. Se você usar um ambiente padrão, verifique se a imagem da sessão de computação usa a versão mais recente. Se você usar uma imagem base personalizada, verifique se instalou todos os pacotes necessários no contexto do Docker.

Como encontrar a instância sem servidor usada por uma sessão de computação?

Você pode ver a instância sem servidor usada por uma sessão de computação na guia de lista de sessões de computação na página de computação. Para saber mais sobre como gerenciar uma instância sem servidor, consulte Gerenciar uma sessão de computação.

Como encontrar as entradas brutas e as saídas da ferramenta LLM para uma investigação mais aprofundada?

Em um prompt flow, em uma página de fluxo com uma página de execução bem-sucedida e de detalhes de execução, você pode encontrar as entradas e saídas brutas da ferramenta LLM na seção de saída. Selecione Exibir saída completa para exibir a saída completa.

A seção Rastreamento inclui cada solicitação e resposta à ferramenta LLM. Você pode verificar a mensagem bruta enviada ao modelo LLM e a resposta bruta do modelo LLM.

Como corrigir um erro 429 do Azure OpenAI?

Você pode encontrar um erro 429 do Azure OpenAI. Esse erro significa que você atingiu o limite de taxa do Azure OpenAI. Você pode verificar a mensagem de erro na seção de saída do nó LLM. Para saber mais sobre o limite de taxa, consulte o limite de taxa do Azure OpenAI.

Como identificar qual nó consome mais tempo?

Verifique os logs de sessão de computação.
Tente encontrar o seguinte formato de log de aviso: <node_name> has been running for <duration> seconds.

Por exemplo:
- Caso 1: nó de script Python em execução por muito tempo.
  
  Nesse caso, você pode ver que PythonScriptNode estava em execução por um longo tempo (quase 300 segundos). Verifique os detalhes do nó para ver o que está causando o problema.
- Caso 2: o nó LLM é executado por muito tempo.
  
  Se você vir a mensagem request canceled nos logs, pode ser porque a chamada à API do OpenAI está demorando muito e excedendo o tempo limite.
  
  Um problema de rede ou uma solicitação complexa que exige mais tempo de processamento pode fazer com que o OpenAI atinja o tempo limite.
  
  Aguarde alguns segundos e tente solicitar novamente. Essa ação geralmente resolve os problemas de rede.
  
  Se a repetição não funcionar, verifique se você está usando um modelo de contexto longo, como gpt-4-32k, e defina um valor grande para max_tokens. Se for esse o caso, o comportamento é esperado porque sua solicitação pode gerar uma resposta longa que demora mais do que o limite superior do modo interativo. Nessa situação, recomendamos que você tente Bulk test porque esse modo não tem uma configuração de tempo limite.

Como resolver um problema de tempo limite de solicitação upstream?

Se você usar a CLI do Azure ou o SDK para implantar o fluxo, poderá encontrar um erro de timeout. Por padrão, request_timeout_ms é 5000. Você pode especificar um máximo de cinco minutos, que é 300.000 ms. O exemplo a seguir mostra como especificar um tempo limite de solicitação no arquivo .yaml de implantação. Para saber mais, confira o esquema de implantação.

request_settings:
  request_timeout_ms: 300000

O que faço quando a API OpenAI gera um erro de autenticação?

Se você regenerar a chave do OpenAI do Azure e atualizar manualmente a conexão usada em um prompt flow, poderá haver erros como "Não autorizado. O token de acesso está ausente, inválido, o público-alvo está incorreto ou expirou." Você pode ver essas mensagens ao invocar um ponto de extremidade existente que foi criado antes da regeneração da chave.

Este erro ocorre porque as conexões usadas nos endpoints/implantações não são atualizadas automaticamente. Você deve atualizar manualmente qualquer alteração para uma chave ou segredos em implantações, o que visa evitar afetar a implantação de produção online devido à operação offline não intencional.

Se o ponto de extremidade tiver sido implantado no portal do Azure AI Foundry, reimplante o fluxo para o ponto de extremidade existente usando o mesmo nome de implantação.
Se o ponto de extremidade foi implantado usando o SDK ou a CLI do Azure, faça uma modificação na definição de implantação, como adicionar uma variável de ambiente fictícia. Em seguida, use az ml online-deployment update para atualizar a implantação.

Como resolver problemas de vulnerabilidade em implantações de prompt flow?

Para vulnerabilidades relacionadas ao tempo de execução do fluxo de prompt, tente as seguintes abordagens:

Atualize os pacotes de dependência em seu arquivo requirements.txt na pasta do fluxo.
Se você usar uma imagem base personalizada para o seu fluxo, atualize o ambiente de execução do fluxo de prompt para a versão mais recente e reconstrua sua imagem base. Em seguida, reimplante o fluxo.

Para quaisquer outras vulnerabilidades de implantações online gerenciadas, o Azure AI corrige os problemas mensalmente.

O que fazer se receber erros de "MissingDriverProgram" ou "Não foi possível localizar o programa de driver na solicitação"?

Se você implantar seu fluxo e encontrar o seguinte erro, ele poderá estar relacionado ao ambiente de implantação:

'error': 
{
    'code': 'BadRequest', 
    'message': 'The request is invalid.', 
    'details': 
         {'code': 'MissingDriverProgram', 
          'message': 'Could not find driver program in the request.', 
          'details': [], 
          'additionalInfo': []
         }
}

Could not find driver program in the request

Há duas maneiras de corrigir esse erro:

Recomendado: localize o URI da imagem do contêiner na página de detalhes do ambiente personalizado. Defina-a como a imagem base de fluxo no arquivo flow.dag.yaml. Ao implantar o fluxo na interface do usuário, selecione Usar ambiente da definição de fluxo atual. O serviço de back-end cria o ambiente personalizado com base nessa imagem base e requirement.txt para sua implantação. Para obter mais informações, consulte o ambiente especificado na definição de fluxo.
Adicione inference_config na sua definição do ambiente personalizado.

O exemplo a seguir é um exemplo de uma definição de ambiente personalizada.

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: pf-customized-test
build:
  path: ./image_build
  dockerfile_path: Dockerfile
description: promptflow customized runtime
inference_config:
  liveness_route:
    port: 8080
    path: /health
  readiness_route:
    port: 8080
    path: /health
  scoring_route:
    port: 8080
    path: /score

O que fazer se minha resposta de modelo demorar muito?

Talvez você note que a implantação está levando muito tempo para responder. Esse atraso ocorre devido a vários fatores potenciais:

O modelo usado no fluxo não é poderoso o suficiente. (Por exemplo, use GPT 3.5 em vez de text-ada.)
A consulta de índice não é otimizada e leva muito tempo.
O fluxo tem muitas etapas a serem processadas.

Considere otimizar o ponto de extremidade com as considerações anteriores para melhorar o desempenho do modelo.

O que fazer se não conseguir buscar o esquema de implantação?

Depois de implantar o ponto de extremidade, você precisará testá-lo na guia Teste na página de detalhes da implantação. Para acessar a guia Teste , no painel esquerdo, em Meus ativos, selecione Modelos + pontos de extremidade. Em seguida, selecione a implantação para exibir os detalhes. Se a guia Teste mostrar Não é possível buscar o esquema de implantação, tente os dois métodos a seguir para atenuar esse problema.

Certifique-se de conceder a permissão correta à identidade do ponto de extremidade. Para obter mais informações, confira como conceder permissão à identidade do ponto de extremidade.
Talvez você tenha executado o fluxo em um runtime de versão antiga e, em seguida, implantado o fluxo, de modo que a implantação usou o ambiente do runtime que era a versão antiga. Para atualizar o runtime, siga as etapas em Atualizar um runtime na interface do usuário. Reexecute o fluxo no ambiente de execução mais recente e, em seguida, implante novamente o fluxo.

O que fazer se eu receber um erro "Acesso negado para listar o segredo do workspace"?

Se você encontrar um erro como "Acesso negado ao listar o segredo do espaço de trabalho", verifique se você concedeu a permissão correta à identidade do endpoint. Para obter mais informações, confira como conceder permissão à identidade do ponto de extremidade.