TeknoTUT

Cara Menggunakan Ollama dengan Python: Membuat Chatbot AI Lokal

Panduan memakai Ollama dengan Python: install library resmi, streaming jawaban, membuat chatbot dengan memori, hingga output JSON terstruktur.

Ditulis oleh 13 menit bacaEnglish
Ilustrasi jendela kode Python yang terhubung ke chip AI dan gelembung percakapan
Daftar Isi

Jika anda sudah pernah menjalankan model AI di komputer sendiri dengan Ollama, tentu anda sudah merasakan serunya mengobrol dengan AI langsung dari terminal. Namun, mengobrol saja rasanya belum cukup, kan? Sebagai developer, biasanya kita ingin melangkah lebih jauh: memanggil model itu dari kode program kita sendiri.

Bayangkan anda bisa membuat chatbot pribadi, alat perangkum dokumen, atau script yang otomatis mengelompokkan ulasan pelanggan, semuanya berjalan di mesin anda sendiri. Tidak ada biaya API per token, dan tidak ada data yang dikirim ke server pihak lain.

Kabar baiknya, Ollama menyediakan library Python resmi yang membuat semua itu bisa dilakukan hanya dengan beberapa baris kode. Anda tidak perlu menyusun request HTTP secara manual.

Dalam artikel kali ini, kita akan membahas tuntas cara menggunakan Ollama dengan Python, mulai dari memasang library-nya, mengirim pesan pertama, menampilkan jawaban secara streaming, membuat chatbot yang mengingat percakapan, hingga meminta jawaban dalam format JSON yang terstruktur. Mari kita mulai!

Apa itu Library Ollama untuk Python?

Ollama adalah aplikasi untuk menjalankan Large Language Model (LLM) secara lokal. Saat berjalan, Ollama membuka REST API di http://localhost:11434 yang bisa dipanggil oleh aplikasi apa pun.

Library ollama untuk Python adalah pustaka resmi dari tim Ollama yang membungkus REST API tersebut menjadi fungsi-fungsi Python yang rapi. Jadi, alih-alih menulis request HTTP dan mengurai JSON sendiri, anda cukup memanggil fungsi seperti chat() dan langsung mendapatkan objek jawaban.

Analoginya seperti ini: REST API itu ibarat dapur restoran, sedangkan library ini adalah pelayannya. Anda cukup menyebutkan pesanan, dan pelayan yang mengurus komunikasi dengan dapur.

Catatan: library ini hanyalah penghubung. Model AI tetap dijalankan oleh aplikasi Ollama, sehingga Ollama harus sudah terpasang dan berjalan di komputer anda (atau di server yang bisa dijangkau).

Mengapa Memakai Library Resmi Ollama?

Sebenarnya ada beberapa cara memanggil Ollama dari Python, misalnya lewat library requests atau library OpenAI yang diarahkan ke endpoint /v1. Lalu, kenapa memilih library resmi?

  • Kode lebih ringkas: satu pemanggilan fungsi chat() sudah cukup untuk mengirim pesan dan menerima jawaban.
  • Mendukung semua fitur Ollama: streaming, structured outputs, tool calling, embedding, hingga pengelolaan model (pull, list, delete) tersedia langsung.
  • Jawaban berupa objek bertipe: anda bisa menulis response.message.content, dan editor seperti VS Code bisa memberi autocomplete.
  • Tersedia versi sinkron dan asinkron: ada Client untuk script biasa dan AsyncClient untuk aplikasi berbasis asyncio seperti FastAPI.

Kekurangan yang Perlu Diketahui

Agar berimbang, ada beberapa hal yang perlu anda pertimbangkan:

  • Terikat pada Ollama: jika suatu saat anda ingin berpindah ke penyedia AI lain, kodenya perlu disesuaikan. Bila portabilitas penting bagi anda, endpoint kompatibel OpenAI bisa menjadi pilihan yang lebih fleksibel.
  • Kecepatan bergantung pada hardware: library ini tidak membuat model lebih cepat. Tanpa GPU, jawaban dari model berukuran besar tetap akan terasa lambat.

Persiapan

Sebelum memulai, pastikan anda sudah memiliki:

  • Ollama yang sudah terpasang dan berjalan. Jika belum, silakan ikuti panduan cara install Ollama di Ubuntu terlebih dahulu.
  • Minimal satu model yang sudah diunduh. Contoh di artikel ini memakai llama3.2 yang ringan (unduhan sekitar 2 GB). Anda bebas menggantinya dengan model lain.
  • Python 3.8 atau lebih baru. Ubuntu 24.04 LTS dan 26.04 LTS sudah menyertakan Python 3 versi yang jauh lebih baru dari itu.
  • Editor kode, misalnya VS Code atau cukup nano.

