Documentación de SOF.IA LLM

Introducción

SOF.IA LLM es una plataforma de LLM-as-a-Service sobre infraestructura privada. A diferencia de los proveedores públicos de IA, su información se procesa en infraestructura dedicada, con colecciones de datos aisladas por cliente, y nunca se utiliza para entrenar modelos de terceros.

La plataforma expone dos superficies de API:

• API del modelo — protocolo estándar de la industria (chat completions). Se integra con cualquier lenguaje mediante HTTP estándar; solo necesita la URL base y su API key.
• API de producto — capacidades de alto nivel: análisis de documentos con skills especialistas, base de conocimiento privada (RAG), agentes configurables y recepción de datasets para fine-tuning.

Primeros pasos

Necesita una API key (formato sk-...), entregada por su ejecutivo de cuenta al activar el servicio. Con ella puede hacer su primera petición en menos de un minuto:

curl https://api.sofiallm.com/v1/chat/completions \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sofia-llm-32b",
    "messages": [{"role": "user", "content": "Hola SOF.IA"}],
    "max_tokens": 300,
    "chat_template_kwargs": {"enable_thinking": false}
  }'

Con Python:

import requests

resp = requests.post(
    "https://api.sofiallm.com/v1/chat/completions",
    headers={"Authorization": "Bearer TU_API_KEY"},  # use una variable de entorno
    json={
        "model": "sofia-llm-32b",
        "messages": [{"role": "user", "content": "Hola SOF.IA"}],
        "max_tokens": 300,
        "chat_template_kwargs": {"enable_thinking": False},
    },
)
print(resp.json()["choices"][0]["message"]["content"])

const resp = await fetch("https://api.sofiallm.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SOFIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "sofia-llm-32b",
    messages: [{ role: "user", content: "Hola SOF.IA" }],
    max_tokens: 300,
    chat_template_kwargs: { enable_thinking: false },
  }),
});
const data = await resp.json();
console.log(data.choices[0].message.content);

Autenticación

Todas las peticiones se autentican con el header estándar:

Authorization: Bearer TU_API_KEY

Gestión de keys (multi-key)

Su cuenta admite múltiples API keys, gestionables de forma autónoma desde la consola (sección API keys). Cada key tiene su propio alias, fecha de expiración, presupuesto opcional y puede revocarse individualmente sin afectar a las demás.

• Una key por entorno o integración — p. ej. prod-backend, staging, dev-maria. Si un desarrollador deja el equipo o una integración se retira, revoque solo esa key.
• Expiración automática — configure 30, 90 o 365 días; al vencer, la key deja de funcionar sin intervención manual.
• Reemplazo sin interrupciones — para renovar una credencial: cree la key nueva, actualice sus sistemas con calma y revoque la anterior. Sin ventanas de caída.

Buenas prácticas

• Guarde las keys en variables de entorno o un gestor de secretos; nunca en código fuente ni repositorios.
• La key completa se muestra una única vez al crearla; en la plataforma solo se almacena su hash irreversible (SHA-256).
• Ante cualquier sospecha de filtración, cree una key de reemplazo y revoque la comprometida de inmediato desde la consola.

Chat Completions

Genera una respuesta del modelo a partir de una conversación. Protocolo estándar de la industria: los SDK existentes funcionan sin cambios.

Parámetros

Respuesta

{
  "id": "chatcmpl-…",
  "model": "sofia-llm-32b",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": {
      "role": "assistant",
      "content": "…respuesta…",
      "reasoning_content": null
    }
  }],
  "usage": { "prompt_tokens": 18, "completion_tokens": 96, "total_tokens": 114 }
}

El bloque usage es la base de la facturación: cada token de entrada y salida se descuenta de su crédito según la tarifa de su plan.

Razonamiento extendido

El modelo puede "pensar" antes de responder, lo que mejora tareas complejas de lógica, matemáticas o análisis de varios pasos. El razonamiento llega separado en el campo reasoning_content y también consume tokens.

• Desactivado (recomendado por defecto): "chat_template_kwargs": {"enable_thinking": false}.
• Activado: omita el parámetro. Útil en cálculos, planeación y problemas de varios pasos.

Streaming

Agregue "stream": true para recibir la respuesta de forma incremental (Server-Sent Events), ideal para interfaces de chat:

import json, requests

with requests.post(
    "https://api.sofiallm.com/v1/chat/completions",
    headers={"Authorization": "Bearer TU_API_KEY"},
    json={"model": "sofia-llm-32b",
          "messages": [{"role": "user", "content": "Escribe un párrafo sobre logística"}],
          "max_tokens": 400, "stream": True},
    stream=True,
) as r:
    for line in r.iter_lines():
        if line.startswith(b"data: ") and line != b"data: [DONE]":
            delta = json.loads(line[6:])["choices"][0]["delta"].get("content", "")
            print(delta, end="", flush=True)

Manejo de errores

Análisis de documentos (skills)

Envíe un documento (PDF o texto) con una instrucción y un skill especialista, y reciba un análisis experto estructurado. Los documentos largos se procesan automáticamente por partes y se sintetizan en un único resultado.

Lista los skills disponibles para su cuenta.

