Интеграция Ollama с языками программирования
В этой статье систематически описаны четыре способа вызова Ollama из кода: официальная библиотека Python, официальная библиотека JavaScript, нативный HTTP и SDK, совместимые с OpenAI / Anthropic, а также их объединение с помощью двух практических проектов.
Официальный SDK: Python и JavaScript
Официальная команда напрямую поддерживает две библиотеки с согласованным дизайном API; если вы знаете одну, вы знаете и обе.
Установка
pip install ollama
# JavaScript / TypeScript
npm install ollama
Сравнение основных методов в двух библиотеках:
| Метод | Назначение | Ключевые параметры |
|---|---|---|
| chat | Многоходовой диалог (основной метод) | model、messages、stream、tools、think、format、options |
| generate | Одноходовая генерация текста | model、prompt、stream、suffix |
| embed | Векторное представление | model, input (один элемент или массив) |
| list | Список локальных моделей | Отсутствует |
| pull | Загрузка модели (прогресс можно отслеживать) | model、stream |
Вызов чата с полным набором параметров на Python охватывает большинство возможностей, изученных в предыдущих статьях:
Пример
from pydantic import BaseModel
# Определение схемы структурированного вывода
class Answer(BaseModel):
site: str
free: bool
response = chat(
model='qwen3.5',
messages=[{'role': 'user', 'content': 'Расскажи о Python'}],
stream=False, # Переключатель потоковой передачи
think=False, # Переключатель режима размышления
format=Answer.model_json_schema(), # Схема структурированного вывода
options={'temperature': 0.3, 'num_ctx': 8192}, # Параметры генерации
)
print(Answer.model_validate_json(response.message.content))
Эквивалентный код на JavaScript:
Пример
// Пример потокового чата
const stream = await ollama.chat({
model: 'qwen3.5',
messages: [{ role: 'user', content: 'Опиши Python в трёх предложениях' }],
stream: true,
})
// Выводить фрагмент за фрагментом
let content = ''
for await (const chunk of stream) {
process.stdout.write(chunk.message.content)
content += chunk.message.content
}
При подключении к адресу, отличному от адреса по умолчанию (например, к удалённому серверу или Ollama Cloud), укажите его с помощью host и headers:
Пример
from ollama import Client
# Подключение к удалённому Ollama или Ollama Cloud (Bearer-аутентификация)
клиент = Клиент(
host='https://ollama.com',
headers={'Authorization': 'Bearer ' + os.environ.get('OLLAMA_API_KEY')},
)
response = client.chat(model='qwen3.5', messages=[
{'role': 'user', 'content': 'Расскажи о Python в одном предложении'}
])
Нативный HTTP: Краткий справочник по curl
При написании скриптов, отладке API или устранении неполадок curl — самый быстрый инструмент.
| Сценарий | Команда |
|---|---|
| Однооборотная генерация (без потоковой передачи) | curl http://localhost:11434/api/generate -d '{"model":"qwen3.5","prompt":Hello,"stream":false}' |
| Чат | curl http://localhost:11434/api/chat -d '{"model":"qwen3.5","messages":[...],"stream":false}' |
| Векторное представление | curl http://localhost:11434/api/embed -d '{"model":"embeddinggemma","input":"Text"}' |
| Список моделей | curl http://localhost:11434/api/tags |
| Сведения о модели | curl http://localhost:11434/api/show -d '{"model":"qwen3.5"}' |
| Загрузить модель | curl http://localhost:11434/api/pull -d '{"model":"qwen3.5:4b"}' |
| Удалить модель | curl -X DELETE http://localhost:11434/api/delete -d '{"model":"qwen3.5:4b"}' |
Повторное использование OpenAI / Anthropic SDK
При миграции существующих проектов слой совместимости создаёт гораздо меньше проблем, чем переписывание.
В проекте на JavaScript используйте OpenAI SDK для подключения к локальным моделям:
Пример
// Меняйте только base_url; api_key может быть любым
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: "Расскажи о Python в одном предложении" }],
})
console.log(res.choices[0].message.content)
То же самое применимо в проекте Python с использованием Anthropic SDK:
Пример
# Укажите в base_url локальный адрес, ключ может быть любым
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': 'Расскажи о Python в одном предложении'}],
)
print(message.content[0].text)
Рекомендация: для новых проектов используйте официальный SDK напрямую (наиболее полный набор возможностей); для существующих проектов — идите через слой совместимости, основанный на текущем SDK (минимальные изменения); при интеграции с фреймворком, который поддерживает только протокол OpenAI, слой совместимости — единственный путь.
Практика 1: Скрипт чата из командной строки
Менее чем в 40 строках Python соберите чат, потоковую передачу и управление историей из предыдущих разделов в удобный инструмент чата для терминала.
Пример
# Запуск: python cli_chat.py
from ollama import chat
MODEL = 'qwen3.5:4b'
# История сессии: система задаёт роль, затем добавляйте сообщения диалога
messages = [{
'role': 'system',
'content': 'Ты — ассистент EXAMPLE по программированию. Отвечай кратко и приводи примеры кода.',
}]
print(f'Начать чат (модель {MODEL}), введите exit для выхода.')
while True:
user_input = input('\n'Вы: ').strip()
if user_input.lower() == 'exit':
break
if not user_input:
continue
# Добавьте сообщение пользователя и запустите потоковый запрос
messages.append({'role': 'user', 'content': user_input})
stream = chat(model=MODEL, messages=messages, stream=True)
# Выводить по фрагментам, накапливая полный ответ
print('Ассистент: ', end='', flush=True)
reply = ''
for chunk in stream:
reply += chunk.message.content
print(chunk.message.content, end='', flush=True)
# Ключевой момент: добавляйте ответ этого раунда обратно в историю, чтобы модель могла "помнить" контекст
messages.append({'role': 'assistant', 'content': reply})
$ python cli_chat.py 开始对话(模型 qwen3.5:4b),输入 exit 退出。 你:什么是 Python 的切片? 助手:切片是用 [start:stop:step] 从序列中取子序列的语法, 例如 s[1:3] 取索引 1 到 2 的元素。 你:给个 EXAMPLE 风格的例子 助手:s = "EXAMPLE" print(s[1:4]) # 输出 UNO 你:exit
Есть только один ключевой момент: при каждом ходе добавляйте и сообщение пользователя, и полный ответ ассистента в messages. Сама модель не имеет состояния; "память" полностью исходит из этого списка.
Практика 2: Веб-приложение многоходового диалога с памятью
Чтобы перенести ту же идею в браузер, нужен бэкенд, который координирует процесс посередине: управляет историей диалога, вызывает Ollama и передаёт результаты потоковой передачи на фронтенд.
Бэкенд: Flask-обёртка для потокового API Ollama
Пример
# Установите зависимости: pip install flask ollama
from flask import Flask, request, Response, stream_with_context
from ollama import chat
app = Flask(__name__)
# История сессии временно хранится в памяти: в реальном проекте вместо этого следует использовать базу данных
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': 'Отсутствует параметр q'}
# Получить (или инициализировать) историю для этой сессии
history = sessions.setdefault(session_id, [
{'role': 'system', 'content': 'Вы — помощник по программированию от EXAMPLE.'}
])
history.append({'role': 'user', 'content': user_input})
# Потоковая генерация, передаваемая построчно на фронтенд в формате 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'
# Ключ: записать полный ответ обратно в историю, чтобы сформировать память
history.append({'role': 'assistant', 'content': reply})
return Response(
stream_with_context(generate()),
mimetype='application/x-ndjson',
)
if __name__ == '__main__':
app.run(port=5000)
Фронтенд: потоковое чтение с fetch
Пример
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
// Добавляйте каждый фрагмент на страницу по мере его поступления для эффекта печатной машинки
document.getElementById('answer').textContent +=
decoder.decode(value)
}
}
Запуск и проверка
Пример
python server.py
# Смоделируйте два последовательных запроса для проверки памяти
curl http://localhost:5000/chat?session=demo&q=什么YesPythonSlice
curl "http://localhost:5000/chat?session=demo&q=再GiveitemsEXAMPLEWind格ofExamples"
Во втором запросе модель продолжает отвечать в рамках темы «срезы», что показывает, что серверная история сессии работает; использование другого параметра session запускает совершенно новую сессию без взаимного влияния.
Другие расширенияЭтот каркас из нескольких десятков строк уже охватывает три ключевых элемента приложения в стиле ChatGPT: изоляцию сессий (параметр session), потоковую передачу (пересылку NDJSON) и постоянную память (обратную запись истории). Добавьте хранилище базы данных и список нескольких сессий — и он станет прототипом полноценного практического проекта; глава «Практика веб-приложений» продолжит его расширять.