API Ollama di Python, Lalu Endpoint yang Di-host

Siapkan Klien Python

Instal Ollama terlebih dahulu, mulai, dan pull model dari terminal: ollama pull llama3. Server mendengarkan di http://localhost:11434. Lalu instal paket Python di lingkungan virtual:

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

Paket ollama berkomunikasi dengan rute asli Ollama di bawah /api. Paket openai digunakan untuk bagian kedua tutorial ini, di mana tujuannya adalah endpoint yang di-host. Jika Anda lebih suka alat visual sebelum melakukan pengkodean, lihat catatan tentang menggunakan Ollama dengan GUI.

Periksa instalasi dengan menjalankan ollama list di terminal. Jika model Anda muncul di sana, Python akan menemukannya. Jika Anda mendapatkan error koneksi nanti, server mungkin tidak berjalan.

Panggilan chat pertama Anda

Ini adalah dasar-dasar API Ollama Python dalam satu cuplikan: pesan sistem, pesan pengguna, dan dua opsi.

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

Balasan adalah objek mirip kamus; teks ada di message.content. Di options Anda dapat mengatur parameter generasi. temperature mengontrol keacakan dan num_ctx mengatur panjang konteks untuk panggilan itu. Ollama secara default menggunakan konteks yang cukup kecil kecuali Anda meningkatkannya, yang mengejutkan orang yang menempel dokumen panjang dan mendapatkan jawaban yang mengabaikan awal.

Untuk chat multi-gilir, simpan daftar pesan dan tambangkan setiap balasan sendiri. Ollama, seperti sebagian besar API chat, bersifat stateless antar panggilan.

Respons streaming

Tanpa streaming Anda menunggu jawaban lengkap. Dengan stream=True fungsi mengembalikan generator dan Anda mencetak bagian saat tiba:

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

Setiap bagian membawa message.content kecil. Bagian terakhir memiliki done diatur ke true dan menyertakan waktu dan hitungan token. Untuk aplikasi web, teruskan bagian-bagian ini ke browser melalui server-sent events atau websocket.

Kesalahan yang benar-benar akan Anda lihat

Dua kegagalan mencakup sebagian besar masalah pemula.

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

404 dari ResponseError berarti nama model tidak cocok dengan sesuatu yang telah Anda ambil. Nama termasuk tag, jadi llama3 dan llama3:70b adalah model yang berbeda. Kesalahan koneksi berarti server tidak aktif, atau Anda berada di dalam kontainer di mana localhost menunjuk ke kontainer, bukan host. Dalam kasus itu, teruskan klien dengan host yang benar: ollama.Client(host="http://host.docker.internal:11434").

Lebih banyak pola kesalahan dikumpulkan di kesalahan umum API Ollama.

Program yang sama, endpoint yang di-host

Model lokal dibatasi oleh memori dan kecepatan Anda. Ketika skrip harus berjalan di server, menangani banyak pekerjaan paralel, atau menggunakan jendela yang lebih besar, endpoint yang di-host lebih mudah. Triknya adalah menulis program melawan SDK OpenAI dan memperlakukan URL dasar, kunci, dan model sebagai konfigurasi:

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

Untuk Ollama lokal, atur LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (string yang tidak kosong apa pun diterima di sana) dan LLM_MODEL=llama3. Untuk API yang di-host, gunakan pengaturan bawaan di atas, kunci asli Anda, dan model uncensored. Tidak ada perubahan lain pada kode.

Dapatkan kunci di halaman kunci API. Akun baru dapat mengklaim uji coba $0,50 dalam satu klik, tanpa pembayaran, berlaku selama 7 hari. Model adalah satu model bobot terbuka dari penyedia independen, disesuaikan untuk menjawab tanpa penolakan konten untuk penggunaan dewasa yang sah. Ini hanya teks dan bukan API resmi dari lab besar mana pun.

Menjalankan banyak prompt secara paralel

Model lokal di satu mesin biasanya menangani satu permintaan pada satu waktu, jadi loop bersifat sekuensial. Endpoint yang di-host memungkinkan konkurensi, yang membuat pekerjaan batch jauh lebih cepat. Pertahankan jumlah pekerja di bawah batas kunci Anda: 8 permintaan konkuren untuk kunci penuh, 2 untuk kunci uji coba.

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

Enam pekerja memberikan ruang aman di bawah batas 8. Jika seorang pekerja menerima 429, SDK OpenAI akan mencoba lagi beberapa kali secara default, tetapi tambahkan penundaan Anda sendiri untuk menjalankan jangka panjang. Juga ingat bahwa setiap permintaan streaming memegang slotnya hingga stream berakhir, jadi jangan campur obrolan streaming panjang dan batch besar pada kunci uji coba yang sama.

Perbedaan yang perlu direncanakan

• Tidak ada opsi hanya lokal. num_ctx dan keep_alive tidak memiliki arti di sisi hosting. Jendela konteksnya adalah 100.000 token, untuk prompt dan penyelesaian bersama-sama.
• Batas laju. Kunci penuh memungkinkan 8 permintaan konkuren dan 300 permintaan per menit; kunci uji coba memungkinkan 2 dan 60. Lewat itu Anda mendapatkan 429 dengan rate_limited atau concurrency. Coba lagi setelah jeda; saat kelebihan beban sementara, respons membawa Retry-After: 5.
• Biaya. Input adalah $0,15 per 1M token dan output adalah $0,50 per 1M. Skrip yang mengirim 2.000 prompt dengan 600 input dan 400 token output menghabiskan 2.000 x (600 x $0,15 + 400 x $0,50) / 1M = 2.000 x $0,00029 = $0,58.
• Penagihan. Saldo kredit prabayar, dari $20 hingga $500, dibayar dengan kripto (USDT di TRC20 atau USDC di Base). Permintaan yang gagal atau ditolak tidak dikenakan biaya.

Untuk tampilan berdampingan endpoint, baca catatan harga API kami atau dokumentasi.

Panduan lainnya

• API Ollama vs API OpenAI: Endpoint dan Kode
• Cara Menggunakan Ollama dengan GUI (dan Cadangan Ter-host)