SystemTce/dify-skills

SKILL de Design de Workflows Dify

Domine o conhecimento central e as melhores práticas de design de workflows do Dify

Navegação Rápida

• Visão Geral do Workflow
• Tipos de Nós Principais
• Padrões de Design
• Templates de Workflow
• Sistema de Variáveis
• Melhores Práticas

---

Visão Geral do Workflow

O workflow do Dify é um sistema visual de orquestração de aplicações de IA, que combina nós e arestas para implementar lógicas de negócio complexas.

Conceitos Principais

• Nó (Node): Unidade básica de execução do workflow; cada nó executa uma função específica.
• Aresta (Edge): Conecta nós, definindo o fluxo de dados e a ordem de execução.
• Variável (Variable): Transmite dados entre nós.
• DSL (Domain Specific Language): Linguagem de definição de workflow no formato YAML.

Tipos de Workflow

1. Workflow: Workflow padrão, adequado para processamento complexo em várias etapas.
2. Advanced Chat: Aplicação de chat avançada, com suporte a orquestração por workflow.
3. Agent: Agente inteligente, com tomada de decisão autônoma e chamada de ferramentas.

Modelo de Execução

• Orientado a Fila: Agendamento de nós baseado em Ready Queue.
• Orientado a Eventos: A execução dos nós gera um fluxo de eventos.
• Execução Paralela: Suporte a 2 a 8 threads de trabalho para processamento paralelo.
• Resposta em Streaming: Suporte a saída em streaming em tempo real.

---

Tipos de Nós Principais

1. Nó Start

Função: Ponto de entrada do workflow, define as variáveis de entrada.

Exemplo de Configuração:

- data:
    desc: ''
    selected: false
    title: Início
    type: start
    variables:
    - label: Entrada do Usuário
      max_length: 1000
      required: true
      type: text-input
      variable: user_input
  id: start
  type: custom

Documentação Detalhada: nodes/start.md

---

2. Nó LLM

Função: Invoca modelos de linguagem de grande porte para raciocínio e geração.

Exemplo de Configuração:

- data:
    type: llm
    model:
      provider: openai
      name: gpt-4
      completion_params:
        temperature: 0.7
        max_tokens: 2000
    prompt_template:
    - id: system
      role: system
      text: "Você é um assistente profissional"
    - id: user
      role: user
      text: "{{#sys.query#}}"
    context:
      enabled: true
      variable_selector: ["knowledge", "result"]
  id: llm

Parâmetros Principais:

• model: Configuração do modelo (provedor, nome, parâmetros)
• prompt_template: Template do prompt (suporta mensagens de sistema e do usuário)
• context: Configuração de contexto (habilita resultado da recuperação da base de conhecimento)
• memory: Configuração de memória de conversação
• vision: Configuração de capacidade visual (suporta entrada de imagens)

Documentação Detalhada: nodes/llm.md

---

3. Nó Agent

Função: Agente inteligente que invoca ferramentas de forma autônoma de acordo com as necessidades do usuário.

Exemplo de Configuração:

- data:
    type: agent
    agent_parameters:
      instruction:
        type: constant
        value: "De acordo com a necessidade do usuário, invoque a ferramenta adequada para concluir a tarefa"
      model:
        type: constant
        value:
          provider: openai
          model: gpt-4
          completion_params:
            temperature: 0.7
      query:
        type: constant
        value: "{{#sys.query#}}"
      tools:
        type: constant
        value:
        - enabled: true
          provider_name: time
          tool_name: current_time
          type: builtin
        - enabled: true
          provider_name: duckduckgo
          tool_name: ddgo_search
          type: builtin
    agent_strategy_name: function_calling
  id: agent

Estratégias Suportadas:

• function_calling: Chamada de função (recomendado)
• react: Modo de raciocínio ReAct

Documentação Detalhada: nodes/agent.md

---

4. Nó Knowledge Retrieval

Função: Recupera informações relevantes da base de conhecimento (RAG).

Exemplo de Configuração:

- data:
    type: knowledge-retrieval
    dataset_ids:
    - "dataset-uuid-1"
    - "dataset-uuid-2"
    query_variable_selector: ["start", "sys.query"]
    retrieval_mode: single
    single_retrieval_config:
      model:
        provider: openai
        name: text-embedding-3-small
      top_k: 3
      score_threshold: 0.7
      reranking_model:
        provider: cohere
        model: rerank-english-v2.0
  id: knowledge

Modos de Recuperação:

• single: Recuperação única
• multiple: Recuperação múltipla

Documentação Detalhada: nodes/knowledge-retrieval.md

---

5. Nó Code

Função: Executa código Python ou JavaScript.

Exemplo de Configuração:

- data:
    type: code
    code_language: python3
    code: |
      def main(input_text: str) -> dict:
          # Lógica de processamento
          result = input_text.upper()
          return {
              "output": result,
              "length": len(result)
          }
    variables:
    - variable: input_text
      value_selector: ["start", "user_input"]
    outputs:
      output:
        type: string
      length:
        type: number
  id: code

Linguagens Suportadas:

• Python 3
• JavaScript (Node.js)

Documentação Detalhada: nodes/code.md

---

6. Nó HTTP Request

Função: Invoca APIs HTTP externas.

Exemplo de Configuração:

- data:
    type: http-request
    method: POST
    url: "https://api.example.com/endpoint"
    headers:
      Content-Type: application/json
      Authorization: "Bearer {{#env.API_KEY#}}"
    body:
      type: json
      data:
        query: "{{#sys.query#}}"
        options:
          temperature: 0.7
    timeout: 30
  id: http

Métodos Suportados:

• GET, POST, PUT, DELETE, PATCH

Documentação Detalhada: nodes/http-request.md

---

7. Nó Tool

Função: Invoca ferramentas internas ou personalizadas.

Exemplo de Configuração:

- data:
    type: tool
    provider_id: google_translate
    provider_type: builtin
    provider_name: google_translate
    tool_name: translate
    tool_parameters:
      content:
        type: mixed
        value: "{{#sys.query#}}"
      dest:
        type: mixed
        value: "pt-BR"
  id: tool

Tipos de Ferramenta:

• builtin: Ferramenta interna
• api: Ferramenta de API
• workflow: Ferramenta de workflow

Documentação Detalhada: nodes/tool.md

---

8. Nó If-Else

Função: Controle de ramificação condicional.

Exemplo de Configuração:

- data:
    type: if-else
    conditions:
    - variable_selector: ["llm", "text"]
      comparison_operator: contains
      value: "palavra-chave"
    logical_operator: and
  id: condition

Operadores Suportados:

• contains, not contains
• is, is not
• empty, not empty
• >, <, >=, <=, =, !=

Documentação Detalhada: nodes/if-else.md

---

9. Nó Iteration

Função: Processa dados de array de forma iterativa.

Exemplo de Configuração:

- data:
    type: iteration
    iterator_selector: ["start", "items"]
    output_selector: ["iteration_inner", "output"]
    parallel_nums: 3
    error_handle_mode: continue
  id: iteration

Modos de Tratamento de Erro:

• continue: Continua a execução
• stop: Interrompe a iteração

Documentação Detalhada: nodes/iteration.md

---

10. Nó Answer

Função: Gera a saída do resultado do workflow.

Exemplo de Configuração:

- data:
    type: answer
    answer: "{{#llm.text#}}"
  id: answer

Documentação Detalhada: nodes/answer.md

---

Padrões de Design

1. Padrão de Pipeline Sequencial

Cenário de Uso: Fluxo de processamento linear simples.

Estrutura:

Start → LLM → Answer

Exemplo: patterns/sequential.md

---

2. Padrão de Ramificação Condicional

Cenário de Uso: Executa diferentes lógicas de processamento com base em condições.

Estrutura:

Start → LLM → If-Else → [Ramo A / Ramo B] → Answer

Exemplo: patterns/conditional.md

---

3. Padrão de Processamento Iterativo

Cenário de Uso: Processamento em lote de dados em array.

Estrutura:

Start → Code → Iteration → LLM → Answer

