Ollama Python Library: Memulai LLM Secara Lokal

API LLM berbasis cloud memang kuat, tetapi ada kompromi: harga berbasis penggunaan, batas laju, dan ketidakpastian berkelanjutan tentang di mana data Anda diproses. Bagi pengembang yang bekerja dengan data sensitif atau bereksperimen secara intensif, kendala ini cepat menjadi hambatan.

Di sinilah pendekatan local-first menonjol. Perpustakaan Python Ollama menghilangkan hambatan itu dengan memungkinkan Anda menjalankan large language model secara lokal sambil berinteraksi dengannya menggunakan kode Python yang bersih dan native. Ini memberi Anda kendali penuh atas kinerja, biaya, dan privasi.

Dalam artikel ini, saya akan memandu Anda melalui API perpustakaan Python Ollama secara lengkap, mulai dari pembuatan teks sederhana dengan generate() hingga pemanggilan tool dan model visi.

Saya juga menyarankan Anda melihat tutorial Ollama terbaru kami lainnya:

• Tutorial Gemma 4: Membangun Agen Koding AI Lokal dengan Gradio dan Ollama
• Tutorial Qwen 3.5 Small Models: Bangun Generator Video-ke-Gim dengan Ollama
• Menggunakan OpenClaw dengan Ollama: Membangun Analis Data Lokal
• Menggunakan Claude Code dengan Model Lokal Ollama

Prasyarat Menjalankan Ollama dengan Python

Sebelum memulai, pastikan perangkat Anda sudah menyiapkan hal-hal berikut:

• Python 3.8 atau lebih baru

• Ollama diunduh dari situs web-nya, diinstal, dan berjalan (ollama serve)

• Setidaknya satu model sudah ditarik (misalnya, ollama pull llama3.2)

Prasyarat ini penting karena SDK Python hanyalah klien; inferensi sebenarnya terjadi di runtime Ollama. Jika runtime tidak tersedia atau tidak ada model yang sesuai, pemanggilan akan gagal.

Anda juga dapat mempertimbangkan menggunakan Docker dengan Ollama untuk konsistensi versi.

Apa Itu Perpustakaan Python Ollama?

Perpustakaan Python Ollama adalah SDK resmi yang membungkus REST API Ollama menjadi antarmuka yang sederhana dan Pythonic. Dengan kata lain, ini mengubah permintaan HTTP tingkat rendah dan payload JSON menjadi fungsi-fungsi Python tingkat tinggi sehingga Anda bisa fokus pada tujuan alih-alih detail transport.

Seiring aplikasi Anda berkembang, abstraksi ini menghilangkan pembuatan permintaan berulang, menstandarkan cara respons ditangani, dan memusatkan penanganan error di satu tempat.

Sebagai perbandingan, permintaan mentah mungkin terlihat seperti ini:

import requests

response = requests.post(
    "http://localhost:11434/api/generate",
    json={
        "model": "llama3.2",
        "prompt": "Explain recursion"
    }
)

Ini berfungsi, tetapi cepat menjadi bertele-tele dan rawan error. Dengan SDK, tugas yang sama menjadi:

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Explain recursion'
)

Cara perpustakaan berkomunikasi dengan server Ollama

Di balik layar, setiap pemanggilan SDK menjadi permintaan HTTP ke server Ollama di http://localhost:11434. Skrip Python Anda bertindak sebagai klien, sementara runtime Ollama bertindak sebagai server yang meng-host dan mengeksekusi model.

Pemisahan ini penting karena memungkinkan model berjalan sebagai layanan khusus, membuat manajemen sumber daya (CPU/GPU) lebih efisien dan memungkinkan banyak aplikasi berbagi instance model yang sama.

Jika Anda perlu terhubung ke mesin lain, Anda bisa mengonfigurasi klien khusus:

from ollama import Client

client = Client(host='http://remote-server:11434')
response = client.generate(model='llama3.2', prompt='Hello')

Menginstal dan mengonfigurasi perpustakaan

Instalasi sederhana dan hanya memerlukan dependensi minimal:

pip install ollama

Setelah instalasi, sebaiknya verifikasi konektivitas dengan mencantumkan model yang tersedia. 

Ini membantu Anda memastikan bahwa lingkungan Python, SDK, dan runtime Ollama semuanya terhubung dengan benar.

Untuk melakukannya, jalankan perintah berikut:

import ollama

print(ollama.list())

Menghasilkan Teks Menggunakan generate()

Fungsi generate() dirancang untuk tugas tanpa status, artinya setiap permintaan ditangani secara independen tanpa memori interaksi sebelumnya. Ini ideal untuk tugas seperti peringkasan, penulisan ulang, atau pembuatan kode.

Karena tidak ada konteks yang dipertahankan, kualitas keluaran sepenuhnya bergantung pada seberapa jelas prompt ditulis.

Pembuatan teks dasar

