trustgraph/docs/tech-specs/flow-class-definition.es.md

layout	title	parent
default	Especificación de la Definición del Esquema de Flujo	Spanish (Beta)

<<<<<<< HEAD

Especificación de la Definición del Esquema de Flujo

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Resumen

Un esquema de flujo define una plantilla de patrón de flujo de datos completo en el sistema TrustGraph. Cuando se instancia, crea una red interconectada de procesadores que manejan la ingesta de datos, el procesamiento, el almacenamiento y la consulta como un sistema unificado.

Estructura

Una definición de esquema de flujo consta de cinco secciones principales:

1. Sección de Clase

Define procesadores de servicios compartidos que se instancian una vez por esquema de flujo. Estos procesadores manejan las solicitudes de todas las instancias de flujo de esta clase.

Especificación de la Definición de la Hoja de Flujo

Resumen

Una hoja de flujo define una plantilla de patrón de flujo de datos completo en el sistema TrustGraph. Cuando se instancia, crea una red interconectada de procesadores que manejan la ingesta de datos, el procesamiento, el almacenamiento y la consulta como un sistema unificado.

Estructura

Una definición de hoja de flujo consta de cinco secciones principales:

1. Sección de Clase

Define procesadores de servicios compartidos que se instancian una vez por hoja de flujo. Estos procesadores manejan las solicitudes de todas las instancias de flujo de esta clase.

82edf2d (New md files from RunPod)

"class": {
  "service-name:{class}": {
    "request": "queue-pattern:{class}",
    "response": "queue-pattern:{class}",
    "settings": {
      "setting-name": "fixed-value",
      "parameterized-setting": "{parameter-name}"
    }
  }
}

Características: Compartidas entre todas las instancias de flujo de la misma clase. Típicamente servicios costosos o sin estado (modelos de lenguaje grandes, modelos de embedding). Utilice la variable de plantilla {class} para el nombre de la cola. Los ajustes pueden ser valores fijos o parametrizados con la sintaxis {parameter-name}. Ejemplos: embeddings:{class}, text-completion:{class}, graph-rag:{class}.

2. Sección de Flujo

Define los procesadores específicos del flujo que se instancian para cada instancia de flujo individual. Cada flujo obtiene su propio conjunto aislado de estos procesadores.

"flow": {
  "processor-name:{id}": {
    "input": "queue-pattern:{id}",
    "output": "queue-pattern:{id}",
    "settings": {
      "setting-name": "fixed-value",
      "parameterized-setting": "{parameter-name}"
    }
  }
}

Características: Instancia única por flujo Maneja datos y estado específicos del flujo Utilice la variable de plantilla {id} para el nombre de la cola Los ajustes pueden ser valores fijos o parametrizados con la sintaxis {parameter-name} Ejemplos: chunker:{id}, pdf-decoder:{id}, kg-extract-relationships:{id}

3. Sección de Interfaces

Define los puntos de entrada y los contratos de interacción para el flujo. Estos forman la superficie de la API para sistemas externos y comunicación entre componentes internos.

Las interfaces pueden adoptar dos formas:

Patrón de "Enviar y Olvidar" (cola única):

"interfaces": {
  "document-load": "persistent://tg/flow/document-load:{id}",
  "triples-store": "persistent://tg/flow/triples-store:{id}"
}

Patrón de solicitud/respuesta (objeto con campos de solicitud/respuesta):

"interfaces": {
  "embeddings": {
    "request": "non-persistent://tg/request/embeddings:{class}",
    "response": "non-persistent://tg/response/embeddings:{class}"
  }
}

Tipos de Interfaces: Puntos de Entrada: Lugares donde los sistemas externos inyectan datos (document-load, agent) Interfaces de Servicio: Patrones de solicitud/respuesta para servicios (embeddings, text-completion) Interfaces de Datos: Puntos de conexión de flujo de datos "dispara y olvida" (triples-store, entity-contexts-load)

4. Sección de Parámetros

Mapea los nombres de parámetros específicos del flujo a definiciones de parámetros almacenadas centralmente:

"parameters": {
  "model": "llm-model",
  "temp": "temperature",
  "chunk": "chunk-size"
}

Características: Las claves son nombres de parámetros utilizados en la configuración del procesador (por ejemplo, {model}) Los valores hacen referencia a definiciones de parámetros almacenadas en schema/config Permite la reutilización de definiciones de parámetros comunes en diferentes flujos Reduce la duplicación de esquemas de parámetros

5. Metadatos

Información adicional sobre el plano del flujo:

"description": "Human-readable description",
"tags": ["capability-1", "capability-2"]

Variables de Plantilla

Variables del Sistema

{id}

Reemplazado con el identificador único de la instancia del flujo. Crea recursos aislados para cada flujo. Ejemplo: flow-123, customer-A-flow

{class}

Reemplazado con el nombre de la plantilla del flujo. Crea recursos compartidos entre flujos de la misma clase. Ejemplo: standard-rag, enterprise-rag

Variables de Parámetro

{parameter-name}

Parámetros personalizados definidos en el momento de la ejecución del flujo. Los nombres de los parámetros coinciden con las claves en la sección parameters del flujo. Se utilizan en la configuración de los procesadores para personalizar el comportamiento. Ejemplos: {model}, {temp}, {chunk} Reemplazado con los valores proporcionados al iniciar el flujo. Validados contra definiciones de parámetros almacenadas centralmente.