Exemplo: patterns/iterative.md

---

4. Padrão de Recuperação de Conhecimento (RAG)

Cenário de Uso: Perguntas e respostas baseadas em base de conhecimento.

Estrutura:

Start → Knowledge Retrieval → LLM (com contexto) → Answer

Exemplo: patterns/rag.md

---

5. Padrão de Agregação Multi-Fonte

Cenário de Uso: Integra informações de múltiplas fontes de dados.

Estrutura:

Start → [Tool1, Tool2, HTTP] → Agregador de Variáveis → LLM → Answer

Exemplo: patterns/aggregation.md

---

Templates de Workflow

Pergunta e Resposta Simples

Arquivo: templates/simple-qa.yml

Descrição: Workflow de perguntas e respostas mais básico.

Nós: Start → LLM → Answer

---

Assistente RAG

Arquivo: templates/rag-assistant.yml

Descrição: Assistente inteligente baseado em base de conhecimento.

Nós: Start → Knowledge Retrieval → LLM → Answer

---

Chamada de Ferramentas do Agent

Arquivo: templates/agent-tools.yml

Descrição: Agente inteligente que invoca ferramentas de forma autônoma.

Nós: Start → Agent → Answer

---

Processamento em Múltiplas Etapas

Arquivo: templates/multi-step.yml

Descrição: Fluxo de processamento complexo em várias etapas.

Nós: Start → Code → HTTP → LLM → If-Else → Answer

---

Sistema de Variáveis

Variáveis de Sistema

{{#sys.query#}}              # Consulta do usuário
{{#sys.files#}}              # Arquivos enviados
{{#sys.conversation_id#}}    # ID da conversa
{{#sys.user_id#}}            # ID do usuário

Variáveis de Nó

{{#ID_do_Nó.campo_de_saída#}}  # Referencia a saída de um nó
{{#llm.text#}}               # Saída de texto do LLM
{{#knowledge.result#}}       # Resultado da recuperação de conhecimento
{{#code.output#}}            # Saída do nó de código

Variáveis de Conversação

{{#conversation.nome_da_variável#}}  # Variável no nível da conversa

Variáveis de Ambiente

{{#env.API_KEY#}}            # Variável de ambiente
{{#env.DATABASE_URL#}}       # Conexão com banco de dados

Variáveis de Iteração

{{#item#}}                   # Item atual da iteração
{{#index#}}                  # Índice atual

---

Melhores Práticas

1. Design Modular

• Divida fluxos complexos em vários nós independentes.
• Use variáveis para transmitir dados, evitando valores fixos.
• Utilize adequadamente nós de ramificação condicional e iteração.

2. Convenção de Nomenclatura de Variáveis

• Use nomes de variáveis significativos.
• Siga uma convenção de nomenclatura consistente.
• Adicione informações descritivas quando necessário.

3. Tratamento de Erros

• Adicione lógica de tratamento de erros nos nós críticos.
• Use ramificações condicionais para lidar com exceções.
• Forneça mensagens de erro amigáveis.

4. Otimização de Desempenho

• Evite chamadas desnecessárias a nós.
• Utilize mecanismos de cache de forma adequada.
• Controle o número de iterações em loops.
• Use ramificações paralelas para melhorar o desempenho.

5. Mantenibilidade

• Adicione descrições e comentários aos nós.
• Use nomes de nós claros.
• Mantenha a estrutura do workflow simples.
• Revise e otimize periodicamente.

Conteúdo Detalhado: best-practices.md

---

Próximos Passos

• Aprofunde-se na Documentação Detalhada dos Tipos de Nó
• Explore os Padrões de Design
• Use os Templates de Workflow para começar rapidamente
• Leia as Melhores Práticas para aprimorar suas habilidades

---

SKILLs Relacionados

• 02-plugin SKILL - Desenvolva ferramentas e plugins personalizados
• 03-performance SKILL - Otimize o desempenho do workflow
• 06-reference SKILL - Referência de sintaxe DSL

---

Versão: v1.0.0 Última Atualização: 2026-03-04 Voltar: SKILL Principal