API Ollama di Python, dan Alternatif yang Dihosting

Versi singkat

Jika Anda mencari ollama api python, Anda biasanya menginginkan salah satu dari tiga hal: memanggil model yang berjalan di mesin Anda sendiri, melakukan streaming token darinya, atau membuat skrip yang sama berfungsi di tempat lain. Ollama memberikan ketiganya. Ini menjalankan server lokal, secara default di http://localhost:11434, dan Anda berbicara dengannya dengan paket Python ollama, dengan HTTP biasa, atau dengan klien OpenAI apa pun yang ditunjuk ke jalur /v1.

Tangkapannya adalah model harus berjalan di perangkat keras Anda. Laptop tanpa GPU yang layak akan lambat dengan model yang lebih besar, dan server tanpa itu adalah pilihan yang buruk. Untuk kasus itu, API yang kompatibel dengan OpenAI yang dihosting adalah rute yang lebih mudah, dan karena format permintaan sama, beralih hanya membutuhkan tiga baris konfigurasi. Kedua jalur dicakup di bawah ini, dengan kode yang dapat Anda tempel.

Memanggil model lokal dengan paket ollama

Instal Ollama, tarik model, dan pastikan server berjalan. Kemudian instal klien Python:

Copypip install ollama
ollama pull llama3.2

Panggilan chat dasar terlihat seperti ini. Nama model adalah apa pun yang Anda tarik; llama3.2 hanyalah contoh.

Copyimport ollama

response = ollama.chat(
    model="llama3.2",
    messages=[{"role": "user", "content": "Explain DNS in two sentences."}],
)
print(response["message"]["content"])

Streaming

Lewatkan stream=True dan Anda mendapatkan iterator potongan alih-alih satu balasan. Setiap potongan membawa bagian dari jawaban di message.content.

Copyimport ollama

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

Mengarahkan klien ke mesin lain

Jika Ollama berjalan di host yang berbeda, buat klien dengan alamat eksplisit, misalnya ollama.Client(host="http://192.168.1.20:11434"). Secara default server hanya mendengarkan di mesin lokal, sehingga akses jarak jauh memerlukan pengaturan yang disengaja di sisi server. Jangan mengeksposnya ke internet publik tanpa proxy dan autentikasi di depan, karena API asli tidak memiliki pemeriksaan kunci sendiri.

HTTP biasa dengan requests

Anda sama sekali tidak memerlukan paket tersebut. Endpoint chat asli adalah POST /api/chat. Streaming adalah default di sana, dan stream adalah JSON yang dipisahkan baris, bukan SSE. Tetapkan "stream": false jika Anda menginginkan objek tunggal kembali.

Copyimport requests

r = requests.post(
    "http://localhost:11434/api/chat",
    json={
        "model": "llama3.2",
        "messages": [{"role": "user", "content": "Name three HTTP status codes."}],
        "stream": False,
    },
    timeout=120,
)
r.raise_for_status()
print(r.json()["message"]["content"])

Atur batas waktu yang murah hati. Permintaan pertama setelah penarikan harus memuat model ke dalam memori, dan itu bisa memakan waktu jauh lebih lama daripada permintaan selanjutnya.

Membaca stream secara manual hanya membutuhkan beberapa baris lagi. Panggil requests.post(..., stream=True), iterasi r.iter_lines(), lewati baris kosong, dan jalankan json.loads pada setiap baris. Setiap objek memegang potongan kecil dari balasan, dan yang terakhir memiliki "done": true. Ini berguna dalam kontainer minimal di mana Anda lebih memilih untuk tidak menginstal paket lain, dan itu membuat jelas apa yang dilakukan perpustakaan untuk Anda. API yang dihosting melakukan streaming secara berbeda, sebagai baris SSE yang dimulai dengan data:, yang merupakan satu alasan lagi untuk membiarkan SDK OpenAI mengurai stream untuk Anda dalam kode portabel.