Analiza un documento. Envío como multipart/form-data.

Skills disponibles

curl -X POST https://app.sofiallm.com/v1/documents/analyze \
  -H "Authorization: Bearer TU_API_KEY" \
  -F "skill=revisor-contratos" \
  -F "instruction=Identifique cláusulas riesgosas y puntos a negociar" \
  -F "file=@contrato_marco.pdf"

{
  "analysis": "…análisis estructurado…",
  "skill": "revisor-contratos",
  "model": "sofia-llm-32b",
  "source": "contrato_marco.pdf",
  "chunks_processed": 1,
  "usage": { "prompt_tokens": 1240, "completion_tokens": 830, "total_tokens": 2070 }
}

Base de conocimiento (RAG)

Suba los documentos de su organización una sola vez y consúltelos por API cuantas veces necesite. El modelo responde con su información, citando los archivos fuente. Cada cliente tiene una colección aislada a nivel de base de datos: sus documentos jamás se mezclan con los de otros clientes ni entrenan modelos de terceros.

Indexa un documento en su base privada (multipart/form-data: campo file o text + filename).

curl -X POST https://app.sofiallm.com/v1/knowledge/documents \
  -H "Authorization: Bearer TU_API_KEY" \
  -F "file=@expediente_acme.pdf"

Lista los documentos de su colección.

Elimina un documento y todos sus fragmentos indexados.

curl -X POST https://app.sofiallm.com/v1/knowledge/query \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "¿Qué penalizaciones contempla el contrato con ACME?"}'

{
  "answer": "…respuesta con base en sus documentos…",
  "sources": ["expediente_acme.pdf"],
  "fragments_used": 5,
  "model": "sofia-llm-32b",
  "usage": { "prompt_tokens": 231, "completion_tokens": 138, "total_tokens": 369 }
}

Agentes

Un agente es una configuración con nombre propio: instrucciones (personalidad y proceso de su organización) + opcionalmente un skill base y acceso a su base de conocimiento. Se invoca por API desde cualquiera de sus sistemas y es privado de su cuenta.

curl -X POST https://app.sofiallm.com/v1/agents \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "asistente-legal",
    "instructions": "Eres el asistente legal interno de la firma. Responde con base en los expedientes y siempre indica nivel de riesgo (alto/medio/bajo).",
    "use_knowledge": true,
    "skill": "revisor-contratos"
  }'

Lista sus agentes.

Elimina un agente.

Conversa con el agente. Si tiene use_knowledge activo, recupera los fragmentos relevantes de sus documentos y responde citando fuentes.

curl -X POST https://app.sofiallm.com/v1/agents/1/chat \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "¿Qué riesgos tiene terminar anticipadamente el contrato con ACME?"}]}'

Fine-tuning (modelo privado)

Entrenamos un adaptador exclusivo con sus datos sobre el modelo base, obteniendo un modelo con el conocimiento y estilo de su organización, servido de forma aislada bajo su propio nombre. El proceso inicia subiendo su dataset por API; nuestro equipo agenda y ejecuta el entrenamiento como trabajo dedicado.

Formato del dataset

Archivo JSONL: una línea por ejemplo, cada una con el formato de conversación. Mínimo 10 ejemplos (recomendado: 100+):

{"messages": [{"role": "user", "content": "¿Cómo redactamos la cláusula de confidencialidad?"}, {"role": "assistant", "content": "En nuestra firma, la cláusula estándar establece…"}]}
{"messages": [{"role": "user", "content": "…"}, {"role": "assistant", "content": "…"}]}

curl -X POST https://app.sofiallm.com/v1/finetune/datasets \
  -H "Authorization: Bearer TU_API_KEY" \
  -F "file=@dataset.jsonl"

Dataset Studio: fabrique su dataset desde sus documentos

Si no cuenta con ejemplos preparados, la plataforma puede generarlos por usted a partir de su base de conocimiento: el modelo produce pares de pregunta-respuesta fieles a sus documentos, elimina duplicados y un juez de calidad automático puntúa cada ejemplo (1–10), señalando los que requieren revisión. El resultado se guarda como borrador con un reporte de certificación.

curl -X POST https://app.sofiallm.com/v1/finetune/prepare \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_name": "estilo-firma-v1",
    "source": "knowledge",
    "num_examples": 20,
    "style_hint": "tono formal legal, responde como la firma"
  }'

Certifica cualquier dataset (generado o subido): valida el esquema línea por línea, mide duplicados, calcula estadísticas y evalúa una muestra con el juez de calidad. Devuelve el reporte con veredicto: listo_para_entrenar o requiere_revision con los ejemplos señalados.

Detalle de un dataset: estado, reporte de certificación y muestra de ejemplos.

Consulta el estado de sus datasets (recibido / borrador → validado → en entrenamiento → desplegado).

Al completarse, su modelo queda disponible con su propio identificador (p. ej. sofia-llm-32b-sufirma), accesible únicamente con sus keys.

Facturación y límites

Modelo prepago

Su cuenta opera con crédito prepago. Cada petición descuenta según los tokens procesados; al agotarse el crédito, el servicio se pausa automáticamente (respuestas 429) hasta la recarga. Sin sorpresas ni facturas abiertas.