Contoh berikut menunjukkan alur kerja paling sederhana: kirim prompt, terima respons, dan ekstrak teks yang dihasilkan.

import ollama

response = ollama.generate(
    model='llama3.2',
    prompt='Write a Python docstring for a function that calculates factorial'
)

print(response['response'])

Respons juga menyertakan metadata seperti waktu eksekusi dan jumlah token, yang berguna saat mengoptimalkan kinerja.

Menyesuaikan keluaran dengan parameter

Perilaku generasi dapat disesuaikan menggunakan parameter sampling, yang mengontrol bagaimana model memilih token.

Nilai temperature yang lebih rendah menghasilkan keluaran yang lebih deterministik, sementara nilai yang lebih tinggi memperkenalkan lebih banyak variasi. Anda dapat menggunakan parameter seperti top_p dan num_predict untuk menyempurnakan keragaman dan panjang keluaran.

Berikut beberapa parameter penting yang bisa Anda gunakan: 

Berikut contoh penggunaan parameter top_p, temperature, dan num_predict:

response = ollama.generate(
    model='llama3.2',
    prompt='Explain machine learning in one paragraph',
    options={
        'temperature': 0.2,
        'top_p': 0.9,
        'num_predict': 100
    }
)

Membangun Percakapan Menggunakan chat()

Berbeda dengan generate(), API chat() mendukung interaksi berstatus dengan bekerja pada serangkaian pesan. Ini memungkinkan model mempertahankan konteks di beberapa putaran.

Setiap pesan menyertakan peran, seperti user, assistant, atau system, yang membantu menyusun percakapan.

Permintaan chat satu putaran

Bahkan interaksi satu putaran pun menggunakan format pesan, yang menjadi dasar untuk percakapan yang lebih kompleks.

response = ollama.chat(
    model='llama3.2',
    messages=[
        {'role': 'user', 'content': 'Explain Python decorators'}
    ]
)

print(response['message']['content'])

Mempertahankan konteks multi-putaran

Untuk mempertahankan konteks, Anda secara eksplisit menyimpan dan mengirim ulang seluruh riwayat percakapan pada setiap permintaan. Ini memberi Anda kendali penuh atas apa yang diingat model.

messages = [
    {'role': 'user', 'content': 'What is recursion?'}
]

response = ollama.chat(model='llama3.2', messages=messages)
messages.append(response['message'])

messages.append({'role': 'user', 'content': 'Give an example in Python'})
response = ollama.chat(model='llama3.2', messages=messages)

Menggunakan system prompt untuk membentuk perilaku

System prompt digunakan untuk mendefinisikan perilaku model di awal, seperti nada, batasan, atau peran.

messages = [
    {'role': 'system', 'content': 'You are a strict Python code reviewer.'},
    {'role': 'user', 'content': 'Review this code: def add(a,b): return a+b'}
]

Dukungan Streaming dan Async di Perpustakaan Python Ollama

Untuk aplikasi interaktif, daya tanggap sama pentingnya dengan ketepatan. Ollama mendukung eksekusi streaming dan asynchronous untuk meningkatkan kinerja dan pengalaman pengguna.

Streaming respons secara real time

Streaming memungkinkan Anda memproses keluaran secara bertahap saat dihasilkan, alih-alih menunggu seluruh respons.

for chunk in ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Write a story'}],
    stream=True
):
    print(chunk['message']['content'], end='', flush=True)

Menggunakan AsyncClient untuk aplikasi async

Eksekusi asynchronous memungkinkan aplikasi Anda menangani banyak permintaan secara bersamaan tanpa memblokir. Anda perlu menggunakan pustaka asyncio Python untuk menerapkannya.

Mari lihat contoh di bawah ini:

import asyncio
from ollama import AsyncClient

async def main():
    client = AsyncClient()
    async for chunk in await client.chat(
        model='llama3.2',
        messages=[{'role': 'user', 'content': 'Explain async programming'}],
        stream=True
    ):
        print(chunk['message']['content'], end='')

asyncio.run(main())

Mengelola Model Ollama dari Python

SDK Ollama juga menyediakan tool untuk mengelola model secara terprogram, yang sangat berguna di lingkungan otomatis.

Mendaftar dan memeriksa model lokal

Anda dapat mengambil daftar model yang tersedia dan memeriksa propertinya, seperti ukuran dan konfigurasinya.

models = ollama.list()
print(models)

info = ollama.show('llama3.2')
print(info)

Menarik dan menghapus model secara terprogram

Model dapat diunduh atau dihapus langsung dari Python, sehingga memudahkan pengelolaan dependensi secara dinamis.

ollama.pull('llama3.2')
ollama.delete('llama3.2')

Menghasilkan dan Menggunakan Embedding dengan Perpustakaan Python Ollama