Perintah di artikel ini ditujukan untuk Ubuntu 24.04 LTS dan 26.04 LTS. Di macOS dan Windows, kode Python-nya sama persis, hanya cara membuat virtual environment yang sedikit berbeda.

Jika model belum ada di komputer anda, unduh dulu dengan perintah berikut:

ollama pull llama3.2

Lalu pastikan server Ollama merespons:

curl http://localhost:11434

Jika outputnya adalah teks Ollama is running, berarti anda siap melanjutkan.

Cara Menggunakan Ollama dengan Python

Langkah #1: Buat Folder Proyek dan Virtual Environment

Pada Ubuntu versi baru, menjalankan pip install langsung di sistem akan ditolak dengan pesan error: externally-managed-environment. Ini bukan bug, melainkan perlindungan agar paket Python milik sistem tidak rusak. Solusinya adalah memakai virtual environment (venv), yaitu lingkungan Python terpisah khusus untuk proyek anda.

Pertama, pasang paket pendukung venv dengan perintah berikut:

sudo apt update
sudo apt install -y python3-venv python3-pip

Selanjutnya, buat folder proyek dan masuk ke dalamnya:

mkdir ~/chatbot-ollama
cd ~/chatbot-ollama

Buat virtual environment di folder .venv, lalu aktifkan:

python3 -m venv .venv
source .venv/bin/activate

Jika berhasil, di awal baris terminal anda akan muncul tulisan (.venv). Artinya, semua paket yang anda pasang setelah ini hanya berlaku di proyek ini saja.

Setiap kali membuka terminal baru, aktifkan kembali venv dengan source .venv/bin/activate dari dalam folder proyek. Untuk keluar dari venv, ketik deactivate.

Langkah #2: Install Library Ollama

Dengan venv yang sudah aktif, pasang library ollama dengan perintah berikut:

pip install ollama

Perintah ini juga otomatis memasang dua dependensinya, yaitu httpx (untuk koneksi HTTP) dan pydantic (untuk validasi data). Nanti pydantic akan kita pakai di bagian JSON terstruktur.

Untuk memastikan library sudah terpasang, cek dengan perintah berikut:

pip show ollama

Jika outputnya menampilkan nama, versi, dan lokasi paket, berarti instalasi sudah berhasil.

Langkah #3: Kirim Pesan Pertama ke Model

Sekarang bagian yang ditunggu-tunggu. Buat file baru bernama halo.py:

nano halo.py

Isikan kode berikut:

from ollama import chat
 
response = chat(
    model="llama3.2",
    messages=[
        {"role": "user", "content": "Jelaskan apa itu Python dalam dua kalimat."},
    ],
)
 
print(response.message.content)

Simpan file dengan menekan Ctrl+X, lalu Y, dan Enter. Jalankan dengan perintah berikut:

python halo.py

Setelah menunggu beberapa detik, jawaban model akan tampil di terminal. Selesai! Anda baru saja memanggil model AI lokal dari Python.

Mari kita bedah kodenya:

  • model: nama model yang dipakai, harus sama dengan nama di output ollama list.
  • messages: daftar pesan dalam percakapan. Setiap pesan memiliki role (peran) dan content (isi).
  • response.message.content: teks jawaban dari model. Anda juga bisa menulisnya dengan gaya dictionary: response["message"]["content"].

Ada empat nilai role yang dikenali Ollama:

Role Fungsi
system Instruksi dasar yang mengatur perilaku model
user Pesan dari pengguna
assistant Jawaban dari model
tool Hasil pemanggilan tool (dipakai pada tool calling)

Pemanggilan pertama biasanya lebih lambat karena Ollama perlu memuat model ke memori terlebih dahulu. Pemanggilan berikutnya akan lebih cepat selama model masih dimuat (secara default 5 menit sejak terakhir dipakai).

Langkah #4: Tampilkan Jawaban Secara Streaming

Pada contoh sebelumnya, kita harus menunggu sampai seluruh jawaban selesai dibuat, baru teksnya muncul. Untuk jawaban yang panjang, ini terasa lama. Solusinya adalah streaming: jawaban ditampilkan kata demi kata saat model menulisnya, seperti di ChatGPT.

Perlu diketahui, pada REST API Ollama streaming aktif secara default, tetapi pada library Python justru nonaktif secara default. Jadi kita perlu menambahkan stream=True.

Buat file streaming.py dengan isi berikut:

from ollama import chat
 