Referencia: 1 millón de tokens ≈ 750,000 palabras en español. Una consulta típica consume entre 100 y 2,000 tokens.

Créditos

En la consola, su saldo y consumo se presentan en créditos (1 USD = 1,000 créditos). Las tarifas equivalen a 400 créditos por millón de tokens de entrada y 1,200 créditos por millón de tokens de salida. Las recargas y la facturación contractual se expresan en USD.

Transparencia total

Cada petición queda registrada con su costo exacto, visible en la consola (sección Uso) y descargable para conciliación.

Consola de desarrollador

La consola es su centro de control, accesible con su API key:

• Resumen — saldo disponible, consumo, tokens y actividad reciente.
• Playground — pruebe el modelo sin escribir código; cada prueba muestra tokens y costo estimado.
• API keys — cree múltiples keys con alias, expiración y presupuesto; revoque individualmente sin afectar las demás.
• Uso — registro completo de peticiones con costo por llamada.
• Documentación — quickstart con código listo para copiar.
• Personalización — skills a la medida, base de conocimiento, agentes y fine-tuning.

Seguridad y protección de datos

SOF.IA LLM está diseñado para organizaciones que manejan información de terceros bajo estrictos deberes de confidencialidad. Esta sección describe los controles técnicos aplicados a su información en cada etapa.

¿Cómo envío mi información cifrada?

No necesita implementar ningún cifrado: es automático. Al hacer sus peticiones a https://api.sofiallm.com, la librería HTTP de su lenguaje negocia TLS con la plataforma y cifra todo el contenido — documentos, consultas y su API key — antes de que salga de sus servidores. Las respuestas del modelo regresan cifradas por el mismo canal y su librería las descifra de forma transparente. Las conexiones sin cifrar (http://) se rechazan y redirigen forzosamente al canal seguro, por lo que no es posible enviar información en claro ni por error.

Ciclo de vida de su información

Transparencia técnica: en el instante del procesamiento, el modelo requiere el texto en claro en memoria para poder analizarlo — esto es inherente a cualquier sistema de IA. La diferencia de SOF.IA LLM es dónde ocurre ese instante: en infraestructura dedicada bajo control de la plataforma, no en proveedores públicos compartidos, sin persistir el contenido de sus peticiones más allá de los registros de uso (tokens y costo) y sin usarlo jamás para entrenar modelos de terceros. Para requisitos donde ni siquiera la plataforma deba operar la infraestructura, existe la modalidad de despliegue on-premise como proyecto enterprise.

Cifrado en tránsito

Todo el tráfico viaja cifrado con TLS 1.2+ extremo a extremo: desde sus sistemas hasta la API (api.sofiallm.com), entre los componentes internos de la plataforma (gateway, motor de inferencia) y hacia la capa de persistencia. No existe ningún tramo de la cadena donde su información viaje en claro. Los certificados se renuevan automáticamente.

Cifrado en reposo

La capa de persistencia (documentos de su base de conocimiento, configuración de agentes, datasets y registros de uso) se almacena cifrada con AES-256 a nivel de almacenamiento, sobre infraestructura con certificaciones SOC 2. Los respaldos heredan el mismo cifrado.

Credenciales: hash irreversible

Las API keys no se almacenan en texto plano. La plataforma conserva únicamente su huella SHA-256 (hash criptográfico irreversible): la key completa existe solo en el momento de su creación, cuando se le muestra una única vez. Ni el personal de la plataforma puede recuperar una key emitida — solo revocarla o emitir una nueva. Cada key admite expiración automática y presupuesto propio.

Aislamiento multi-tenant

Cada registro de su información (documentos, fragmentos indexados, agentes, datasets) se almacena vinculado al identificador criptográfico de su cuenta (derivado por SHA-256). Toda consulta a la base de datos filtra por ese identificador a nivel de fila: la información de un cliente es estructuralmente inaccesible desde la cuenta de cualquier otro. No es una política — es el diseño del esquema de datos.

Sin entrenamiento de terceros

Su información nunca se utiliza para entrenar modelos ajenos a su cuenta. El modelo se ejecuta en infraestructura dedicada bajo control de la plataforma; sus peticiones no transitan por proveedores públicos de IA ni se comparten con terceros. Los entrenamientos privados (fine-tuning) usan exclusivamente el dataset que usted aporta y producen un modelo accesible únicamente con sus keys.

Gobernanza y trazabilidad

• Registro por petición — cada llamada queda registrada con fecha, key utilizada, tokens y costo, consultable en su consola para auditoría y conciliación.
• Control de gasto — presupuestos por cuenta y por key con bloqueo automático al agotarse.
• Revocación inmediata — cualquier key puede revocarse al instante desde la consola, sin intervención del proveedor.
• Sesión de consola — la credencial de sesión no se persiste en el equipo: se descarta al cerrar la pestaña del navegador.

Soporte

Para skills a la medida, acceso beta a agentes con herramientas (MCP), fine-tuning o cualquier consulta técnica, contacte a su ejecutivo de cuenta o escriba a soporte@sofia-llm.com.