Compartilhar via

Diretrizes de solução de problemas

  • Artigo

Este artigo aborda perguntas frequentes sobre como usar o prompt flow.

O erro "A ferramenta de pacote não foi encontrada" ocorre quando você atualiza o fluxo para uma experiência de code-first

Ao atualizar os fluxos para uma experiência code-first, se o fluxo utilizou as ferramentas Faiss Index Lookup, Vector Index Lookup, Vector DB Lookup ou Content Safety (Text), você poderá encontrar a seguinte mensagem de erro:

Package tool 'embeddingstore.tool.faiss_index_lookup.search' is not found in the current environment.

Para resolver o problema, você tem duas opções:

  • Opção 1

    • Atualize sua sessão de computação para a versão mais recente da imagem base.

    • Selecione Modo de arquivo bruto para alternar para o modo de exibição de código bruto. Em seguida, abra o arquivo flow.dag.yaml.

      Captura de tela que mostra como alternar para o modo de arquivo bruto.

    • Atualize os nomes das ferramentas.

      Captura de tela que mostra como atualizar o nome da ferramenta.

      Ferramenta Novo nome da ferramenta
      Pesquisa do Índice Faiss promptflow_vectordb.tool.faiss_index_lookup.FaissIndexLookup.search
      Ferramenta de Índice de Vetor promptflow_vectordb.tool.vector_index_lookup.VectorIndexLookup.search
      Pesquisa do BD de Vetor promptflow_vectordb.tool.vector_db_lookup.VectorDBLookup.search
      Segurança de Conteúdo (Texto) content_safety_text.tools.content_safety_text_tool.analyze_text

    • Salve o arquivo flow.dag.yaml.

  • Opção 2

    • Atualize sua sessão de computação para a versão mais recente da imagem base
    • Remova a ferramenta antiga e recrie outra.

Erro "Nenhum diretório ou arquivo"

O prompt flow depende de um armazenamento de compartilhamento de arquivos para armazenar um instantâneo do fluxo. Se o armazenamento de compartilhamento de arquivos tiver um problema, você poderá encontrar o seguinte problema. Estas são algumas soluções alternativas:

  • Se estiver usando uma conta de armazenamento privada, confira Isolamento de rede no prompt flow para garantir que o workspace possa acessar sua conta de armazenamento.

  • Se a conta de armazenamento estiver habilitada para acesso público, verifique se há um armazenamento de dados chamado workspaceworkingdirectory no workspace. Deve ser um tipo de compartilhamento de arquivo.

    Captura de tela que mostra workspaceworkingdirectory.

    • Se você não obteve esse armazenamento de dados, precisará adicioná-lo ao seu workspace.
      • Crie um compartilhamento de arquivos com o nome code-391ff5ac-6576-460f-ba4d-7e03433c68b6.
      • Crie um armazenamento de dados com o nome workspaceworkingdirectory. Confira Criar armazenamentos de dados.
    • Se você tiver um armazenamento de dados workspaceworkingdirectory, mas seu tipo for blob em vez de fileshare, crie um novo workspace. Use o armazenamento que não habilita namespaces hierárquicos para o Azure Data Lake Storage Gen2 como uma conta de armazenamento padrão do workspace. Para obter mais informações, confira Criar workspace.

O fluxo está ausente

Captura de tela que mostra um fluxo sem uma página de criação.

Há possíveis motivos para esse problema:

  • Se o acesso público à sua conta de armazenamento estiver desabilitado, você deverá garantir o acesso adicionando seu IP ao firewall de armazenamento ou habilitando o acesso por meio de uma rede virtual que tenha um ponto de extremidade privado conectado à conta de armazenamento.

    Captura de tela que mostra a configuração de firewall na conta de armazenamento.

  • Há alguns casos, a chave da conta no armazenamento de dados está fora de sincronia com a conta de armazenamento, você pode tentar atualizar a chave da conta na página de detalhes do armazenamento de dados para corrigir isso.

    Captura de tela que mostra o armazenamento de dados com a chave de conta errada.

  • Se você estiver usando o Azure AI Foundry, a conta de armazenamento precisará definir o CORS para permitir que o Azure AI Foundry acesse a conta de armazenamento, caso contrário, você verá o problema de fluxo ausente. Você pode adicionar as seguintes configurações de CORS à conta de armazenamento para corrigir esse problema.

    • Acesse a página da conta de armazenamento, selecione Resource sharing (CORS) em settings e selecione a guia File service.
    • Origens permitidas: https://mlworkspace.azure.ai,https://ml.azure.com,https://*.ml.azure.com,https://ai.azure.com,https://*.ai.azure.com,https://mlworkspacecanary.azure.ai,https://mlworkspace.azureml-test.net
    • Métodos permitidos: DELETE, GET, HEAD, POST, OPTIONS, PUT

    Captura de tela que mostra a configuração de compartilhamento de recursos da conta de armazenamento.