stream = chat(
    model="llama3.2",
    messages=[
        {"role": "user", "content": "Tuliskan tiga tips belajar pemrograman untuk pemula."},
    ],
    stream=True,
)
 
for chunk in stream:
    print(chunk.message.content or "", end="", flush=True)
 
print()

Jalankan dengan python streaming.py, dan anda akan melihat jawaban mengalir sedikit demi sedikit.

Dengan stream=True, fungsi chat() tidak lagi mengembalikan satu jawaban utuh, melainkan rangkaian potongan (chunk). Opsi end="" mencegah print membuat baris baru di setiap potongan, dan flush=True memastikan teks langsung tampil di layar tanpa ditahan di buffer.

Langkah #5: Buat Chatbot yang Mengingat Percakapan

Ada satu hal penting yang sering mengejutkan pemula: model tidak mengingat apa pun di antara dua pemanggilan. Setiap pemanggilan chat() berdiri sendiri. Jika anda bertanya "Siapa nama saya?" pada pemanggilan kedua, model tidak tahu bahwa anda sudah memperkenalkan diri pada pemanggilan pertama.

Lalu bagaimana chatbot bisa "mengingat"? Caranya sederhana: kita simpan seluruh riwayat percakapan di sebuah list, lalu mengirimkan semuanya setiap kali memanggil model.

Buat file chatbot.py dengan isi berikut:

from ollama import chat
 
MODEL = "llama3.2"
 
messages = [
    {
        "role": "system",
        "content": "Kamu adalah asisten yang ramah. Jawab dengan singkat dan jelas dalam Bahasa Indonesia.",
    },
]
 
print("Chatbot siap. Ketik 'keluar' untuk berhenti.\n")
 
while True:
    try:
        user_input = input("Anda: ").strip()
    except (EOFError, KeyboardInterrupt):
        print()
        break
 
    if not user_input:
        continue
    if user_input.lower() in ("keluar", "exit", "quit"):
        break
 
    messages.append({"role": "user", "content": user_input})
 
    print("AI: ", end="", flush=True)
    reply = ""
    stream = chat(model=MODEL, messages=messages, stream=True)
    for chunk in stream:
        text = chunk.message.content or ""
        print(text, end="", flush=True)
        reply += text
    print("\n")
 
    messages.append({"role": "assistant", "content": reply})

Jalankan dengan perintah berikut:

python chatbot.py

Coba perkenalkan diri anda, lalu tanyakan kembali nama anda di pesan berikutnya. Percakapannya kira-kira seperti ini (jawaban model tentu bisa berbeda):

Chatbot siap. Ketik 'keluar' untuk berhenti.
 
Anda: Halo, nama saya Budi dan saya sedang belajar Python.
AI: Halo Budi! Senang berkenalan. Ada yang bisa saya bantu soal Python?
 
Anda: Siapa nama saya?
AI: Nama anda Budi.

Menarik bukan? Berikut cara kerja script tersebut:

  1. List messages diawali dengan pesan system yang mengatur kepribadian dan bahasa chatbot. Silakan ubah isinya sesuka anda.
  2. Setiap input pengguna ditambahkan ke messages dengan role user.
  3. Seluruh messages dikirim ke model, lalu jawabannya ditampilkan secara streaming sambil dikumpulkan di variabel reply.
  4. Jawaban lengkap ditambahkan kembali ke messages dengan role assistant, sehingga ikut terkirim pada giliran berikutnya.

Perhatikan panjang riwayat. Setiap model memiliki batas context window, yaitu jumlah maksimal token yang bisa dibacanya sekaligus. Karena seluruh riwayat dikirim ulang setiap giliran, percakapan yang sangat panjang lama-lama akan melewati batas itu, dan pesan paling awal mulai "terlupakan". Cara paling mudah mengatasinya adalah membatasi riwayat, misalnya dengan menambahkan baris messages = messages[:1] + messages[-20:] sebelum memanggil chat(). Baris itu mempertahankan pesan system dan 20 pesan terakhir saja.

Langkah #6: Atur Perilaku Model dengan Options

Fungsi chat() menerima parameter options untuk mengatur cara model menghasilkan jawaban. Berikut contoh pemakaiannya:

from ollama import chat
 
response = chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Buatkan satu slogan untuk warung kopi."}],
    options={
        "temperature": 0.8,
        "num_ctx": 8192,
        "num_predict": 200,
    },
    keep_alive="10m",
)
 
print(response.message.content)

Penjelasan opsi yang paling sering dipakai:

