Guía de integración del SDK de compresión: llamada multilenguaje Python/Java/C#

Conclusión primero: SmartSlim SDK exporta bibliotecas dinámicas a través del ABI estándar de C, soportando integración en cuatro lenguajes: Python/Java/C#/Rust. El flujo de llamada central se divide en cuatro pasos — inicializar el SDK, crear la configuración de compresión, ejecutar la compresión y liberar recursos. La compresión de un único archivo PDF de 100 MB tarda aproximadamente 0,8 segundos, con una latencia de verificación de licencia inferior a 5 ms. Este artículo presenta ejemplos de código de integración completos en tres lenguajes, tablas de parámetros de la API y un plan de optimización de rendimiento, con una demo de compresión por lotes. A continuación, empezando por la arquitectura del SDK, se explica detalladamente el método de integración para cada lenguaje.

Si necesitas invocar el servicio de compresión a través de una interfaz HTTP en lugar de la integración del SDK, te recomendamos leer primero la Guía práctica de llamada a la API de compresión: documentación detallada de la interfaz RESTful.

1. Arquitectura del SDK y principios de integración

La base del SmartSlim SDK es el motor de compresión Rust, exportado como biblioteca dinámica (.so/.dylib/.dll) a través del ABI estándar de C (Application Binary Interface). Cualquier lenguaje que soporte FFI (Foreign Function Interface) puede cargarla y llamarla. La ventaja de esta arquitectura es: escribir el motor central una vez en Rust y reutilizar el mismo binario para múltiples lenguajes, sin necesidad de reimplementar la lógica de compresión en cada uno.

Componente	Tecnología	Función	Salida
Núcleo del motor de compresión	Rust	Ejecutar algoritmos de compresión	Biblioteca estática .a/.lib
Capa de exportación ABI	Rust #[no_mangle]	Exportar funciones compatibles con C	Biblioteca dinámica .so/.dylib/.dll
Capa de bindings de lenguaje	FFI de cada lenguaje	Encapsular llamadas nativas	Paquete/biblioteca por lenguaje
Módulo de licencia	Rust + cifrado	Verificar clave de licencia	Integrado en la biblioteca dinámica
Gestión de configuración	Rust struct	Gestión de parámetros de compresión	Configuración JSON/TOML

El SDK proporciona bibliotecas precompiladas para 6 plataformas, cubriendo los sistemas operativos y arquitecturas de CPU principales, listas para usar sin necesidad de compilar código Rust.

Plataforma	Biblioteca dinámica	Sistema operativo	Arquitectura CPU	Escenario aplicable
linux-x64	libsmartslim.so	Linux	x86_64	Servidor/escritorio
linux-arm64	libsmartslim.so	Linux	aarch64	Servidor ARM/Raspberry Pi
macos-universal	libsmartslim.dylib	macOS	x86_64+arm64	Intel+Apple Silicon
windows-x64	smartslim.dll	Windows	x86_64	Windows escritorio/servidor
linux-server-x64	libsmartslim.so	Linux	x86_64	Versión optimizada para servidor
linux-server-arm64	libsmartslim.so	Linux	aarch64	Versión optimizada para servidor ARM

2. Detalle de los parámetros principales de la API

La API principal del SDK se divide en cuatro categorías: inicialización, configuración, compresión y liberación. La siguiente tabla lista las funciones principales de la API y la descripción de sus parámetros.

Función API	Parámetros	Valor de retorno	Descripción
smartslim_init	license_key: String	handle: Handle	Inicializar el SDK, verificar licencia
smartslim_create_config	format, level, quality	config: ConfigHandle	Crear configuración de compresión
smartslim_compress	handle, input, output, config	result: ResultCode	Ejecutar compresión de archivo individual
smartslim_compress_batch	handle, files[], config, workers	results[]: ResultCode	Compresión por lotes (multi-concurrencia)
smartslim_get_info	handle, filepath	FileInfo: struct	Obtener información de compresión del archivo
smartslim_free_config	config: ConfigHandle	void	Liberar recursos de configuración
smartslim_free	handle: Handle	void	Liberar instancia del SDK

Los parámetros de configuración de compresión soportan 4 niveles de compresión (low/medium/high/ultra) x 15 escenarios x 5 modos de rendimiento (ultrafast/fast/balanced/quality/optimal), con un total de 300 combinaciones que cubren prácticamente todas las necesidades de compresión.