Menggunakan SDK OpenAI dengan Ollama

Ollama juga mengekspos endpoint gaya OpenAI di bawah /v1. Itu berarti paket resmi openai berfungsi, dan begitu juga sebagian besar perangkat lunak yang memungkinkan Anda menetapkan URL dasar kustom. Kunci diperlukan oleh SDK tetapi diabaikan oleh Ollama lokal, jadi string apa pun bisa dilakukan.

Copyfrom openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Give me a one-line summary of TCP."}],
)
print(resp.choices[0].message.content)

Ini adalah bentuk yang paling berguna, karena memisahkan kode Anda dari server. Fungsi yang sama dapat berbicara dengan model lokal hari ini dan dengan sesuatu yang lain besok, yang merupakan bagian berikutnya.

Kode yang sama terhadap API yang dihosting

Pilihan yang dihosting di sini adalah API yang kompatibel dengan OpenAI dengan satu model, uncensored, dijalankan oleh penyedia independen dan disesuaikan untuk menjawab tanpa penolakan konten untuk penggunaan dewasa yang sah. Ini hanya teks. URL dasarnya adalah https://api.ollamaapi.cc/v1, dan Anda mengautentikasi dengan kunci Bearer dari halaman kunci API.

Berikut adalah versi yang membaca targetnya dari variabel lingkungan, dengan nilai yang dihosting sebagai default. Untuk kembali ke server lokal Anda, ekspor dua variabel dan jangan ubah yang lain.

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("LLM_BASE_URL", "https://api.ollamaapi.cc/v1"),
    api_key=os.getenv("LLM_API_KEY", "YOUR_API_KEY"),
)
MODEL = os.getenv("LLM_MODEL", "uncensored")

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "List four uses of a message queue."},
    ],
    temperature=0.7,
)
print(resp.choices[0].message.content)

Untuk menjalankan lokal, atur LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama dan LLM_MODEL=llama3.2. panduan awal memiliki pengaturan yang sama di curl dan Node.

Streaming, mode JSON, dan alat di sisi hosting

Endpoint yang dihosting mendukung streaming melalui SSE, mode JSON, pemanggilan alat, dan parameter sampling biasa (temperature, top_p, stop, seed dan penalti). Streaming dengan SDK adalah loop yang sama yang akan Anda tulis untuk server gaya OpenAI apa pun:

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell a two-paragraph story about a lighthouse."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Untuk output terstruktur, atur response_format={"type": "json_object"} dan katakan dalam prompt bahwa Anda menginginkan JSON. Selalu parse di dalam blok try; model masih dapat mengembalikan sesuatu yang tidak Anda harapkan.

Satu perbedaan dari penggunaan lokal yang penting dalam kode: batas. Kunci penuh memungkinkan 8 permintaan bersamaan dan 300 permintaan per menit, dan permintaan yang di-stream mempertahankan slotnya hingga stream berakhir. Jika Anda menjalankan paralel dengan thread, batasi pool di 8 dan coba lagi pada HTTP 429 menggunakan header Retry-After ketika ada.

Melanjutkan percakapan

Baik endpoint chat lokal maupun yang dihosting tidak mengingat apa pun antara panggilan. Server hanya melihat pesan yang Anda kirim, sehingga chatbot adalah daftar yang Anda tambahkan dan kirim ulang. Polanya identik untuk kedua target, yang merupakan alasan lain untuk mempertahankan klien gaya OpenAI sebagai default Anda.

Copyhistory = [{"role": "system", "content": "You are a helpful assistant."}]

def ask(text):
    history.append({"role": "user", "content": text})
    resp = client.chat.completions.create(model=MODEL, messages=history)
    answer = resp.choices[0].message.content
    history.append({"role": "assistant", "content": answer})
    return answer

print(ask("Pick a name for a hiking app."))
print(ask("Give me a tagline for it."))