Opsi Fungsi
temperature Tingkat "kreativitas". Nilai rendah (mis. 0) membuat jawaban konsisten, nilai tinggi membuat jawaban lebih bervariasi
num_ctx Ukuran context window dalam token. Semakin besar, semakin banyak riwayat yang muat, tetapi pemakaian memori ikut naik
num_predict Jumlah maksimal token yang dihasilkan dalam satu jawaban
seed Angka acuan agar hasil bisa diulang dengan input yang sama
stop Daftar teks yang membuat model berhenti menulis

Parameter keep_alive (di luar options) mengatur berapa lama model tetap dimuat di memori setelah dipakai. Nilai "10m" berarti 10 menit, sedangkan 0 membuat model langsung dilepas setelah menjawab.

Langkah #7: Minta Jawaban dalam Format JSON Terstruktur

Jawaban berupa teks bebas memang enak dibaca manusia, tetapi sulit diolah oleh program. Misalnya anda ingin mengelompokkan ulasan pelanggan menjadi positif atau negatif, tentu anda butuh jawaban dengan format yang pasti, bukan paragraf panjang.

Di sinilah fitur structured outputs berperan. Kita mendefinisikan bentuk data yang diinginkan dengan pydantic, lalu mengirimkan skemanya lewat parameter format. Ollama akan memaksa model menjawab sesuai skema tersebut.

Buat file analisis_ulasan.py dengan isi berikut:

from typing import Literal
 
from ollama import chat
from pydantic import BaseModel
 
 
class Ulasan(BaseModel):
    produk: str
    sentimen: Literal["positif", "negatif", "netral"]
    skor: int
    ringkasan: str
 
 
teks = (
    "Saya membeli keyboard mekanik ini minggu lalu. Suara tombolnya enak "
    "dan pengirimannya cepat, tetapi lampu RGB-nya mati setelah tiga hari."
)
 
response = chat(
    model="llama3.2",
    messages=[
        {
            "role": "user",
            "content": f"Analisis ulasan berikut. Beri skor 1 sampai 5.\n\n{teks}",
        },
    ],
    format=Ulasan.model_json_schema(),
    options={"temperature": 0},
)
 
ulasan = Ulasan.model_validate_json(response.message.content)
 
print("Produk   :", ulasan.produk)
print("Sentimen :", ulasan.sentimen)
print("Skor     :", ulasan.skor)
print("Ringkasan:", ulasan.ringkasan)

Jalankan dengan python analisis_ulasan.py. Outputnya kira-kira seperti ini:

Produk   : keyboard mekanik
Sentimen : netral
Skor     : 3
Ringkasan: Suara tombol enak dan pengiriman cepat, tetapi lampu RGB mati setelah tiga hari.

Beberapa hal yang perlu diperhatikan dari kode di atas:

  • Ulasan.model_json_schema() mengubah kelas pydantic menjadi JSON Schema yang dipahami Ollama.
  • Literal[...] membatasi nilai sentimen hanya pada tiga pilihan tersebut.
  • Ulasan.model_validate_json(...) mengubah teks JSON dari model menjadi objek Python, sekaligus memvalidasi tipenya. Hasilnya bisa langsung dipakai, misalnya disimpan ke database.
  • temperature: 0 adalah saran dari dokumentasi Ollama agar hasil lebih konsisten.

Skema menjamin bentuk, bukan kebenaran isi. Model tetap bisa salah menilai sentimen atau memberi skor di luar rentang 1–5, terutama model kecil. Untuk tugas yang penting, periksa kembali hasilnya atau gunakan model yang lebih besar.

Langkah #8: Tangani Error dengan Baik

Script yang baik tidak langsung berhenti dengan pesan error yang panjang saat ada masalah. Ada dua jenis error yang paling sering muncul:

  • ConnectionError: library tidak bisa terhubung ke server Ollama, biasanya karena Ollama belum berjalan.
  • ollama.ResponseError: server Ollama membalas dengan error, misalnya karena model belum diunduh (status 404).

Berikut contoh penanganannya, dalam file aman.py:

import ollama
 
MODEL = "llama3.2"
 
try:
    response = ollama.chat(
        model=MODEL,
        messages=[{"role": "user", "content": "Halo!"}],
    )
    print(response.message.content)
except ollama.ResponseError as e:
    print("Error dari Ollama:", e.error)
    if e.status_code == 404:
        print(f"Model belum ada. Unduh dengan: ollama pull {MODEL}")
except ConnectionError:
    print("Tidak bisa terhubung ke Ollama. Cek dengan: systemctl status ollama")

Dengan pola ini, pengguna script anda mendapat petunjuk yang jelas tentang apa yang harus dilakukan.

Tips Agar Hasil Lebih Maksimal

Tip #1: Ukur Kecepatan Model dari Python