Configuración de Procesadores

La configuración proporciona valores de configuración a los procesadores en el momento de la creación. Pueden ser:

Configuración Fija

Valores directos que no cambian:

"settings": {
  "model": "gemma3:12b",
  "temperature": 0.7,
  "max_retries": 3
}

Configuración parametrizada

Valores que utilizan parámetros proporcionados al iniciar el flujo:

"settings": {
  "model": "{model}",
  "temperature": "{temp}",
  "endpoint": "https://{region}.api.example.com"
}

Los nombres de los parámetros en la configuración corresponden a las claves en la sección parameters del flujo.

Ejemplos de configuración

Procesador LLM con parámetros:

// In parameters section:
"parameters": {
  "model": "llm-model",
  "temp": "temperature",
  "tokens": "max-tokens",
  "key": "openai-api-key"
}

// In processor definition:
"text-completion:{class}": {
  "request": "non-persistent://tg/request/text-completion:{class}",
  "response": "non-persistent://tg/response/text-completion:{class}",
  "settings": {
    "model": "{model}",
    "temperature": "{temp}",
    "max_tokens": "{tokens}",
    "api_key": "{key}"
  }
}

Chunker con Configuraciones Fijas y Parametrizadas:

// In parameters section:
"parameters": {
  "chunk": "chunk-size"
}

// In processor definition:
"chunker:{id}": {
  "input": "persistent://tg/flow/chunk:{id}",
  "output": "persistent://tg/flow/chunk-load:{id}",
  "settings": {
    "chunk_size": "{chunk}",
    "chunk_overlap": 100,
    "encoding": "utf-8"
  }
}

Patrones de Colas (Pulsar)

Los planos de flujo utilizan Apache Pulsar para el envío de mensajes. Los nombres de las colas siguen el formato de Pulsar:

<persistence>://<tenant>/<namespace>/<topic>

Componentes:

persistencia: persistent or non-persistent (Modo de persistencia de Pulsar) inquilino: tg para definiciones de planos de flujo proporcionados por TrustGraph espacio de nombres: Indica el patrón de mensajería flow: Servicios de envío y olvido request: Parte de solicitud de servicios de solicitud/respuesta response: Parte de respuesta de servicios de solicitud/respuesta tema: El nombre específico de la cola/tema con variables de plantilla

Colas Persistentes

Patrón: persistent://tg/flow/<topic>:{id} Utilizado para servicios de envío y olvido y flujo de datos duradero Los datos persisten en el almacenamiento de Pulsar a través de reinicios Ejemplo: persistent://tg/flow/chunk-load:{id}

Colas No Persistentes

Patrón: non-persistent://tg/request/<topic>:{class} or non-persistent://tg/response/<topic>:{class} Utilizado para patrones de mensajería de solicitud/respuesta Efímero, no se persiste en disco por Pulsar Menor latencia, adecuado para comunicación estilo RPC Ejemplo: non-persistent://tg/request/embeddings:{class}

Arquitectura del Flujo de Datos

El plano de flujo crea un flujo de datos unificado donde:

1. Pipeline de Procesamiento de Documentos: Fluye desde la ingesta hasta la transformación y el almacenamiento <<<<<<< HEAD
2. Servicios de Consulta: Procesadores integrados que consultan las mismas bases de datos y servicios =======
3. Servicios de Consulta: Procesadores integrados que consultan las mismas fuentes de datos y servicios

82edf2d (New md files from RunPod)

3. Servicios Compartidos: Procesadores centralizados que todos los flujos pueden utilizar
4. Escritores de Almacenamiento: Persisten los datos procesados en los almacenes apropiados

Todos los procesadores (tanto {id} como {class}) trabajan juntos como un gráfico de flujo de datos cohesivo, no como sistemas separados.

Ejemplo de Instanciación de Flujo

Dado: ID de instancia de flujo: customer-A-flow Plano de flujo: standard-rag Mapeos de parámetros de flujo: "model": "llm-model" "temp": "temperature" "chunk": "chunk-size" Parámetros proporcionados por el usuario: model: gpt-4 temp: 0.5 chunk: 512

Expansiones de plantilla: persistent://tg/flow/chunk-load:{id} → persistent://tg/flow/chunk-load:customer-A-flow non-persistent://tg/request/embeddings:{class} → non-persistent://tg/request/embeddings:standard-rag "model": "{model}" → "model": "gpt-4" "temperature": "{temp}" → "temperature": "0.5" "chunk_size": "{chunk}" → "chunk_size": "512"

Esto crea: Pipeline de procesamiento de documentos aislado para customer-A-flow Servicio de incrustación compartido para todos los flujos standard-rag Flujo de datos completo desde la ingesta de documentos hasta la consulta Procesadores configurados con los valores de parámetro proporcionados

Beneficios

1. Eficiencia de Recursos: Los servicios costosos se comparten entre los flujos
2. Aislamiento de Flujos: Cada flujo tiene su propio pipeline de procesamiento de datos
3. Escalabilidad: Se pueden instanciar múltiples flujos desde la misma plantilla
4. Modularidad: Clara separación entre componentes compartidos y específicos del flujo
5. Arquitectura Unificada: La consulta y el procesamiento son parte del mismo flujo de datos