Falha na execução devido a "Nenhum módulo chamado XXX"

Esse tipo de erro está relacionado à falta dos pacotes necessários na sessão de computação. Se estiver usando um ambiente padrão, verifique se a imagem da sua sessão de computação está usando a versão mais recente. Se você estiver usando uma imagem base personalizada, verifique se instalou todos os pacotes necessários no contexto do Docker. Para obter mais informações, confira Personalizar imagem base para a sessão de computação.

Onde encontrar a instância sem servidor usada pela sessão de computação?

Você pode exibir a instância sem servidor usada pela sessão de computação na guia da lista de sessões de computação na página de computação. Saiba mais sobre como gerenciar instâncias sem servidor.

Falhas de sessão de computação usando imagem base personalizada

Falha no início da sessão de computação com requirements.txt ou imagem base personalizada

Suporte à sessão de computação para usar requirements.txt ou uma imagem base personalizada em flow.dag.yaml para personalizar a imagem. É recomendável usar requirements.txt para um caso comum, que usará pip install -r requirements.txt para instalar os pacotes. Se você tiver mais de uma dependência de pacotes python, precisará seguir a imagem base personalizada para criar uma nova imagem base sobre a imagem base do prompt flow. Em seguida, use-a em flow.dag.yaml. Saiba mais sobre como especificar a imagem base na sessão de computação.

  • Você não pode usar a imagem base arbitrária para criar uma sessão de computação, você precisa usar a imagem base fornecida pelo fluxo de prompt.
  • Não fixe a versão de promptflow e promptflow-tools em requirements.txt, porque já as incluímos na imagem base. Usar a versão antiga de promptflow e promptflow-tools pode causar um comportamento inesperado.

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

No prompt flow, na página de fluxo com execução bem-sucedida e na página de detalhes da execução, é possível encontrar as entradas e saídas brutas da ferramenta LLM na seção de saída. Selecione o botão view full output para exibir a saída completa.

Captura de tela que mostra a exibição da saída completa no nó LLM.

A seção Trace 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.

Captura de tela que mostra a solicitação bruta enviada ao modelo LLM e a resposta do modelo LLM.

Como corrigir o erro 409 do OpenAI do Azure?

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

Captura de tela que mostra o erro de limite de taxa 429 do OpenAI do Azure.

Identificar qual nó consome mais tempo

  1. Verifique os logs de sessão de computação.

  2. Tente localizar o seguinte formato de log de aviso:

    {node_name} está em execução há {duration} segundos.

    Por exemplo:

    • Caso 1: nó de script Python em execução por muito tempo.

      Captura de tela que mostra uma entrada de execução de tempo limite na interface do usuário do estúdio.

      Nesse caso, você pode descobrir que PythonScriptNode ficou em execução por muito tempo (quase 300 segundos). Em seguida, você pode verificar os detalhes do nó para ver qual é o problema.

    • Caso 2: nó LLM em execução por muito tempo.

      Captura de tela de logs de tempo limite causados pelo tempo limite do LLM na interface do usuário do estúdio.

      Nesse caso, se você encontrar a mensagem request canceled nos logs, ela poderá ser devido à chamada à API do OpenAI demorar muito e exceder o tempo limite.

      Um tempo limite da API do OpenAI pode ser causado por um problema de rede ou por uma solicitação complexa que exige mais tempo de processamento. Para obter mais informações, confira Tempo limite da API do OpenAI.

      Aguarde alguns segundos e tente solicitar novamente. Essa ação geralmente resolve os problemas de rede.

      Se a nova tentativa não funcionar, verifique se você está usando um modelo de contexto longo, como gpt-4-32k, e se definiu 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, é recomendável tentar Bulk test, pois esse modo não tem uma configuração de tempo limite.

  3. Se não conseguir encontrar nada nos logs que indique que é um problema específico do nó:

    • Entre em contato com a equipe do prompt flow (promptflow-eng) com os logs. Tentamos identificar a causa raiz.