Parámetro	Valores disponibles	Valor predeterminado	Descripción
format	pdf/image/video/office/ofd	Detección automática	Tipo de archivo
level	low/medium/high/ultra	medium	Nivel de compresión
quality	1-100	75	Factor de calidad (imágenes/PDF)
performance	ultrafast/fast/balanced/quality/optimal	balanced	Modo de rendimiento
workers	1-16	4	Número de hilos concurrentes
security	DISABLED/LOW/MEDIUM/HIGH/MAXIMUM	MEDIUM	Nivel de seguridad

3. Ejemplos de código de integración en tres lenguajes

A continuación se presentan ejemplos de integración completos en Python, Java y C#, todos con el ejemplo de comprimir un único archivo PDF.

1. Integración en Python (ctypes)

Python carga la biblioteca dinámica y llama a las funciones exportadas a través del módulo ctypes. El siguiente código implementa el flujo completo: inicializar el SDK, crear la configuración, comprimir el PDF y liberar recursos. La compresión de un PDF de 100 MB tarda aproximadamente 0,8 segundos.

Paso	Código Python	Descripción
1. Cargar biblioteca	lib = ctypes.CDLL('./libsmartslim.so')	Cargar biblioteca dinámica
2. Inicializar	handle = lib.smartslim_init(b"YOUR_LICENSE")	Pasar clave de licencia
3. Crear configuración	config = lib.smartslim_create_config(b"pdf", b"medium", 75)	PDF/medium/q75
4. Ejecutar compresión	lib.smartslim_compress(handle, b"in.pdf", b"out.pdf", config)	Comprimir archivo
5. Liberar recursos	lib.smartslim_free_config(config); lib.smartslim_free(handle)	Liberar memoria

2. Integración en Java (JNI)

Java llama a la biblioteca dinámica a través de JNI (Java Native Interface). Es necesario escribir primero la declaración de métodos nativos y luego cargar el archivo de biblioteca. El siguiente código muestra el flujo de llamada central, adecuado para la integración en proyectos backend de Java como Spring Boot.

Paso	Código Java	Descripción
1. Cargar biblioteca	System.loadLibrary("smartslim")	Cargar DLL/SO
2. Declarar métodos	native long smartslim_init(String key)	Declaración de método JNI
3. Inicializar	long handle = smartslim_init("YOUR_LICENSE")	Obtener handle de instancia
4. Crear configuración	long config = smartslim_create_config("pdf","medium",75)	Parámetros de configuración
5. Ejecutar compresión	smartslim_compress(handle, "in.pdf", "out.pdf", config)	Comprimir archivo
6. Liberar recursos	smartslim_free_config(config); smartslim_free(handle)	Liberar memoria

3. Integración en C# (P-Invoke)

C# llama a la biblioteca dinámica a través de P/Invoke (Platform Invocation Services). Usa el atributo DllImport para declarar funciones externas, adecuado para proyectos .NET/.NET Core. El siguiente código es compatible con plataformas Windows y Linux.

Paso	Código C#	Descripción
1. Declarar función	[DllImport("smartslim")] static extern IntPtr smartslim_init(string key)	Declaración P-Invoke
2. Inicializar	IntPtr handle = smartslim_init("YOUR_LICENSE")	Obtener handle
3. Crear configuración	IntPtr config = smartslim_create_config("pdf","medium",75)	Parámetros de configuración
4. Ejecutar compresión	smartslim_compress(handle, "in.pdf", "out.pdf", config)	Comprimir archivo
5. Liberar recursos	smartslim_free_config(config); smartslim_free(handle)	Liberar memoria

4. Optimización de rendimiento y compresión por lotes

La optimización de rendimiento de la integración del SDK se centra en tres dimensiones: concurrencia, memoria y procesamiento por lotes. La siguiente tabla presenta la comparación de efectos de diferentes estrategias de optimización.

Estrategia de optimización	Tiempo por archivo	Tiempo total 100 archivos	Uso de memoria	Licencia aplicable
Un solo hilo en serie	0.8s	80s	50MB	Trial (1 concurrencia)
4 hilos concurrentes	0.8s	22s	180MB	Standard (4 concurrencias)
8 hilos concurrentes	0.8s	12s	320MB	Professional (8 concurrencias)
16 hilos concurrentes	0.8s	7s	600MB	Enterprise (16+ concurrencias)
Modo de compresión por flujos	1.2s	95s	15MB	Todas las licencias

Para la compresión por lotes se recomienda usar la interfaz integrada smartslim_compress_batch, pasando la lista de archivos y el número de concurrencia; el SDK usa programación asíncrona de Rust internamente, siendo más eficiente que implementar multihilo en cada lenguaje. A continuación se presentan los datos de rendimiento de una demo de compresión por lotes de 100 archivos PDF.

