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

Buenas prácticas

• Guarde la key en variables de entorno; nunca en código fuente ni repositorios.
• Use una key distinta por entorno (desarrollo / producción).
• Ante cualquier sospecha de filtración, rote la key desde la consola (API keys → Rotar key). La anterior queda invalidada de inmediato.

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"

Consulta el estado de sus datasets (recibido → 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.

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 — copie o rote su credencial en cualquier momento.
• 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 aislamiento

• Infraestructura privada — el modelo corre en infraestructura dedicada bajo control de la plataforma; su información no transita por proveedores públicos de IA.
• Aislamiento por cliente — documentos, agentes y datasets se almacenan con identificador criptográfico de su cuenta; toda consulta filtra por él a nivel de base de datos. Los datos de un cliente son inaccesibles para cualquier otro.
• Sin entrenamiento de terceros — su información nunca se usa para entrenar modelos ajenos a su cuenta.
• Credenciales — keys con presupuesto, rotación inmediata self-service y registro de actividad por petición.
• Transporte — todo el tráfico viaja cifrado por TLS.

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.