Ollama Llamadas desde lenguajes de programación
Este artículo revisa sistemáticamente cuatro rutas de código para llamar a Ollama: la biblioteca oficial de Python, la biblioteca oficial de JavaScript, HTTP nativo y los SDK compatibles con OpenAI / Anthropic, y las conecta con dos proyectos prácticos.
SDK oficial: Python y JavaScript
La organización oficial proporciona dos bibliotecas mantenidas directamente, con diseños de interfaz consistentes: si sabes usar una, sabes usar las dos.
Instalación
pip install ollama
# JavaScript / TypeScript
npm install ollama
Comparación de los métodos principales de las dos bibliotecas:
| Método | Uso | Parámetros clave |
|---|---|---|
| chat | Diálogo multironda (método principal) | model、messages、stream、tools、think、format、options |
| generate | Generación de texto de una sola ronda | model、prompt、stream、suffix |
| embed | Incrustación de vectores (embeddings) | model, input (único o array) |
| list | Listar modelos locales | Ninguno |
| pull | Descargar modelo (con posibilidad de monitorear el progreso) | model、stream |
Una llamada a chat con todos los parámetros en Python, que cubre la mayoría de las capacidades aprendidas en los artículos anteriores:
Ejemplo
from pydantic import BaseModel
# Definir el schema de salida estructurada
class Answer(BaseModel):
site: str
free: bool
response = chat(
model='qwen3.5',
messages=[{'role': 'user', 'content': 'Presenta EJEMPLO Tutorial para principiantes'}],
stream=False, # Interruptor de streaming
think=False, # Interruptor de modo de pensamiento
format=Answer.model_json_schema(), # Schema de salida estructurada
options={'temperature': 0.3, 'num_ctx': 8192}, # Parámetros de generación
)
print(Answer.model_validate_json(response.message.content))
Escritura equivalente en JavaScript:
Ejemplo
// Ejemplo de diálogo en streaming
const stream = await ollama.chat({
model: 'qwen3.5',
messages: [{ role: 'user', content: 'Presenta EJEMPLO en tres frases' }],
stream: true,
})
// Salida por fragmentos
let content = ''
for await (const chunk of stream) {
process.stdout.write(chunk.message.content)
content += chunk.message.content
}
Al conectarse a una dirección que no es la predeterminada (como un servidor remoto o Ollama Cloud), se especifica con host y headers:
Ejemplo
from ollama import Client
# Conectar a Ollama remoto u Ollama Cloud (autenticación Bearer)
client = Client(
host='https://ollama.com',
headers={'Authorization': 'Bearer ' + os.environ.get('OLLAMA_API_KEY')},
)
response = client.chat(model='qwen3.5', messages=[
{'role': 'user', 'content': 'Presenta EJEMPLO en una frase'}
])
HTTP nativo: referencia rápida de curl
Al escribir scripts, depurar interfaces o solucionar problemas, curl es la herramienta más rápida.
| Escenario | Comando |
|---|---|
| Generación de una sola ronda (sin streaming) | curl http://localhost:11434/api/generate -d '{"model":"qwen3.5","prompt":"Hola","stream":false}' |
| Diálogo | curl http://localhost:11434/api/chat -d '{"model":"qwen3.5","messages":[...],"stream":false}' |
| Incrustación de vectores (embeddings) | curl http://localhost:11434/api/embed -d '{"model":"embeddinggemma","input":"文本"}' |
| Listar modelos | curl http://localhost:11434/api/tags |
| Detalles del modelo | curl http://localhost:11434/api/show -d '{"model":"qwen3.5"}' |
| Descargar modelo | curl http://localhost:11434/api/pull -d '{"model":"qwen3.5:4b"}' |
| Eliminar modelo | curl -X DELETE http://localhost:11434/api/delete -d '{"model":"qwen3.5:4b"}' |
Reutilizar los SDK de OpenAI / Anthropic
Al migrar proyectos existentes, la capa de compatibilidad es mucho más conveniente que reescribir.
En un proyecto JavaScript, usar el SDK de OpenAI para conectarse a un modelo local:
Ejemplo
// Solo cambia base_url, api_key se puede rellenar arbitrariamente
const openai = new OpenAI({
baseURL: "http://localhost:11434/v1",
apiKey: "ollama",
})
const res = await openai.chat.completions.create({
model: "qwen3.5",
messages: [{ role: "user", content: "Presenta EJEMPLO en una frase" }],
})
console.log(res.choices[0].message.content)
En un proyecto Python, usar el SDK de Anthropic es similar:
Ejemplo
# base_url apunta a local, key se puede rellenar arbitrariamente
client = anthropic.Anthropic(
base_url='http://localhost:11434',
api_key='ollama',
)
message = client.messages.create(
model='qwen3.5',
max_tokens=1024,
messages=[{'role': 'user', 'content': 'Presenta EJEMPLO en una frase'}],
)
print(message.content[0].text)
Recomendación de elección: para proyectos nuevos, usa directamente el SDK oficial (es el más completo en capacidades); para proyectos existentes, sigue la capa de compatibilidad con el SDK actual (cambios mínimos); cuando te integres con un framework que solo reconoce el protocolo OpenAI, la capa de compatibilidad es la única vía.
Proyecto práctico 1: script de chat por línea de comandos
Con menos de 40 líneas de Python, combina el chat, el streaming y la gestión de historial aprendidos anteriormente en una herramienta de chat de terminal utilizable.
Ejemplo
# Ejecutar: python cli_chat.py
from ollama import chat
MODEL = 'qwen3.5:4b'
# Historial de la sesión: system define el rol y luego se añaden los diálogos
messages = [{
'role': 'system',
'content': 'Eres el asistente de programación de EJEMPLO, responde de forma concisa y proporciona código de ejemplo.',
}]
print(f'Inicia el diálogo (modelo {MODEL}), escribe exit para salir.')
while True:
user_input = input('\n'Tú: ').strip()
if user_input.lower() == 'exit':
break
if not user_input:
continue
# Añadir el mensaje del usuario y realizar una solicitud en streaming
messages.append({'role': 'user', 'content': user_input})
stream = chat(model=MODEL, messages=messages, stream=True)
# Imprimir por fragmentos mientras se acumula la respuesta completa
print('Asistente: ', end='', flush=True)
reply = ''
for chunk in stream:
reply += chunk.message.content
print(chunk.message.content, end='', flush=True)
# Clave: añadir la respuesta de esta ronda al historial para que el modelo pueda "recordar" el contexto anterior
messages.append({'role': 'assistant', 'content': reply})
$ python cli_chat.py 开始对话(模型 qwen3.5:4b),输入 exit 退出。 你:什么是 Python 的切片? 助手:切片是用 [start:stop:step] 从序列中取子序列的语法, 例如 s[1:3] 取索引 1 到 2 的元素。 你:给个 EJEMPLO 风格的例子 助手:s = "EJEMPLO" print(s[1:4]) # 输出 UNO 你:exit
El núcleo es solo uno: en cada ronda, agregar tanto el mensaje de user como la respuesta completa de assistant a messages. El modelo en sí no tiene estado; la "memoria" proviene completamente de esta lista.
Proyecto práctico 2: aplicación web de diálogo multironda con memoria
Para llevar la misma idea al navegador, se necesita un backend que coordine en el centro: gestionar el historial de la sesión, llamar a Ollama y reenviar los resultados en streaming al frontend.
Backend: Flask envuelve la interfaz de streaming de Ollama
Ejemplo
# Instalar dependencias: pip install flask ollama
from flask import Flask, request, Response, stream_with_context
from ollama import chat
app = Flask(__name__)
# El historial de la sesión se almacena temporalmente en memoria: en proyectos reales debería sustituirse por una base de datos
sessions = {}
@app.route('/chat')
def do_chat():
session_id = request.args.get('session', 'default')
user_input = request.args.get('q', '')
if not user_input:
return {'error': 'Falta el parámetro q'}
# Obtener (o inicializar) el historial de esa sesión
history = sessions.setdefault(session_id, [
{'role': 'system', 'content': 'Eres el asistente de programación de EJEMPLO.'}
])
history.append({'role': 'user', 'content': user_input})
# Generación en streaming, reenviada al frontend línea por línea en formato NDJSON
def generate():
reply = ''
stream = chat(model='qwen3.5:4b', messages=history, stream=True)
for chunk in stream:
reply += chunk.message.content
yield chunk.message.content + '\n'
# Clave: escribir la respuesta completa de vuelta al historial para formar la memoria
history.append({'role': 'assistant', 'content': reply})
return Response(
stream_with_context(generate()),
mimetype='application/x-ndjson',
)
if __name__ == '__main__':
app.run(port=5000)
Frontend: lectura en streaming con fetch
Ejemplo
async function ask(question) {
const resp = await fetch(
`/chat?session=demo&q=${encodeURIComponent(question)}`
)
const reader = resp.body.getReader()
const decoder = new TextDecoder()
while (true) {
const { done, value } = await reader.read()
if (done) break
// Cada fragmento leído se añade a la página, logrando un efecto de máquina de escribir
document.getElementById('answer').textContent +=
decoder.decode(value)
}
}
Ejecución y verificación
Ejemplo
python server.py
# Simular dos solicitudes consecutivas para verificar la memoria
curl http://localhost:5000/chat?session=demo&q=什么SíPython切片
curl http://localhost:5000/chat?session=demo&q=再ParaunidadEJEMPLOviento格deEjemplo子
En la segunda solicitud, el modelo puede continuar respondiendo siguiendo el tema "slicing", lo que demuestra que el historial de la sesión gestionado por el servidor ha surtido efecto; al cambiar el parámetro session se obtiene una sesión completamente nueva, sin interferencias mutuas.
Otras extensionesEste esqueleto de unas pocas docenas de líneas ya cubre los tres elementos esenciales de una aplicación tipo ChatGPT: aislamiento de sesiones (parámetro session), experiencia de streaming (reenvío NDJSON) y persistencia de memoria (escritura del historial). Añadiendo almacenamiento en base de datos y una lista de múltiples sesiones, se obtiene el prototipo de un proyecto práctico completo; el capítulo de práctica de aplicaciones web lo ampliará.