Cantidad de archivos	Promedio por archivo	Tamaño total	Tamaño comprimido	Tiempo 8 concurrencias	Tasa de compresión
100 PDF	15MB	1.5GB	320MB	12s	78.7%
100 PNG	8MB	800MB	180MB	8s	77.5%
100 DOCX	5MB	500MB	120MB	6s	76.0%
100 MP4	50MB	5GB	1.8GB	45s	64.0%

Si necesitas conocer la comparación de algoritmos subyacentes de las bibliotecas de compresión Rust, puedes consultar la comparación de bibliotecas de compresión Rust: por qué elegir Rust para el motor de compresión. Si necesitas desplegar el servicio de compresión mediante contenedores Docker, puedes consultar la guía de despliegue de servicio de compresión con Docker.

5. Preguntas frecuentes (FAQ)

Q1: ¿Qué lenguajes de programación soporta el SDK de compresión?

SmartSlim SDK exporta bibliotecas dinámicas a través del ABI estándar de C, soportando integración en cuatro lenguajes: Python (ctypes), Java (JNI), C# (P-Invoke) y Rust (FFI). El SDK proporciona bibliotecas precompiladas para 6 plataformas (linux-x64/arm64, macos-universal, windows-x64, etc.), listas para usar sin necesidad de compilación. Otros lenguajes que soportan llamadas C ABI (como Go, Node.js, PHP) también pueden integrarse mediante sus respectivos mecanismos FFI.

Q2: ¿Cuál es el flujo de llamada a la API del SDK de compresión?

El flujo de llamada estándar se divide en cuatro pasos: 1. llamar a smartslim_init para inicializar el SDK y pasar la clave de licencia; 2. llamar a smartslim_create_config para crear la configuración de compresión (especificar formato, nivel y modo de rendimiento); 3. llamar a smartslim_compress para ejecutar la compresión (pasar la ruta del archivo de entrada y salida); 4. llamar a smartslim_free para liberar recursos. La compresión de un único archivo PDF de 100 MB tarda aproximadamente 0,8 segundos, con una latencia de verificación de licencia inferior a 5 ms.

Q3: ¿Cómo implementar la compresión por lotes con el SDK de compresión?

La compresión por lotes se puede implementar de dos formas: primera, llamar en bucle a la interfaz de compresión de archivos individuales, combinada con concurrencia multihilo (Python usa concurrent.futures, Java usa ThreadPoolExecutor); segunda, usar la interfaz de compresión por lotes integrada smartslim_compress_batch, pasando la lista de archivos y el número de concurrencia, con el SDK usando programación asíncrona de Rust internamente. Se recomienda la segunda opción: la licencia Standard soporta 4 concurrencias, Professional 8 y Enterprise 16 o más.

Q4: ¿Qué hacer si hay errores en la integración del SDK de compresión?

Errores comunes y soluciones: 1. UnsatisfiedLinkError (Java) o fallo de carga de DLL — verificar si la ruta de la biblioteca dinámica y la arquitectura del sistema coinciden; 2. fallo de verificación de licencia — comprobar si la clave es correcta y no ha expirado; 3. desbordamiento de memoria — reducir el número de concurrencias o activar el modo de compresión por flujos; 4. formato no soportado — verificar si la versión del SDK soporta el formato objetivo. Se recomienda activar el registro DEBUG para localizar el problema o contactar con el soporte técnico de SmartSlim.

Resumen

SmartSlim SDK implementa a través del ABI estándar de C el principio de escribir una vez, llamar desde múltiples lenguajes, soportando integración en Python/Java/C#/Rust. El flujo de llamada central en cuatro pasos: inicializar, crear configuración, ejecutar compresión, liberar recursos. La compresión de un único archivo PDF de 100 MB tarda 0,8 segundos, y la compresión por lotes de 100 archivos con 8 concurrencias solo 12 segundos. La optimización de rendimiento en tres dimensiones: concurrencia (4–16 hilos), memoria (el modo por flujos reduce el uso un 75%) y procesamiento por lotes (interfaz batch integrada).

Recuerda tres puntos: primero, selecciona la biblioteca precompilada que coincida con la arquitectura del sistema (6 plataformas cubiertas); segundo, para la compresión por lotes usa prioritariamente la interfaz batch integrada en lugar de implementar multihilo propio; tercero, en entornos de producción se recomienda licencia Professional o superior (8 concurrencias), equilibrando rendimiento y coste. Si prefieres la llamada por interfaz HTTP en lugar de la integración del SDK, puedes consultar la guía práctica de llamada a la API de compresión.