Embedding merepresentasikan teks sebagai vektor numerik yang menangkap makna semantik. Ini memungkinkan Anda membandingkan teks berdasarkan kesamaan alih-alih kata yang persis sama.

Membuat embedding teks

Contoh berikut mengonversi teks menjadi representasi vektor yang dapat digunakan untuk pencarian atau pengelompokan.

response = ollama.embed(
    model='nomic-embed-text',
    input='Ollama is a local LLM runtime'
)

embedding = response['embeddings'][0]

Membangun pencarian kemiripan dasar

Setelah embedding dibuat, kemiripan dapat diukur menggunakan cosine similarity, yang membandingkan sudut antarputar.

Berikut contoh sederhana fungsi pencarian:

import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

Pemanggilan Tool dan Keluaran Terstruktur di Perpustakaan Python Ollama

Untuk membangun aplikasi yang lebih maju, model sering perlu berinteraksi dengan fungsi eksternal atau mengembalikan data terstruktur.

Menerapkan pemanggilan tool dengan fungsi Python

Pemanggilan tool memungkinkan model memanggil fungsi Python yang sudah ditentukan berdasarkan maksud pengguna.

Mari buat fungsi yang menggunakan tool semacam itu:

def get_weather(city: str) -> str:
    """Get current weather for a city"""
    return f"Weather in {city} is sunny"
response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
    tools=[get_weather]
)

Mendapatkan respons JSON terstruktur

Keluaran terstruktur memastikan bahwa respons dikembalikan dalam format yang konsisten dan dapat dibaca mesin seperti JSON.

response = ollama.chat(
    model='llama3.2',
    messages=[{'role': 'user', 'content': 'Review: Great product, 5 stars!'}],
    format='json'
)

Lanjutan: Model Visi dan Ollama Cloud di Python

Ollama mendukung model multimodal dan inferensi berbasis cloud untuk kasus penggunaan yang lebih maju.

Mengirim gambar ke model visi

Model visi dapat memproses teks dan gambar, memungkinkan tugas seperti deskripsi gambar dan analisis visual.

response = ollama.chat(
    model='llama3.2-vision',
    messages=[{
        'role': 'user',
        'content': 'Describe this image',
        'images': ['image.jpg']
    }]
)

Menjalankan model cloud dari Python

Untuk model yang lebih besar yang tidak dapat dijalankan secara lokal, Ollama Cloud menyediakan inferensi ter-host.

ollama signin
ollama.chat(model='deepseek-v3.1:671b-cloud', messages=[...])
from ollama import Client

client = Client(
    host='https://ollama.com',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

Penanganan Error untuk Jebakan Umum Python Ollama

Saat membangun aplikasi nyata, menangani error secara eksplisit membantu mencegah kegagalan diam-diam dan meningkatkan keandalan.

Menangani pengecualian ResponseError

SDK Ollama menimbulkan pengecualian terstruktur untuk error sisi server, memungkinkan Anda memeriksa apa yang salah.

import ollama

try:
    ollama.generate(model='unknown', prompt='test')
except ollama.ResponseError as e:
    print(e.status_code, e.error)

Mendebug masalah koneksi dan model

Masalah umum termasuk server tidak berjalan, model tidak ada, memori tidak cukup, atau batas konteks terlampaui.

• Server tidak berjalan: Mulai dengan ollama serve

• Model tidak ditemukan: Jalankan ollama pull

• Kehabisan memori: Gunakan model yang lebih kecil atau kuantisasi

• Masalah konteks: Sesuaikan num_ctx

num_ctx mengontrol jumlah maksimum token yang dapat “dilihat” model sekaligus, termasuk:

• prompt Anda
• instruksi sistem
• riwayat percakapan
• dokumen yang diambil (RAG)
• dan token yang dihasilkan model sendiri 

Mengelola parameter ini akan membantu mencegah LLM memangkas konten sebelumnya (biasanya dari awal) atau diam-diam kehilangan instruksi atau data penting.

Penutup

Perpustakaan Python Ollama menyediakan antarmuka lengkap untuk bekerja dengan LLM lokal dan cloud, dari pembuatan teks sederhana hingga kapabilitas lanjutan seperti embedding, pemanggilan tool, dan input multimodal. LLM menjadi layanan lokal yang dapat Anda skrip, uji, dan skala seperti komponen lain dalam tumpukan Anda.

Berdasarkan pengalaman saya menggunakan Ollama, saya merasa bahwa ini adalah opsi yang baik tanpa harus menggunakan LLM cloud. Misalnya, saya bisa menggunakan model open source dengan lebih leluasa. Jika Anda juga mencari lebih banyak opsi untuk berganti-ganti model, Ollama adalah gerbang yang baik untuk mengakses semua itu.

Jika Anda ingin memperdalam keterampilan, saya merekomendasikan mengikuti kursus Developing LLM Applications with LangChain kami atau mengejar sertifikasi Associate AI Engineer for Developers.