OpenAIEmbeddings

Este componente permite convertir textos en vectores numéricos (embeddings) utilizando los modelos de OpenAI. Los embeddings son útiles para tareas de búsqueda semántica, clasificación y clustering dentro de Nappai.

¿Cómo funciona?

Cuando configuras el componente, seleccionas un modelo de OpenAI (por ejemplo, text-embedding-3-small). Al enviar un bloque de texto, el componente llama a la API de OpenAI y recibe un vector de números que representa el contenido semántico del texto. Internamente, el componente gestiona la autenticación, la paginación de resultados y la posibilidad de dividir el texto en trozos (Chunk Size) para cumplir con los límites de longitud de contexto del modelo.

Entradas

• Chunk Size: Define cuántos caracteres se envían a la API por cada llamada. Un valor mayor reduce el número de peticiones pero puede acercarse al límite de contexto del modelo.
• Client: Identificador del cliente que realiza la petición. Se usa para trazabilidad interna.
• Default Headers: Encabezados HTTP que se incluirán en cada solicitud a la API. Útil para añadir tokens de autenticación o metadatos personalizados.
• Default Query: Parámetros de consulta que se añadirán a cada petición HTTP. Por ejemplo, {"model": "text-embedding-3-small"}.
• Deployment: Nombre de la implementación de un modelo desplegado en Azure OpenAI. Si no se usa Azure, déjalo vacío.
• Dimensions: El número de dimensiones que tendrá el vector resultante. Solo algunos modelos lo permiten; si no es compatible, se ignora.
• Embedding Context Length: Longitud máxima de contexto que el modelo puede procesar. Ajusta este valor si trabajas con textos muy largos.
• Max Retries: Número de intentos que el componente hará en caso de fallos temporales de la API.
• Model: Selección del modelo de embeddings de OpenAI. Los valores disponibles se listan en OPENAI_EMBEDDING_MODEL_NAMES.
• Model Kwargs: Parámetros adicionales que se pasan al modelo, como temperature o top_p.
• OpenAI API Base: URL base de la API de OpenAI. Útil si usas un proxy o un entorno local.
• OpenAI API Type: Tipo de API (por ejemplo, azure o openai).
• OpenAI API Version: Versión de la API que se va a usar.
• OpenAI Organization: Identificador de la organización en Azure OpenAI.
• OpenAI Proxy: Dirección del proxy HTTP a usar para las peticiones.
• Request Timeout: Tiempo máximo (en segundos) que la solicitud puede tardar antes de abortarse.
• Show Progress Bar: Muestra una barra de progreso mientras se generan los embeddings.
• Skip Empty: Si está activado, se omiten los textos vacíos o nulos.
• TikToken Enable: Si se desactiva, se requiere instalar la librería transformers para el tokenizador.
• TikToken Model Name: Nombre del modelo de tokenización a usar con TikToken.

Credencial requerida
Este componente necesita una credencial de tipo OpenAI API.

1. Ve a la sección de credenciales de Nappai y crea una nueva credencial llamada “OpenAI API”.
2. Ingresa tu OpenAI Api Key (es un secreto).
3. En el componente, selecciona esa credencial en el campo Credential.

Salidas

• Embeddings: Vector numérico que representa el texto procesado. Se puede usar como entrada para búsquedas, clustering o como característica en modelos de aprendizaje automático.

Ejemplo de Uso

1. Añade el componente “OpenAIEmbeddings” al flujo.
2. Selecciona la credencial “OpenAI API”.
3. Configura el Model a text-embedding-3-small.
4. Deja el Chunk Size en 1000 (valor por defecto).
5. Conecta la salida de un componente que extrae texto de un documento a la entrada de este componente.
6. La salida Embeddings se puede pasar a un componente de búsqueda semántica o a un modelo de clasificación.

Componentes Relacionados

• OpenAI Text Embeddings – Genera embeddings para textos cortos con un enfoque más ligero.
• Local Embeddings – Crea embeddings usando modelos locales sin requerir conexión a OpenAI.
• Vector Search – Busca documentos similares usando los embeddings generados.

Consejos y Mejores Prácticas

• Usa Chunk Size adecuado: Si trabajas con textos muy largos, aumenta el tamaño para reducir llamadas, pero no excedas el límite de contexto del modelo.
• Controla el número de dimensiones: Si tu modelo lo permite, reduce las dimensiones para ahorrar memoria y acelerar búsquedas.
• Activa Show Progress Bar cuando proceses grandes volúmenes; ayuda a monitorear el progreso.
• Configura Max Retries en 3 o 5 para manejar picos de tráfico sin interrumpir el flujo.
• Mantén la credencial segura: No compartas la API Key y revísala periódicamente.

Consideraciones de Seguridad

• La API Key es un secreto crítico; nunca la expongas en código público.
• Si usas OpenAI Proxy, asegúrate de que el proxy esté protegido y autenticado.
• Los Default Headers y Default Query pueden incluir información sensible; revisa que no se envíen datos confidenciales accidentalmente.