Setiap jawaban (tanpa streaming) menyertakan statistik pemrosesan. Anda bisa menghitung kecepatan model dalam token per detik dengan menambahkan kode berikut setelah pemanggilan chat():

tokens = response.eval_count
seconds = response.eval_duration / 1_000_000_000
print(f"{tokens} token dalam {seconds:.1f} detik ({tokens / seconds:.1f} token/detik)")

Nilai eval_duration memakai satuan nanodetik, sehingga perlu dibagi satu miliar. Angka ini berguna untuk membandingkan beberapa model di mesin anda.

Tip #2: Hubungkan ke Ollama di Komputer Lain

Secara default, library terhubung ke http://localhost:11434. Jika Ollama berjalan di mesin lain, misalnya PC ber-GPU di jaringan rumah, buat objek Client dengan alamat server tersebut:

from ollama import Client
 
client = Client(host="http://192.168.1.50:11434")
 
response = client.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Halo dari komputer lain!"}],
)
print(response.message.content)

Alternatifnya, atur variabel lingkungan OLLAMA_HOST sebelum menjalankan script, dan library akan otomatis memakainya.

Peringatan: API Ollama tidak memiliki autentikasi. Agar bisa diakses dari mesin lain, server Ollama harus diatur mendengarkan di 0.0.0.0, dan itu hanya aman dilakukan di jaringan lokal yang terpercaya. Jangan membuka port 11434 ke internet. Untuk server di VPS, gunakan SSH tunnel dan pastikan anda sudah mengikuti panduan cara mengamankan VPS Linux.

Tip #3: Pakai AsyncClient untuk Aplikasi Web

Jika anda membangun aplikasi web atau bot yang melayani banyak pengguna sekaligus, gunakan AsyncClient agar aplikasi tidak "macet" saat menunggu jawaban model:

import asyncio
 
from ollama import AsyncClient
 
 
async def main():
    response = await AsyncClient().chat(
        model="llama3.2",
        messages=[{"role": "user", "content": "Apa itu asyncio?"}],
    )
    print(response.message.content)
 
 
asyncio.run(main())

Cara pakainya sama dengan versi sinkron, hanya ditambah await.

Troubleshooting Masalah Umum

Masalah Penyebab Solusi
error: externally-managed-environment pip install dijalankan di luar venv Aktifkan venv dengan source .venv/bin/activate
ModuleNotFoundError: No module named 'ollama' Script dijalankan di luar venv, atau library belum dipasang Aktifkan venv, lalu jalankan pip install ollama
ConnectionError: Failed to connect to Ollama Server Ollama tidak berjalan Jalankan sudo systemctl start ollama
ResponseError dengan status 404 Model belum diunduh atau namanya salah ketik Cek ollama list, lalu ollama pull <model>
Jawaban pertama sangat lambat Model sedang dimuat ke memori Tunggu, atau perpanjang keep_alive
Chatbot lupa awal percakapan Riwayat melebihi context window Batasi riwayat atau perbesar num_ctx
File bernama ollama.py menyebabkan error import Nama file bentrok dengan nama library Ganti nama file anda, jangan pakai ollama.py

Kesimpulan

Dari artikel ini, kita dapat menyimpulkan bahwa menggunakan Ollama dengan Python ternyata sangat mudah. Dengan library resmi ollama, cukup beberapa baris kode untuk mengirim pesan ke model, menampilkan jawaban secara streaming, membuat chatbot yang mengingat percakapan, hingga mendapatkan jawaban berformat JSON terstruktur yang siap diolah program.

Yang Perlu Diingat

  • Model tidak punya memori. Riwayat percakapan harus anda simpan dan kirim ulang di setiap pemanggilan.
  • Streaming pada library Python nonaktif secara default, jadi tambahkan stream=True.
  • Structured outputs menjamin bentuk data, bukan kebenaran isinya.
  • Selalu bekerja di dalam virtual environment agar Python sistem tetap bersih.

Langkah Selanjutnya

Setelah menguasai dasar-dasarnya, anda bisa mengembangkan chatbot ini lebih jauh. Misalnya mempelajari tool calling agar model bisa memanggil fungsi Python anda, atau embedding untuk membuat pencarian dokumen. Jika script anda ingin dijalankan terus-menerus di server, misalnya sebagai bot, silakan simak panduan cara membuat service systemd di Linux.


Selamat mencoba, dan jangan ragu bereksperimen dengan model serta system prompt yang berbeda. Tetap pantau terus web Teknotut!

Semoga artikel ini membantu.

Bacaan Selanjutnya

Artikel lain yang mungkin menarik buatmu.