Modelos de lenguaje (LLM)¶
Experimental
Los modulos de IA y modelos de lenguaje (ia, ia_lm, ia_text,
ia_audio, predicts, llm, ndjson_model) son experimentales: su API y
sus formatos pueden cambiar entre versiones menores sin periodo de
transicion, a diferencia del nucleo HTTP/WebSocket. Fija la version
(wsbuilder==X.Y.*) si dependes de ellos y revisa el
registro de cambios al actualizar.
wsbuilder.llm permite entrenar, importar, guardar, descargar y ejecutar
modelos de lenguaje. Tambien puede servirlos por HTTP, con un endpoint
compatible con la API de OpenAI. Los modelos se ejecutan con el motor nativo
de wsbuilder, escrito en Python puro: no hace falta llama.cpp ni ningun otro
motor externo.
| Pieza | Para que sirve | Dependencias |
|---|---|---|
ByteLanguageModel |
Modelo de lenguaje nativo: se entrena, genera texto y se guarda en NDJSON | Ninguna |
LanguageModel + NativeBackend |
Conversar con un modelo nativo (chat, generate, streaming) |
Ninguna |
ModelWriter / ModelReader |
Escribir y leer el formato de modelos de wsbuilder: un unico archivo NDJSON con el modelo y sus pesos | Ninguna |
ModelStore |
Directorio de modelos: importar, descargar, exportar, verificar y borrar | Ninguna |
download_file, huggingface_files |
Descargas reanudables y verificadas con SHA-256 | Ninguna |
LanguageModel + OpenAICompatibleBackend |
Opcional: usar un modelo que ya sirve otro programa por HTTP (API de OpenAI) | Ninguna |
install_llm / App.enable_llm |
Exponer los modelos por HTTP | Ninguna |
Todo funciona solo con la biblioteca estandar.
Inicio rapido: entrenar y conversar¶
from wsbuilder import ByteLanguageModel, LanguageModel
conversaciones = [
[{"role": "user", "content": "hola"}, {"role": "assistant", "content": "Hola, en que te ayudo?"}],
[{"role": "user", "content": "precio"}, {"role": "assistant", "content": "El plan cuesta 10 euros."}],
]
modelo = ByteLanguageModel(context=16, embedding=8, hidden=(64,), seed=1)
modelo.fit_chat(conversaciones, epochs=60, learning_rate=0.1, decay=0.97)
modelo.chat("precio", temperature=0) # "El plan cuesta 10 euros."
modelo.save("bot.ndjson", name="bot") # modelo + pesos en un NDJSON
bot = LanguageModel.from_file("bot.ndjson", temperature=0.7)
print(bot.chat("hola"))
El motor nativo: ByteLanguageModel¶
Es el modelo de lenguaje propio de wsbuilder (arquitectura wsbuilder.bytelm).
Lee los ultimos context bytes del texto UTF-8 y predice el siguiente byte con
una red neuronal: un vector por byte (embedding), una o varias capas tanh
(hidden) y un softmax sobre los 256 bytes mas un token de fin de texto.
| Metodo | Uso |
|---|---|
ByteLanguageModel(context=24, embedding=12, hidden=(96,), seed=None) |
Crea un modelo con pesos aleatorios. |
fit(textos, epochs=10, learning_rate=0.05, decay=0.9, progress=None) |
Entrena con textos. Devuelve el historial {"epoch", "loss", "learning_rate"}. |
fit_chat(conversaciones, ...) |
Entrena con conversaciones [{"role", "content"}, ...]. |
generate(prompt, **opciones) / stream(prompt, **opciones) |
Continua un texto, entero o por partes. |
chat(messages, **opciones) |
Responde a una conversacion. |
perplexity(texto) |
Mide lo bien que el modelo predice un texto (menos es mejor). |
save(ruta, dtype="F32", name=None) / ByteLanguageModel.load(ruta) |
Guarda y carga el modelo en NDJSON. |
Opciones de generacion: max_tokens (en bytes, 256 por defecto),
temperature (0 elige siempre el byte mas probable), top_k, top_p,
repeat_penalty, stop (texto o lista de textos) y seed.
- Formato de chat.
format_chat(messages)convierte la conversacion en<|user|>hola\n<|assistant|>. El modelo aprende ese formato confit_chaty la respuesta termina en el token de fin de texto o antes del siguiente\n<|. - Entrenamiento en segundo plano.
submit_lm_training_task(app.tasks, modelo, textos, epochs=...)entrena en una tarea deTaskManager; sumetadatamuestraepochylossmientras avanza. - Para que sirve. Es un modelo pequeno pensado para corpus pequenos y
concretos: respuestas de un asistente, comandos, preguntas frecuentes,
frases de un dominio. Solo ve los ultimos
contextbytes, asi que no mantiene conversaciones largas ni conocimiento general. - Rendimiento. Es Python puro: el coste de entrenar crece con
context * embedding * hiddenpor cada byte de texto y epoca. Concontext=16, embedding=8, hidden=(64,), cada byte de entrenamiento tarda unos 2-3 ms y generar una respuesta corta, milisegundos. Empieza con tamanos pequenos y entrena en una tarea.
El formato de modelos: NDJSON¶
wsbuilder usa un solo formato para los modelos y sus pesos: un archivo
NDJSON (JSON con un objeto por linea, extension .ndjson). No se aceptan
GGUF, safetensors ni otros formatos.
- Linea 1, el modelo. Formato, version, arquitectura, nombre, metadatos libres y el numero de tensores que siguen.
- Lineas siguientes, los pesos. Un tensor por linea con su nombre, su forma
(
shape), su tipo (dtype) y sus valores endata, en una lista plana y en orden por filas.
{"format":"wsbuilder-model","version":1,"architecture":"wsbuilder.dense","name":"xor","metadata":{"loss":"mse","activations":["tanh","sigmoid"]},"tensor_count":4}
{"tensor":"blk.0.weight","shape":[6,2],"dtype":"F64","data":[0.41,-1.2,...]}
{"tensor":"blk.0.bias","shape":[6],"dtype":"F64","data":[0.03,...]}
{"tensor":"blk.1.weight","shape":[1,6],"dtype":"F64","data":[...]}
{"tensor":"blk.1.bias","shape":[1],"dtype":"F64","data":[-0.2]}
from wsbuilder import ModelReader, ModelWriter
writer = ModelWriter(architecture="mi-modelo", name="demo")
writer.add_metadata("context_length", 2048) # cualquier valor JSON
writer.add_tensor("capa.0.weight", [[0.1, 0.2], [0.3, 0.4]], dtype="F32")
writer.add_tensor("capa.0.bias", [0.0, 0.0])
writer.write("demo.ndjson") # escritura atomica
with ModelReader("demo.ndjson") as model:
model.architecture, model.name, model.metadata
model.summary() # parametros, dtypes, tamano...
model.tensor("capa.0.weight").shape # (2, 2)
model.tensor("capa.0.weight").rows() # [[0.1, 0.2], [0.3, 0.4]] (redondeado a F32)
- Tipos.
F64(exacto),F32yF16(los valores se redondean a esa precision al escribir),I32eI64. NaN e infinito, que JSON no admite, se escriben como"NaN","Infinity"y"-Infinity". - Lectura por partes. Al abrir,
ModelReadervalida cada linea (nombres, tipos, formas y cantidad de valores) y recuerda donde empieza cada tensor;tensor(nombre).values()solo vuelve a leer esa linea. - Entrada no confiable. Un archivo con lineas que no son JSON, tensores
repetidos, valores que no cuadran con la forma o un
tensor_countdistinto del real se rechaza conModelFormatError. - Portable. Es texto plano: cualquier lenguaje con un parser JSON puede
leerlo linea a linea, y
head -1 modelo.ndjsonmuestra el modelo.
Guardar modelos: el almacen¶
from wsbuilder import ModelStore
store = ModelStore() # $WSBUILDER_MODELS o ~/.cache/wsbuilder/models
record = store.import_file("descargas/mi-modelo.ndjson")
print(record.id, record.summary["architecture"], record.summary["parameters"])
for model in store.list():
print(model.id, model.format, model.size, model.sha256)
store.export(record.id, "/backup/") # copia el archivo fuera del almacen
store.verify(record.id) # recalcula el SHA-256
store.rename(record.id, "Mi modelo")
with store.open(record.id) as reader: # ModelReader sobre el archivo guardado
reader.tensor("capa.0.weight").values()
store.remove(record.id)
- Cada modelo vive en
<raiz>/<id>/junto a unmanifest.jsoncon su nombre, formato, tamano, SHA-256, origen y un resumen de sus metadatos. Como no hay un indice compartido, no hay nada comun que se pueda corromper. Las escrituras pasan por archivos temporales yos.replace. - Solo se aceptan modelos NDJSON de wsbuilder. Otros archivos se rechazan
salvo que se pase
require_known_format=False(quedan guardados con formatounknown, pero no se pueden abrir). Un archivo malformado nunca entra al almacen. import_file(..., move=True)mueve el archivo en vez de copiarlo.
El resumen incluye name, architecture, parameters, tensors, dtypes
(valores por tipo), metadata y file_size.
Descargar modelos¶
Desde Hugging Face:
from wsbuilder import ModelStore, huggingface_files
files = huggingface_files("usuario/mi-modelo", suffix=".ndjson")
# [{"path": "mi-modelo.ndjson", "size": 1048576, "sha256": "..."}, ...]
store = ModelStore()
record = store.download_huggingface(
"usuario/mi-modelo",
"mi-modelo.ndjson",
progress=lambda done, total: print(done, total),
)
Desde cualquier URL HTTPS:
record = store.download("https://example.com/modelo.ndjson", sha256="...")
- Verificacion.
download_huggingfacetoma de la API del Hub el SHA-256 publicado y lo comprueba. Si no coincide, el archivo se borra y se lanzaDownloadError. - Reanudacion. Si la descarga se corta, el siguiente intento continua desde
el archivo
.partcon una peticionRange. Solo se reanuda cuando hay un SHA-256 con el que verificar el resultado. - Limites. Solo se aceptan URLs
https://.max_bytesacota el tamano (200 GiB por defecto) ycancel_eventpermite cancelar la descarga. - Repositorios privados. El token se toma de
token=o deHF_TOKENy se envia solo al host original: si el Hub redirige a su CDN, la cabeceraAuthorizationno viaja.HF_ENDPOINTpermite usar un mirror.
Ejecutar modelos¶
Los modelos nativos guardados en el almacen se ejecutan sin configurar nada:
from wsbuilder import ModelStore
store = ModelStore()
record = store.add(modelo, name="Mi bot") # guarda un ByteLanguageModel en el almacen
bot = store.load(record.id, temperature=0.7) # LanguageModel nativo, cacheado por id
print(bot.chat("Hola"))
for piece in bot.stream_chat([{"role": "user", "content": "precio"}], max_tokens=64):
print(piece, end="", flush=True)
Las opciones de store.load son las opciones de generacion por defecto de ese
modelo. Un modelo guardado que no es de lenguaje (por ejemplo una red
wsbuilder.dense) no se puede usar para conversar: store.load lanza
NotImplementedError y la API HTTP responde 501. Tambien puedes crear un
LanguageModel directamente con LanguageModel.native(modelo) o
LanguageModel.from_file("bot.ndjson").
Opcionalmente, un modelo que ya sirve otro programa con la API de OpenAI se usa
con LanguageModel.from_openai("http://localhost:11434/v1", "nombre").
ModelStore(loader=...) permite sustituir el motor nativo por uno propio:
loader(record, **opciones) recibe el ModelRecord y devuelve un
LanguageModel.
| Metodo | Devuelve |
|---|---|
generate(prompt, **opciones) |
El texto completado. |
chat(messages, **opciones) |
La respuesta del asistente. messages puede ser un texto o una lista de {"role", "content"}. |
chat_completion(messages, **opciones) |
{"text", "finish_reason", "usage"}. |
stream_generate, stream_chat |
Generadores que van entregando el texto. |
Las opciones admitidas son max_tokens, temperature, top_p, top_k,
stop, seed, repeat_penalty, presence_penalty y frequency_penalty.
Servir modelos por HTTP¶
from wsbuilder import App, ModelStore
app = App()
app.enable_security(...) # protege estas rutas antes de exponerlas
app.enable_llm(
ModelStore(),
backend_options={"temperature": 0.7}, # opciones por defecto de los modelos nativos
allow_train=True,
)
app.run("0.0.0.0", 8765)
| Ruta | Uso |
|---|---|
GET /api/llm/models |
Lista los modelos del almacen y los remotos. |
GET /api/llm/model?id= |
Devuelve el manifiesto de un modelo. |
POST /api/llm/chat |
Recibe {"model", "messages", "stream"}. Con stream, responde en NDJSON ({"content": ...} por linea). |
POST /api/llm/generate |
Recibe {"model", "prompt", "stream"}. |
GET /v1/models, POST /v1/chat/completions |
API de OpenAI, con streaming SSE incluido. Cualquier cliente de OpenAI puede apuntar a la app. |
Las rutas que modifican el disco del servidor estan desactivadas por defecto:
allow_download=TrueactivaPOST /api/llm/download({"repo", "filename"}o{"url", "sha256"}). La descarga corre como tarea en segundo plano y su progreso se consulta enGET /api/llm/tasks?id=.download_hostsrestringe los hosts permitidos.allow_import=TrueactivaPOST /api/llm/import({"path"}).allow_delete=TrueactivaPOST /api/llm/delete({"id"}).allow_train=TrueactivaPOST /api/llm/train: entrena un modelo nativo en segundo plano y lo guarda en el almacen. Recibe{"name", "texts"}o{"name", "conversations"}y, opcionalmente,context,embedding,hidden,epochs,learning_rateyseed. Responde{"task"}; enGET /api/llm/tasks?id=se venepochylossy, al terminar, el manifiesto del modelo nuevo.train_limitsajusta los limites deDEFAULT_TRAIN_LIMITS(1 MiB de texto,context128,embedding64, capas de hasta 512 unidades, 500 epocas).
Redes propias¶
Las redes de NeuralNetwork se guardan en el mismo formato NDJSON, con la
arquitectura wsbuilder.dense:
network.save("xor.ndjson", name="xor") # dtype="F64" (exacto), "F32" o "F16"
same = NeuralNetwork.load("xor.ndjson") # mismas predicciones
record = store.import_file("xor.ndjson")
same = store.load_network(record.id)