SystemTce/dify-skills

SKILL de Referencia de Dify

Consulta referencias sobre sintaxis, API, CLI, etc.

Navegación Rápida

• Referencia de sintaxis DSL
• Referencia de API
• Referencia de SDK
• Referencia de CLI
• Preguntas Frecuentes

---

Referencia de sintaxis DSL

Estructura del DSL de flujos de trabajo

version: 0.0.1
graph:
  nodes:
    - id: node_id
      data:
        type: node_type
        # configuración del nodo
  edges:
    - source: source_node_id
      target: target_node_id

Tipos de nodo

Tipo	Descripción	Campos obligatorios
start	Nodo de inicio	variables
llm	Nodo LLM	model, prompt_template
agent	Nodo Agente	agent_parameters
knowledge-retrieval	Recuperación de conocimiento	dataset_ids, query_variable_selector
http-request	Petición HTTP	url, method, headers
code	Ejecución de código	code_type, code
tool	Nodo de herramienta	provider_type, tool_name
if-else	Rama condicional	conditions
iteration	Iteración	iterator_variable_name
loop	Bucle	max_loop_count
answer	Nodo de respuesta	answer

Referencia de variables

# Variables del sistema
{{#sys.query#}}           # Consulta del usuario
{{#sys.files#}}           # Archivos subidos
{{#sys.conversation_id#}} # ID de conversación

# Salidas de nodos
{{#node_id.output_field#}}

# Acceso a arrays
{{#items[0]#}}           # Primer elemento del array
{{#items[-1]#}}          # Último elemento del array

# Propiedades de objetos
{{#object.field#}}       # Propiedad de objeto

Ejemplo completo

workflow:
  graph:
    nodes:
      - id: start
        data:
          type: start
          variables:
            - name: query
              type: text
              required: true

      - id: classify
        data:
          type: question-classifier
          instruction: "Clasificar pregunta del usuario"
          categories:
            - name: technical
              description: Pregunta técnica
            - name: general
              description: Pregunta general

      - id: llm
        data:
          type: llm
          model:
            provider: openai
            name: gpt-4
          prompt_template:
            - role: system
              text: "Eres un asistente"
            - role: user
              text: "{{#start.query#}}"
          context:
            enabled: false

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

    edges:
      - source: start
        target: classify
      - source: classify
        target: llm
        source_handle: general
      - source: llm
        target: answer

---

Referencia de API

Autenticación

Todas las peticiones a la API deben incluir la clave API en la cabecera:

Authorization: Bearer TU_CLAVE_API

Resumen de endpoints

API de Aplicación

Endpoint	Método	Descripción
/v1/chat-messages	POST	Enviar mensaje de chat
/v1/completions	POST	Completar texto
/v1/parameters	GET	Obtener parámetros de la aplicación
/v1/file-upload	POST	Subir archivo

API de Flujo de Trabajo

Endpoint	Método	Descripción
/v1/workflows/run	POST	Ejecutar flujo de trabajo
/v1/workflows/run	GET	Obtener estado de ejecución
/v1/workflows/tasks	GET	Listar tareas

API de Conjuntos de Datos

Endpoint	Método	Descripción
/v1/datasets	GET	Listar conjuntos de datos
/v1/datasets	POST	Crear conjunto de datos
/v1/datasets/{id}/documents	GET	Listar documentos
/v1/datasets/{id}/retrieve	POST	Recuperar conocimiento

Formato de solicitud/respuesta

Solicitud de mensaje de chat

{
  "query": "consulta del usuario",
  "user": "user_123",
  "conversation_id": "ID de conversación opcional",
  "response_mode": "blocking | streaming",
  "files": [
    {
      "type": "image",
      "transfer_method": "remote_url",
      "url": "https://example.com/image.jpg"
    }
  ],
  "retrieval_model": {
    "query": "{{#sys.query#}}",
    "top_k": 3
  }
}

Respuesta de mensaje de chat

{
  "message_id": "msg_xxx",
  "conversation_id": "conv_xxx",
  "answer": "contenido de la respuesta de IA",
  "metadata": {
    "usage": {
      "prompt_tokens": 100,
      "completion_tokens": 50,
      "total_tokens": 150
    },
    "retrieval_resources": [
      {
        "position": 1,
        "document_id": "doc_xxx",
        "content": "contenido del documento relevante..."
      }
    ]
  }
}

Respuestas de error

{
  "code": "invalid_api_key",
  "message": "Invalid API key",
  "status_code": 401
}

Códigos de error comunes:

Código de error	Código HTTP	Descripción
invalid_api_key	401	Clave API no válida
invalid_parameter	400	Parámetro incorrecto
quota_exceeded	403	Cuota excedida
rate_limit_exceeded	429	Límite de velocidad excedido
internal_server_error	500	Error interno del servidor

---

Referencia de SDK

SDK de Python

Instalación

pip install dify-client

Uso básico

from dify_client import DifyClient

# Inicializar cliente
client = DifyClient(
    api_key="app-xxx",
    base_url="https://api.dify.ai/v1"
)

# Enviar mensaje de chat
response = client.chat.messages.create(
    query="Hola",
    user="user_123"
)
print(response.answer)

Respuesta en streaming

from dify_client import DifyClient

client = DifyClient(api_key="app-xxx")

# Chat en streaming
for event in client.chat.messages.stream(
    query="Cuenta un cuento",
    user="user_123"
):
    if event.event == "message":
        print(event.data.answer, end="")

Ejecución de flujo de trabajo

# Ejecutar flujo de trabajo
response = client.workflows.run(
    inputs={"query": "prueba"},
    user="user_123",
    response_mode="blocking"
)
print(response.data.output)

Referencia de clases del SDK

DifyClient

class DifyClient:
    def __init__(self, api_key: str, base_url: str = "https://api.dify.ai/v1"):
        """Inicializar cliente"""
        pass

    @property
    def chat(self) -> ChatClient:
        """Cliente de chat"""
        pass

    @property
    def workflows(self) -> WorkflowClient:
        """Cliente de flujo de trabajo"""
        pass

    @property
    def datasets(self) -> DatasetClient:
        """Cliente de conjunto de datos"""
        pass

ChatClient

class ChatClient:
    def create(self, query: str, user: str, **kwargs) -> ChatMessage:
        """Enviar mensaje de chat (bloqueante)"""
        pass

    def stream(self, query: str, user: str, **kwargs) -> Iterator[ChatEvent]:
        """Enviar mensaje de chat (streaming)"""
        pass

---

Referencia de CLI

Instalación

pip install dify-cli

Resumen de comandos

Comandos de plugins

# Inicializar plugin
  dify plugin init [options]

# Ejecutar plugin
  dify plugin run [options]

# Empaquetar plugin
  dify plugin package [options]

# Publicar plugin
  dify plugin publish [options]

# Listar plugins instalados
  dify plugin list

Comandos de flujo de trabajo

# Exportar flujo de trabajo
  dify workflow export <workflow_id> [options]

# Importar flujo de trabajo
  dify workflow import <file> [options]

# Validar flujo de trabajo
  dify workflow validate <file>

# Ejecutar flujo de trabajo
  dify workflow run <workflow_id> --inputs '{}'

Comandos de aplicación

# Listar aplicaciones
  dify app list

# Obtener información de la aplicación
  dify app info <app_id>

# Desplegar aplicación
  dify app deploy <app_id>

Comandos de variables de entorno

# Listar variables de entorno
  dify env list

# Establecer variable de entorno
  dify env set <key> <value>

# Obtener variable de entorno
  dify env get <key>

# Eliminar variable de entorno
  dify env delete <key>

Descripción de opciones

Opción	Abreviatura	Descripción	Valor por defecto
--api-key	-k	Clave API	Variable de entorno DIFY_API_KEY
--base-url	-b	URL base	https://api.dify.ai/v1
--output	-o	Formato de salida	json
--quiet	-q	Modo silencioso	false
--debug	-d	Modo depuración	false

Ejemplos de uso

# Establecer clave API
  export DIFY_API_KEY="app-xxx"

# Inicializar proyecto de plugin
  dify plugin init my-plugin --template tool

# Ejecutar plugin
  dify plugin run --port 5000

# Exportar flujo de trabajo
  dify workflow export wf_xxx -o workflow.yaml

# Importar flujo de trabajo
  dify workflow import workflow.yaml

---

Preguntas Frecuentes

Relacionadas con la API

P: ¿Cómo obtener una clave API? R: En la consola de Dify -> Configuración -> API, crear una.

P: ¿Cuál es el límite de frecuencia de solicitudes? R: Por defecto 60 solicitudes/minuto, se puede solicitar un aumento.

P: ¿Cómo manejar respuestas en streaming? R: Usar response_mode=streaming y procesar eventos SSE.

Relacionadas con flujos de trabajo

P: ¿Cómo hacer referencia a variables? R: Usar la sintaxis {{#node_id.field#}}.

P: ¿Qué tipos de nodo están soportados? R: Consultar la tabla de tipos de nodo.

P: ¿Cómo manejar bucles? R: Usar nodos iteration o loop.

Relacionadas con plugins

P: ¿Cómo desarrollar un plugin personalizado? R: Consultar el SKILL 02-plugin.

P: ¿Cómo obtiene credenciales un plugin? R: Usar self.runtime_credentials.

---

SKILLs Relacionados

• 01-workflow - Diseño de flujos de trabajo
• 02-plugin - Desarrollo de plugins
• 05-integration - Integración y extensiones

---

Recursos Relacionados

• Documentación oficial de Dify
• Documentación de la API de Dify
• GitHub de Dify

---

Información de versión: v1.0.0 | Última actualización: 2026-03-05