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

# Python
pip install ollama

# JavaScript / TypeScript
npm install ollama

Comparación de los métodos principales de las dos bibliotecas:

MétodoUsoParámetros clave
chatDiálogo multironda (método principal)model、messages、stream、tools、think、format、options
generateGeneración de texto de una sola rondamodel、prompt、stream、suffix
embedIncrustación de vectores (embeddings)model, input (único o array)
listListar modelos localesNinguno
pullDescargar 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 ollama import chat
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

import ollama from 'ollama'

// 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

import os
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.

EscenarioComando
Generación de una sola ronda (sin streaming)curl http://localhost:11434/api/generate -d '{"model":"qwen3.5","prompt":"Hola","stream":false}'
Diálogocurl 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 modeloscurl http://localhost:11434/api/tags
Detalles del modelocurl http://localhost:11434/api/show -d '{"model":"qwen3.5"}'
Descargar modelocurl http://localhost:11434/api/pull -d '{"model":"qwen3.5:4b"}'
Eliminar modelocurl -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

import OpenAI from "openai"

// 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

import anthropic

# 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

# Ruta del archivo: cli_chat.py
# 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

# Ruta del archivo: server.py
# 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

// En el navegador: leer NDJSON línea por línea y renderizar en tiempo real
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

# Iniciar el backend
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.

Este 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á.

Otras extensiones