Lenguaje Natural Documentación
Visión general
Análisis de texto por LLM, embeddings, sentimiento y sanitización de PII.
Esta referencia cubre 8 engines. Cada endpoint trae ruta, permiso, parámetros, respuesta y los errores posibles.
Embeddings de imagen
Propósito
Embeddings de imagen con aceleración dedicada: embed, similitud, búsqueda o dedup por modelo de visión.
Carga las imágenes nombradas por image_column y las codifica con un modelo de visión (con aceleración dedicada cuando está disponible); según el mode, devuelve el mapa id->vector, un ranking de similitud por coseno entre pares, los vecinos más cercanos de una imagen de consulta, o pares casi duplicados por encima de un umbral de similitud. Cada entrada puede ser una URL http(s), una URL s3://bucket/clave, una ruta en el sistema de archivos de quien ejecuta, o una clave de objeto del almacenamiento de la plataforma; una URL se descarga con timeout de 15s, límite de 25 MB y solo desde una dirección pública.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
image_column | string | sí | Columna con las referencias de las imágenes (URL, s3://bucket/clave, ruta en el sistema de archivos de quien ejecuta o clave de objeto del almacenamiento de la plataforma). | |
id_column | string | sí | Columna con los identificadores de los ítems. | |
model | string | no | "openai/clip-vit-base-patch32" | Nombre del modelo de visión a usar. |
mode | string | no | "embed" | Uno de embed, similarity, search, dedup. |
batch_size | integer | no | 64 | Tamaño del lote de codificación. |
query_image | string | no | Referencia de la imagen de consulta, en las mismas formas que la columna; obligatorio cuando mode=search. | |
similarity_threshold | number | no | 0.95 | Umbral de similitud por coseno del modo dedup, entre 0 y 1. |
top_n | integer | no | 10 | Cantidad de resultados devueltos en modo search. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
image_path | string | sí | Referencia de la imagen: URL http(s), URL s3://bucket/clave, ruta en el sistema de archivos de quien ejecuta o clave de objeto del almacenamiento de la plataforma (nombre de la columna configurable vía image_column). |
id | string | sí | Identificador del ítem (nombre de columna configurable vía id_column). |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/image_embeddings/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"LLM
Propósito
Procesamiento de texto por LLM en el tier de aceleración dedicada: sentimiento, resumen, clasificación, extracción, análisis, traducción o prompt custom.
¿Por qué? Procesamiento de texto de propósito general vía LLM, con aceleración dedicada para inferencia de baja latencia. Cubre análisis de sentimiento, resumen, clasificación, extracción de entidades, traducción y prompts personalizados, entregando los resultados de cada operación de forma consistente para lotes de textos.
¿Cómo? La inferencia se realiza a través del proveedor de LLM configurado en la plataforma, con ingeniería de prompts y muestreo por temperatura configurable. El paralelismo se controla internamente para procesar múltiples textos sin sobrecargar al proveedor.
Origen El enfoque se apoya en Brown et al. (2020), "Language Models are Few-Shot Learners", NeurIPS.
Literatura de referencia
- Brown, T. et al. (2020). "Language Models are Few-Shot Learners." NeurIPS.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
operation | string | no | "analyze" | Una de sentiment, summarize, classify, extract, analyze, translate_pt, translate_en, custom. |
text_column | string | no | "text" | Nombre de la columna con el texto a procesar. |
custom_prompt | string | no | Plantilla de prompt con el placeholder {text}; obligatoria cuando operation=custom. | |
temperature | number | no | 0.1 | Temperatura de generación del LLM, entre 0 y 2. |
max_tokens | integer | no | 512 | Máximo de tokens generados por texto. |
max_concurrent | integer | no | 5 | Máximo de textos procesados en paralelo. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
text | string | sí | Contenido de texto a procesar (nombre de columna configurable vía text_column). |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/llm/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Análisis de texto (EN)
Propósito
Análisis de texto por LLM fijado en inglés: sentimiento, resumen, clasificación, extracción, análisis o traducción al portugués.
¿Por qué? Análisis de lenguaje natural especializado en textos en inglés, con prompts y heurísticas específicos del idioma que mejoran la calidad del análisis. Ideal cuando el corpus es mayormente anglófono, como reseñas internacionales o tickets de soporte en inglés.
¿Cómo? Se construye sobre el hub de NLP de la plataforma, ejecutando las operaciones a través del proveedor de LLM configurado. Usa plantillas de prompt optimizadas para la lengua inglesa, con instrucciones de sistema específicas para el análisis en inglés, manteniendo la misma arquitectura del engine base.
Origen El enfoque se apoya en Brown et al. (2020), "Language Models are Few-Shot Learners", NeurIPS.
Literatura de referencia
- Brown, T. et al. (2020). "Language Models are Few-Shot Learners." NeurIPS.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
operation | string | no | "analyze" | Una de sentiment, summarize, classify, extract, analyze, translate_pt, custom. translate_en se rechaza. |
response_format | string | no | "text" | Formato deseado de la respuesta, anexado al prompt: json, markdown o text. |
custom_prompt | string | no | Plantilla de prompt con el placeholder {text}; obligatoria cuando operation=custom. | |
temperature | number | no | 0.1 | Temperatura de generación del LLM, entre 0 y 2. |
max_tokens | integer | no | 512 | Máximo de tokens generados por texto. |
max_concurrent | integer | no | 5 | Máximo de textos procesados en paralelo. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
text | string | sí | Contenido de texto en inglés a analizar. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/nlp_analisys_en/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Embeddings de texto
Propósito
Embeddings semánticos de texto con aceleración dedicada: embed, similitud, búsqueda o clustering.
Codifica una columna de texto en vectores densos con un modelo de sentence embeddings (con aceleración dedicada cuando está disponible); según el mode, devuelve el mapa id->vector, un ranking de similitud por coseno entre pares, los vecinos más cercanos de un string de consulta, o asignaciones de clusters KMeans.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
text_column | string | sí | Columna con el texto a codificar. | |
id_column | string | sí | Columna con los identificadores de los ítems. | |
model | string | no | "all-MiniLM-L6-v2" | Nombre del modelo de sentence embeddings. |
mode | string | no | "embed" | Uno de embed, similarity, search, cluster. |
batch_size | integer | no | 256 | Tamaño del lote de codificación. |
normalize | boolean | no | true | Si los embeddings deben normalizarse en L2 antes de similitud/búsqueda/cluster. |
query | string | no | Texto de consulta a codificar y comparar; obligatorio cuando mode=search. | |
top_n | integer | no | 10 | Cantidad de resultados devueltos en modo search. |
n_clusters | integer | no | 5 | Número de clusters KMeans (mode=cluster), >= 2. |
random_state | integer | no | 42 | Semilla aleatoria del clustering KMeans. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
text | string | sí | Texto a codificar (nombre de columna configurable vía text_column). |
id | string | sí | Identificador del ítem (nombre de columna configurable vía id_column). |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/nlp_embeddings/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Análisis de texto
Propósito
Análisis de texto vía LLM: sentimiento, resumen, clasificación, extracción, análisis, traducción o prompt custom.
¿Por qué? Hub central de NLP de la plataforma: una interfaz unificada que entrega análisis de sentimiento, resumen, clasificación, extracción, traducción y operaciones personalizadas. En la práctica, es el punto único de entrada para cualquier procesamiento de lenguaje natural, sin que la aplicación necesite conocer el proveedor detrás.
¿Cómo? Las llamadas se realizan al proveedor de LLM configurado en la plataforma, con selección dinámica de proveedor. Usa ingeniería de prompts con plantillas especializadas por tipo de operación y procesa múltiples textos de forma concurrente.
Origen El enfoque se apoya en Brown et al. (2020), "Language Models are Few-Shot Learners", NeurIPS.
Literatura de referencia
- Brown, T. et al. (2020). "Language Models are Few-Shot Learners." NeurIPS.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
operation | string | no | "analyze" | Una de sentiment, summarize, classify, extract, analyze, translate_pt, translate_en, custom. |
response_format | string | no | "text" | Formato deseado de la respuesta, anexado al prompt: json, markdown o text. |
custom_prompt | string | no | Plantilla de prompt con el placeholder {text}; obligatoria cuando operation=custom. | |
temperature | number | no | 0.1 | Temperatura de generación del LLM, entre 0 y 2. |
max_tokens | integer | no | 512 | Máximo de tokens generados por texto. |
max_concurrent | integer | no | 5 | Máximo de textos procesados en paralelo. |
language | string | no | Pista de idioma pasada al cliente de LLM (normalizada en el servidor). |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
text | string | sí | Contenido de texto a analizar. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/nlp_local/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Sanitización de PII
Propósito
Remoción de PII: enmascara emails, teléfonos, CPF/CNPJ, tarjetas de crédito e IPs en texto libre.
¿Por qué? Elimina información personal identificable (PII) de campos de texto, sustituyendo correos electrónicos, teléfonos brasileños, CPF, CNPJ, números de tarjeta de crédito (Visa, Mastercard, Amex) y direcciones IPv4 por una máscara configurable (por defecto [REDACTED]). Además de los datos sanitizados, entrega un informe de detección con conteo por tipo de PII, filas y columnas afectadas. Fundamental para el cumplimiento normativo en pipelines de procesamiento de datos.
¿Cómo? Aplica expresiones regulares en secuencia sobre cada celda de texto, de los patrones más específicos a los más generales, por ejemplo CPF antes que teléfono, para evitar falsos positivos. Cada ocurrencia se sustituye por la máscara configurable, con validación opcional por dígito verificador (módulo 11 para CPF, Luhn para tarjetas). Al final genera el informe con el total de detecciones por tipo, filas y columnas afectadas.
Origen Responde directamente a las exigencias de la LGPD (Lei Geral de Proteção de Dados, Ley 13.709/2018 de Brasil) y del GDPR (Reglamento General de Protección de Datos, EU 2016/679).
Literatura de referencia
- LGPD (Lei Geral de Protecao de Dados, Lei 13.709/2018)
- GDPR (General Data Protection Regulation, EU 2016/679)
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
mask | string | no | "[##INTELLIGENCE##]" | String de reemplazo usado en cada ocurrencia enmascarada. |
sanitize_emails | boolean | no | true | Detectar y enmascarar direcciones de email. |
sanitize_phones | boolean | no | true | Detectar y enmascarar teléfonos brasileños/internacionales. |
sanitize_cpf | boolean | no | true | Detectar y enmascarar números de CPF. |
sanitize_cnpj | boolean | no | true | Detectar y enmascarar números de CNPJ. |
sanitize_credit_cards | boolean | no | true | Detectar y enmascarar números de tarjeta de crédito. |
sanitize_ips | boolean | no | false | Detectar y enmascarar direcciones IPv4. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
text | string | sí | Texto libre a sanitizar de información personal identificable. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/sanitize/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Sentimiento en tiempo real
Propósito
Sentimiento por reglas para micro-lotes: léxico + emojis + negación, sin LLM.
¿Por qué? Análisis de sentimiento optimizado para micro-lotes y latencia crítica, con inferencia en tiempo real por debajo de 50ms por texto y un score normalizado entre -1 y +1 para cada entrada. Está diseñado para escenarios de alta velocidad, como chat en vivo y streaming de redes sociales, donde esperar un modelo pesado no es una opción.
¿Cómo? Usa coincidencia basada en reglas contra léxicos extendidos de palabras de sentimiento. Maneja la negación con inversión de polaridad, detecta intensificadores (muy, extremadamente) y puntúa emojis para capturar el sentimiento visual. El score final se normaliza entre -1 y +1.
Origen Se inspira en Hutto y Gilbert (2014), "VADER: A Parsimonious Rule-based Model for Sentiment Analysis of Social Media Text", ICWSM.
Literatura de referencia
- Hutto, C. J. & Gilbert, E. (2014). "VADER: A Parsimonious Rule-based Model for Sentiment Analysis of Social Media Text." ICWSM.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
language | string | no | "en" | Idioma del léxico: en o pt. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
text | string | sí | Contenido de texto a analizar. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/sentiment_realtime/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Voz del cliente
Propósito
Análisis de voz del cliente vía LLM local (sentimiento, palabras clave o tópicos) con fallback por reglas.
¿Por qué? Analiza el sentimiento de textos con foco en Voice of Customer, capturando la voz del consumidor en feedback y reseñas y entregando la distribución agregada de sentimiento entre los textos. Alimenta el análisis cualitativo de la experiencia del cliente con una lectura consolidada de lo que expresan los consumidores.
¿Cómo? La clasificación primaria es contextual, realizada por el proveedor de LLM configurado en la plataforma, con un respaldo basado en reglas que usa la frecuencia de palabras de un léxico de sentimiento. Los lotes de textos se procesan de forma asíncrona y la distribución de sentimiento se agrega estadísticamente.
Origen Se fundamenta en Liu (2012), "Sentiment Analysis and Opinion Mining", Morgan & Claypool Publishers.
Literatura de referencia
- Liu, B. (2012). "Sentiment Analysis and Opinion Mining." Morgan & Claypool Publishers.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
operation | string | no | "sentiment" | Una de sentiment, keywords, topics. |
model | string | no | "deepseek-r1:14b" | Nombre del modelo usado en la inferencia. |
inference_url | string | no | "http://localhost:11434" | URL base del servidor de inferencia local. Alias heredado: ollama_url, aún aceptado. |
max_texts | integer | no | 500 | Máximo de filas procesadas (1-2000); las excedentes se truncan. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
text | string | sí | Contenido de texto a analizar. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/sentiment_voc/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"