Autorização ausente para executar a ação "Microsoft.MachineLearningService/workspaces/datastores/read"

Se o fluxo contiver a ferramenta Pesquisa de Índice, depois de implantá-lo, o ponto de extremidade precisará acessar o armazenamento de dados do workspace para ler o arquivo YAML MLIndex ou a pasta FAISS que contém partes e incorporações. Portanto, você precisa conceder manualmente a permissão de identidade de ponto de extremidade para fazer isso.

Você pode conceder a identidade de ponto de extremidade Cientista de Dados do AzureML no escopo do espaço de trabalho ou uma função personalizada que contenha a ação "MachineLearningService/workspace/datastore/reader".

Problema de tempo limite da solicitação upstream ao consumir o ponto de extremidade

Se você usar CLI ou SDK para implantar o fluxo, poderá encontrar um erro de tempo limite. Por padrão, o request_timeout_ms é 5.000. Você pode especificar no máximo até 5 minutos, que é de 300.000 ms. Veja a seguir um exemplo mostrando como especificar o tempo limite da solicitação no arquivo yaml de implantação. Para saber mais, consulte esquema de implantação.

request_settings:
  request_timeout_ms: 300000

API OpenAI atinge erro de autenticação

Se você regenerar sua chave do Azure OpenAI e atualizar manualmente a conexão usada no prompt flow, poderá encontrar erros como "Não autorizado. O token de acesso está ausente, inválido, o público está incorreto ou expirou." ao invocar um ponto de extremidade existente criado antes da regeneração da chave.

Isso ocorre porque as conexões usadas nos pontos de extremidade/implantações não serão atualizadas automaticamente. Qualquer alteração de chave ou segredos nas implantações deve ser feita por atualização manual, que visa evitar o impacto na implantação de produção on-line devido à operação offline não intencional.

  • Se o ponto de extremidade foi implantado na interface do usuário do estúdio, você pode simplesmente reimplantar o fluxo para o ponto de extremidade existente usando o mesmo nome de implantação.
  • Se o ponto de extremidade foi implantado usando SDK ou CLI, você precisará fazer alguma modificação na definição de implantação, como adicionar uma variável de ambiente fictícia e, em seguida, usar az ml online-deployment update para atualizar sua implantação.

Problemas de vulnerabilidade em implantações de prompt flow

Para vulnerabilidades relacionadas ao tempo de execução de fluxo imediato, a seguir estão as abordagens, que podem ajudar a atenuar:

  • Atualize os pacotes de dependência em seu requirements.txt em sua pasta de fluxo.
  • Se você estiver usando uma imagem base personalizada para seu fluxo, precisará atualizar o tempo de execução do prompt flow para a versão mais recente e reconstruir sua imagem base e, em seguida, reimplantar o fluxo.

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

"Erro 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 pode 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) Você pode encontrar o uri da imagem do contêiner na página de detalhes do ambiente personalizado e defini-lo como a imagem base do fluxo no arquivo flow.dag.yaml. Quando você for implantar o fluxo na interface do usuário, basta selecionar Usar ambiente da definição de fluxo atual, e o serviço de atendimento ao consumido criará o ambiente personalizado com base nessa imagem de base e requirement.txt para sua implantação. Saiba mais sobre o ambiente especificado na definição de fluxo.

    Captura de tela da página de detalhes do ambiente personalizado.

    Captura de tela da especificação da imagem base no arquivo YAML bruto do fluxo.

  • Você pode corrigir esse erro adicionando inference_config em sua definição de ambiente personalizado.

    A seguir, um exemplo de definição de ambiente personalizado.

$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

Resposta do modelo demorando muito

Às vezes, você pode notar que a implantação está demorando muito para responder. Há vários fatores potenciais para que isso ocorra.

  • O modelo usado no fluxo não é poderoso o suficiente (exemplo: use GPT 3.5 em vez de text-ada)
  • A consulta de índice não está otimizada e demorando muito
  • O Flow tem muitas etapas para processar

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