Dua catatan praktis. Pertama, model lokal memiliki panjang konteks yang Anda atur dan memori harus menahan; jika riwayat tumbuh melampauinya, giliran yang lebih lama dipotong atau panggilan gagal, tergantung pada pengaturan. Model yang dihosting menerima jendela 100.000 token termasuk penyelesaian, yang jauh lebih banyak daripada yang dibutuhkan sebagian besar obrolan, tetapi riwayat panjang masih menelan token input pada setiap giliran. Kedua, sekali riwayat menjadi panjang, ringkas giliran tertua menjadi satu pesan pendek alih-alih mengirimkannya semua. Itu menjaga latensi dan biaya tetap stabil di kedua backend.

Mencoba lagi dengan sopan

Pada API yang dihosting, kelebihan beban sementara mengembalikan HTTP 429 dengan header Retry-After: 5. Pembungkus kecil menanganinya:

Copyimport time
from openai import RateLimitError

def chat_with_retry(messages, tries=4):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model=MODEL, messages=messages)
        except RateLimitError:
            time.sleep(5 * (attempt + 1))
    raise RuntimeError("still rate limited")

Ollama lokal tidak membatasi laju Anda, tetapi mengantri permintaan ketika model sibuk, sehingga pembungkus yang sama tidak membahayakan di sana.

Lokal atau hosting: cara memutuskan

Tidak ada pilihan yang lebih baik secara umum. Gunakan poin di bawah ini sebagai daftar periksa.

• Pilih Ollama lokal jika Anda perlu bekerja secara offline, jika data tidak boleh pernah meninggalkan mesin, jika Anda sudah memiliki GPU yang mampu, atau jika Anda ingin mencoba banyak model terbuka yang berbeda dengan cepat.
• Pilih API yang dihosting jika Anda tidak memiliki GPU, jika Anda menjalankan di VPS kecil atau di CI, jika beberapa orang atau layanan berbagi satu backend, atau jika Anda menginginkan jendela konteks panjang tanpa mengatur memori sendiri. Model yang dihosting menerima hingga 100.000 token prompt plus penyelesaian.
• Kombinasikan keduanya selama pengembangan: iterasi secara lokal, lalu arahkan produksi ke URL yang dihosting melalui variabel lingkungan.

Penggunaan dihosting ditagih per token, sebesar $0.15 per 1M token input dan $0.50 per 1M token output, dari saldo prabayar. Halaman harga mencantumkan jumlah isi saldo, dan akun baru dapat mengklaim kredit uji coba gratis sebesar $0.50 dengan satu klik, tanpa perlu kartu. Prompt tidak digunakan untuk pelatihan.

Kesalahan yang akan Anda temui

Gejala	Penyebab yang mungkin	Perbaikan
Koneksi ditolak pada port 11434	Server Ollama tidak berjalan	Mulai aplikasi atau jalankan ollama serve
Model tidak ditemukan	Model tidak pernah di-pull, atau nama memiliki salah ketik	Jalankan ollama list, lalu ollama pull nama yang Anda gunakan
Permintaan pertama melebihi batas waktu	Model masih memuat	Naikkan batas waktu atau kirim permintaan pemanasan
Kesalahan autentikasi pada API yang di-hosting	Kunci Bearer hilang atau salah	Periksa LLM_API_KEY dan URL dasar
HTTP 429 dengan kode concurrency	Lebih dari 8 permintaan yang sedang berjalan (2 pada kunci uji coba)	Turunkan jumlah pekerja
HTTP 429 dengan kode rate_limited	Melebihi batas permintaan per menit	Tunggu sebentar lalu coba lagi

Permintaan yang gagal atau ditolak di sisi yang di-hosting tidak dikenakan biaya, sehingga logika pengulangan tidak membebani Anda untuk upaya yang gagal.

Panduan lainnya

• Harga API Ollama: Biaya Lokal vs Pembayaran per Token
• API Ollama vs OpenRouter: Mana yang Cocok untuk Anda
• Panduan Kunci API Mistral