API Ollama trong Python, rồi đến Endpoint lưu trữ

Thiết lập client Python

Đầu tiên, hãy cài đặt Ollama, khởi động nó và pull một mô hình từ terminal: ollama pull llama3. Máy chủ lắng nghe trên http://localhost:11434. Sau đó, cài đặt gói Python trong môi trường ảo:

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

Gói ollama giao tiếp với các endpoint gốc của Ollama dưới /api. Gói openai dành cho nửa sau của hướng dẫn này, nơi đích là một endpoint được lưu trữ. Nếu bạn thích một công cụ trực quan trước khi viết mã, hãy xem các ghi chú về sử dụng Ollama với giao diện đồ họa.

Kiểm tra việc cài đặt bằng cách chạy ollama list trong terminal. Nếu mô hình của bạn xuất hiện ở đó, Python sẽ tìm thấy nó. Nếu bạn gặp lỗi kết nối sau này, máy chủ có thể không chạy.

Cuộc gọi trò chuyện đầu tiên của bạn

Đây là kiến thức cơ bản về API Ollama trong Python trong một đoạn mã: một tin nhắn hệ thống, một tin nhắn người dùng và hai tùy chọn.

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"])

Phản hồi là một đối tượng giống như từ điển; văn bản nằm trong message.content. Trong options, bạn có thể đặt các tham số tạo. temperature kiểm soát độ ngẫu nhiên và num_ctx đặt độ dài ngữ cảnh cho cuộc gọi đó. Ollama mặc định là một ngữ cảnh khá nhỏ trừ khi bạn tăng nó lên, điều này khiến nhiều người ngạc nhiên khi dán các tài liệu dài và nhận được câu trả lời bỏ qua phần đầu.

Đối với trò chuyện nhiều lượt, hãy giữ một danh sách các tin nhắn và tự thêm mỗi phản hồi. Ollama, giống như hầu hết các API trò chuyện, không có trạng thái giữa các cuộc gọi.

Phản hồi streaming

Không có truyền phát, bạn sẽ đợi câu trả lời đầy đủ. Với stream=True, hàm trả về một generator và bạn in các phần khi chúng đến:

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)

Mỗi phần chứa một message.content nhỏ. Phần cuối có done được đặt thành true và bao gồm thời gian và số lượng token. Đối với ứng dụng web, hãy chuyển tiếp các mảnh này đến trình duyệt qua các sự kiện do máy chủ gửi hoặc websocket.

Các lỗi bạn thực sự sẽ thấy

Hai lỗi bao gồm hầu hết các vấn đề của người mới bắt đầu.

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?")

Lỗi 404 từ ResponseError có nghĩa là tên mô hình không khớp với thứ gì đó bạn đã pull về. Tên bao gồm các thẻ, vì vậy llama3 và llama3:70b là các mô hình khác nhau. Lỗi kết nối có nghĩa là máy chủ không hoạt động, hoặc bạn đang ở trong một container nơi localhost trỏ vào container, không phải host. Trong trường hợp đó, hãy truyền một client với host đúng: ollama.Client(host="http://host.docker.internal:11434").

Các mẫu khác được thu thập trong những sai lầm phổ biến về API Ollama.

Cùng chương trình, endpoint được lưu trữ

Các mô hình cục bộ bị giới hạn bởi bộ nhớ và tốc độ của bạn. Khi một tập lệnh phải chạy trên máy chủ, xử lý nhiều công việc đồng thời hoặc sử dụng cửa sổ lớn hơn, một endpoint được lưu trữ sẽ dễ dàng hơn. Mẹo là viết chương trình tương thích với SDK OpenAI và coi base URL, khóa và mô hình là cấu hình:

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.")

Đối với Ollama cục bộ, đặt LLM_BASE_URL=http://localhost:11434/v1, LLM_API_KEY=ollama (bất kỳ chuỗi nào không rỗng đều được chấp nhận ở đó) và LLM_MODEL=llama3. Đối với API được lưu trữ, hãy sử dụng các mặc định ở trên, khóa thực tế của bạn và mô hình uncensored. Không có gì khác trong mã thay đổi.

Lấy khóa trên trang khóa API. Tài khoản mới có thể nhận tín dụng dùng thử $0,50 chỉ với một cú nhấp chuột, không cần thanh toán, có giá trị trong 7 ngày. Mô hình là một mô hình trọng số mở từ một nhà cung cấp độc lập, được tinh chỉnh để trả lời mà không từ chối nội dung cho mục đích người lớn hợp pháp. Nó chỉ dành cho văn bản và không phải là API chính thức của bất kỳ phòng thí nghiệm lớn nào.

Chạy nhiều prompt song song

Một mô hình cục bộ trên một máy thường xử lý một yêu cầu tại một thời điểm, vì vậy các vòng lặp là tuần tự. Một endpoint được lưu trữ cho phép xử lý đồng thời, giúp công việc hàng loạt nhanh hơn nhiều. Hãy giữ số lượng worker dưới giới hạn của khóa của bạn: 8 yêu cầu đồng thời cho khóa đầy đủ, 2 cho khóa dùng thử.

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)

Sáu worker để lại khoảng trống dưới giới hạn 8. Nếu một worker nhận được lỗi 429, SDK OpenAI sẽ thử lại một vài lần theo mặc định, nhưng hãy thêm cơ chế backoff của riêng bạn cho các quá trình chạy dài. Ngoài ra, hãy nhớ rằng mọi yêu cầu truyền phát đều giữ slot của nó cho đến khi luồng kết thúc, vì vậy đừng trộn một cuộc trò chuyện truyền phát dài và một lô lớn trên cùng một khóa dùng thử.

Sự khác biệt cần lên kế hoạch

• Không có tùy chọn chỉ cục bộ. num_ctx và keep_alive không có ý nghĩa ở phía được lưu trữ. Cửa sổ ngữ cảnh là 100.000 token, bao gồm cả prompt và kết quả.
• Giới hạn tốc độ. Một khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 yêu cầu mỗi phút; một khóa dùng thử cho phép 2 và 60. Vượt quá giới hạn đó, bạn sẽ nhận được 429 với rate_limited hoặc concurrency. Thử lại sau một khoảng dừng; khi quá tải tạm thời, phản hồi mang Retry-After: 5.
• Chi phí. Đầu vào là $0,15 cho mỗi 1 triệu token và đầu ra là $0,50 cho mỗi 1 triệu. Một tập lệnh gửi 2.000 prompt với 600 token đầu vào và 400 token đầu ra sẽ tốn 2.000 x (600 x $0,15 + 400 x $0,50) / 1M = 2.000 x $0,00029 = $0,58.
• Hóa đơn. Tín dụng trả trước, từ $20 đến $500, thanh toán bằng tiền mã hóa (USDT trên TRC20 hoặc USDC trên Base). Các yêu cầu thất bại hoặc bị từ chối sẽ không bị tính phí.

Để so sánh các endpoint, hãy đọc ghi chú giá API của chúng tôi hoặc tài liệu.

Hướng dẫn khác

• API Ollama so với API OpenAI: Điểm cuối và Mã
• Cách sử dụng Ollama với GUI (và chế độ dự phòng lưu trữ)