Não é possível buscar o esquema de implantação

Depois de implantar o ponto de extremidade e desejar testá-lo na guia Teste na página de detalhes do ponto de extremidade, se a guia Teste mostrar Não é possível buscar o esquema de implantação, você poderá tentar os dois métodos a seguir para atenuar esse problema:

Captura de tela do erro Não foi possível buscar o esquema de implantação na guia Teste da página de detalhes do ponto de extremidade.

Acesso negado para listar o segredo do workspace

Se você encontrar um erro como "Acesso negado para listar o segredo do workspace", verifique se concedeu a permissão correta à identidade do ponto de extremidade. Saiba mais sobre como conceder permissão à identidade do ponto de extremidade.

Como uso o armazenamento de dados sem credenciais no fluxo de prompt?

Para usar o armazenamento sem credenciais no portal do Azure AI Foundry, você precisa basicamente fazer o seguinte:

  • Altere o tipo de autenticação do armazenamento de dados para Nenhum.
  • Conceda MSI do projeto e permissão de colaborador de dados de blob/arquivo do usuário no armazenamento.

Alterar o tipo de autenticação do armazenamento de dados para Nenhum

Você pode seguir a autenticação de dados baseada em identidade nesta parte para tornar seu armazenamento de dados sem credenciais.

Você precisa alterar o tipo de autenticação do armazenamento de dados para Nenhum, que significa autenticação baseada em meid_token. Você pode fazer alterações na página de detalhes do armazenamento de dados ou na CLI/SDK: https://github.com/Azure/azureml-examples/tree/main/cli/resources/datastore

Captura de tela do tipo de autenticação para armazenamento de dados.

Para armazenamento de dados baseado em blob, você pode alterar o tipo de autenticação e também habilitar o MSI do workspace para acessar a conta de armazenamento.

Captura de tela do tipo de autenticação de atualização para armazenamento de dados baseado em blob.

Para armazenamento de dados baseado em compartilhamento de arquivos, você pode alterar apenas o tipo de autenticação.

Captura de tela do tipo de autenticação de atualização para armazenamento de dados baseado em compartilhamento de arquivos.

Conceder permissão a identidade do usuário ou identidade gerenciada

Para usar o armazenamento de dados sem credenciais no fluxo de prompt, você precisa conceder permissões suficientes à identidade do usuário ou à identidade gerenciada para acessar o armazenamento de dados.

  • Verifique se a identidade gerenciada atribuída pelo sistema de workspace tem Storage Blob Data Contributor e Storage File Data Privileged Contributor , na conta de armazenamento, pelo menos precisa de permissão de leitura/gravação (melhor incluir também a exclusão).
  • Se você estiver usando a identidade do usuário com essa opção padrão no fluxo de prompt, precisará verificar se a identidade do usuário tem a seguinte função na conta de armazenamento:
    • Storage Blob Data Contributor Na conta de armazenamento, pelo menos precisa de permissão de leitura/gravação (melhor incluir também a exclusão).
    • Storage File Data Privileged Contributor Na conta de armazenamento, pelo menos precisa de permissão de leitura/gravação (melhor incluir também a exclusão).
  • Se você estiver usando a identidade gerenciada atribuída pelo usuário, precisará verificar se a identidade gerenciada tem a seguinte função na conta de armazenamento:
    • Storage Blob Data Contributor Na conta de armazenamento, pelo menos precisa de permissão de leitura/gravação (melhor incluir também a exclusão).
    • Storage File Data Privileged Contributor Na conta de armazenamento, pelo menos precisa de permissão de leitura/gravação (melhor incluir também a exclusão).
    • Enquanto isso, você precisa atribuir a função de identidade Storage Blob Data Read do usuário à conta de armazenamento, pelo menos, se quiser usar o fluxo de prompt para o fluxo de criação e teste.
  • Se você ainda não conseguir exibir a página de detalhes do fluxo e a primeira vez que usar o fluxo de prompt for anterior a 2024-01-01, será necessário conceder o MSI do workspace como Storage Table Data Contributor a conta de armazenamento vinculada ao workspace.