Thư viện Python Ollama: Bắt đầu với LLM cục bộ

API LLM trên đám mây rất mạnh mẽ, nhưng đi kèm đánh đổi: tính phí theo mức sử dụng, giới hạn tốc độ và sự bất định thường trực về nơi dữ liệu của bạn được xử lý. Với các nhà phát triển làm việc với dữ liệu nhạy cảm hoặc thử nghiệm nhiều, những ràng buộc này có thể nhanh chóng trở thành lực cản.

Đó là lý do cách tiếp cận ưu tiên cục bộ trở nên nổi bật. Thư viện Python Ollama loại bỏ lực cản đó bằng cách cho phép bạn chạy các mô hình ngôn ngữ lớn ngay trên máy, đồng thời tương tác với chúng bằng mã Python gọn gàng, thuần bản địa. Bạn sẽ có toàn quyền kiểm soát hiệu năng, chi phí và quyền riêng tư.

Trong bài viết này, tôi sẽ hướng dẫn bạn toàn bộ API của thư viện Python Ollama, từ tạo văn bản đơn giản với generate() đến gọi công cụ và mô hình thị giác.

Tôi cũng khuyên bạn nên xem các hướng dẫn Ollama mới nhất khác của chúng tôi:

• Hướng dẫn Gemma 4: Xây dựng tác nhân AI lập trình cục bộ với Gradio và Ollama
• Hướng dẫn Qwen 3.5 Small Models: Xây dựng trình tạo Video-thành-Game với Ollama
• Sử dụng OpenClaw với Ollama: Xây dựng nhà phân tích dữ liệu cục bộ
• Sử dụng Claude Code với các mô hình cục bộ của Ollama

Điều kiện tiên quyết để chạy Ollama với Python

Trước khi bắt đầu, hãy đảm bảo bạn đã thiết lập các mục sau trên thiết bị:

• Python 3.8 trở lên

• Ollama được tải từ trang web của họ, cài đặt và đang chạy (ollama serve)

• Ít nhất đã kéo về một mô hình (ví dụ, ollama pull llama3.2)

Các điều kiện tiên quyết này quan trọng vì Python SDK chỉ là một client; việc suy luận thực tế diễn ra trong runtime của Ollama. Nếu runtime không khả dụng hoặc không có mô hình phù hợp, các lệnh gọi sẽ thất bại.

Bạn cũng có thể cân nhắc dùng Docker với Ollama để đảm bảo tính nhất quán phiên bản.

Thư viện Python Ollama là gì?

Thư viện Python Ollama là SDK chính thức bao bọc Ollama REST API thành một giao diện Pythonic đơn giản. Nói cách khác, nó chuyển các yêu cầu HTTP và payload JSON cấp thấp thành các hàm Python cấp cao để bạn tập trung vào mục tiêu thay vì chi tiết truyền tải.

Khi ứng dụng của bạn mở rộng, lớp trừu tượng này loại bỏ việc lặp lại xây dựng yêu cầu, chuẩn hóa cách xử lý phản hồi và tập trung hóa xử lý lỗi ở một nơi.

Để so sánh, một yêu cầu thô có thể trông như sau:

import requests

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

Cách này hoạt động, nhưng nhanh chóng trở nên dài dòng và dễ lỗi. Với SDK, cùng tác vụ đó trở thành:

import ollama

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

Cách thư viện giao tiếp với máy chủ Ollama

Ở tầng bên dưới, mỗi lệnh gọi SDK trở thành một yêu cầu HTTP tới máy chủ Ollama tại http://localhost:11434. Script Python của bạn đóng vai trò client, còn runtime của Ollama là server lưu trữ và thực thi mô hình.

Sự tách biệt này quan trọng vì cho phép mô hình chạy như một dịch vụ chuyên dụng, giúp quản lý tài nguyên (CPU/GPU) hiệu quả hơn và cho phép nhiều ứng dụng chia sẻ cùng một phiên bản mô hình.

Nếu cần kết nối tới máy khác, bạn có thể cấu hình một client tùy chỉnh:

from ollama import Client

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

Cài đặt và cấu hình thư viện

Việc cài đặt rất đơn giản và yêu cầu ít phụ thuộc:

pip install ollama

Sau khi cài đặt, bạn nên kiểm tra kết nối bằng cách liệt kê các mô hình sẵn có. 

Điều này giúp xác nhận môi trường Python, SDK và runtime Ollama của bạn đều được kết nối đúng.

Để thực hiện, hãy chạy:

import ollama

print(ollama.list())

Tạo văn bản với generate()

Hàm generate() được thiết kế cho các tác vụ không trạng thái, tức mỗi yêu cầu được xử lý độc lập mà không ghi nhớ tương tác trước đó. Điều này rất phù hợp cho các tác vụ như tóm tắt, viết lại hoặc tạo mã.

Vì không có ngữ cảnh được giữ lại, chất lượng đầu ra phụ thuộc hoàn toàn vào độ rõ ràng của prompt.

Tạo văn bản cơ bản

Ví dụ sau minh họa quy trình đơn giản nhất: gửi prompt, nhận phản hồi và trích xuất văn bản được tạo.

import ollama

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

print(response['response'])

Phản hồi cũng bao gồm siêu dữ liệu như thời gian thực thi và số lượng token, hữu ích khi tối ưu hiệu năng.

Tùy chỉnh đầu ra với tham số

Hành vi sinh có thể điều chỉnh bằng các tham số lấy mẫu, điều khiển cách mô hình chọn token.

Giá trị temperature thấp cho đầu ra quyết đoán hơn, trong khi giá trị cao tăng tính biến thiên. Bạn có thể dùng các tham số như top_p và num_predict để tinh chỉnh thêm độ đa dạng và độ dài đầu ra.

Dưới đây là một số tham số quan trọng bạn có thể dùng: 

Đây là ví dụ dùng các tham số top_p, temperature và 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
    }
)

Xây dựng hội thoại với chat()

Khác với generate(), API chat() hỗ trợ tương tác có trạng thái bằng cách làm việc với một chuỗi thông điệp. Điều này cho phép mô hình duy trì ngữ cảnh qua nhiều lượt.

Mỗi thông điệp gồm một vai trò như user, assistant hoặc system, giúp cấu trúc hội thoại.

Yêu cầu chat một lượt

Ngay cả tương tác một lượt cũng dùng định dạng thông điệp, đặt nền móng cho hội thoại phức tạp hơn.

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

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

Duy trì ngữ cảnh nhiều lượt

Để duy trì ngữ cảnh, bạn chủ động lưu và gửi lại toàn bộ lịch sử hội thoại trong mỗi yêu cầu. Cách này cho bạn toàn quyền kiểm soát mô hình nhớ điều gì.

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)

Dùng system prompt để định hình hành vi

System prompt dùng để xác định hành vi của mô hình từ đầu, như giọng điệu, ràng buộc hoặc vai trò.

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

Hỗ trợ Streaming và Async trong thư viện Python Ollama

Với ứng dụng tương tác, độ phản hồi quan trọng không kém độ chính xác. Ollama hỗ trợ cả streaming và thực thi bất đồng bộ để cải thiện hiệu năng và trải nghiệm người dùng.

Streaming phản hồi theo thời gian thực

Streaming cho phép bạn xử lý đầu ra dần dần khi nó được tạo, thay vì chờ toàn bộ phản hồi.

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

Dùng AsyncClient cho ứng dụng async

Thực thi bất đồng bộ cho phép ứng dụng xử lý đồng thời nhiều yêu cầu mà không bị chặn. Bạn sẽ cần dùng thư viện asyncio của Python để hiện thực.

Hãy xem ví dụ dưới đây:

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())

Quản lý mô hình Ollama từ Python

SDK của Ollama cũng cung cấp công cụ để quản lý mô hình bằng lập trình, đặc biệt hữu ích trong môi trường tự động.

Liệt kê và kiểm tra mô hình cục bộ

Bạn có thể lấy danh sách mô hình sẵn có và kiểm tra thuộc tính của chúng, như kích thước và cấu hình.

models = ollama.list()
print(models)

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

Kéo và xóa mô hình bằng lập trình

Mô hình có thể được tải về hoặc gỡ bỏ trực tiếp từ Python, giúp quản lý phụ thuộc linh hoạt hơn.

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

Tạo và sử dụng Embedding với thư viện Python Ollama

Embedding biểu diễn văn bản thành vector số học nắm bắt ý nghĩa ngữ nghĩa. Điều này cho phép bạn so sánh văn bản dựa trên độ tương đồng thay vì trùng khớp từ ngữ.

Tạo embedding văn bản

Ví dụ sau chuyển văn bản thành biểu diễn vector có thể dùng cho tìm kiếm hoặc phân cụm.

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

embedding = response['embeddings'][0]

Xây dựng tìm kiếm tương đồng cơ bản

Khi đã tạo embedding, có thể đo độ tương đồng bằng cosine similarity, so sánh góc giữa các vector.

Dưới đây là ví dụ đơn giản về hàm tìm kiếm:

import numpy as np

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

Gọi công cụ và đầu ra có cấu trúc trong thư viện Python Ollama

Để xây dựng ứng dụng nâng cao, các mô hình thường cần tương tác với hàm bên ngoài hoặc trả về dữ liệu có cấu trúc.

Triển khai gọi công cụ với hàm Python

Gọi công cụ cho phép mô hình gọi các hàm Python được định nghĩa sẵn dựa trên ý định của người dùng.

Hãy tạo một hàm sử dụng các công cụ như vậy:

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

Nhận phản hồi JSON có cấu trúc

Đầu ra có cấu trúc đảm bảo phản hồi được trả về theo định dạng nhất quán, máy có thể đọc được như JSON.

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

Nâng cao: Mô hình thị giác và Ollama Cloud trong Python

Ollama hỗ trợ các mô hình đa phương tiện và suy luận trên đám mây cho các trường hợp nâng cao.

Gửi ảnh tới mô hình thị giác

Mô hình thị giác có thể xử lý cả văn bản và hình ảnh, cho phép các tác vụ như mô tả ảnh và phân tích trực quan.

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

Chạy mô hình đám mây từ Python

Với các mô hình lớn không thể chạy cục bộ, Ollama Cloud cung cấp suy luận được lưu trữ.

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'}
)

Xử lý lỗi cho các lỗi thường gặp với Python Ollama

Khi xây dựng ứng dụng thực tế, xử lý lỗi rõ ràng giúp ngăn lỗi âm thầm và cải thiện độ tin cậy.

Xử lý ngoại lệ ResponseError

SDK của Ollama đưa ra ngoại lệ có cấu trúc cho lỗi phía server, cho phép bạn kiểm tra nguyên nhân.

import ollama

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

Gỡ lỗi kết nối và vấn đề mô hình

Các vấn đề thường gặp gồm server chưa chạy, thiếu mô hình, thiếu bộ nhớ hoặc vượt quá giới hạn ngữ cảnh.

• Server chưa chạy: Khởi động với ollama serve

• Không tìm thấy mô hình: Chạy ollama pull

• Thiếu bộ nhớ: Dùng mô hình nhỏ hơn hoặc lượng tử hóa

• Vấn đề ngữ cảnh: Điều chỉnh num_ctx

num_ctx điều khiển số token tối đa mô hình có thể “nhìn thấy” cùng lúc, bao gồm:

• prompt của bạn
• chỉ dẫn hệ thống
• lịch sử hội thoại
• tài liệu được truy xuất (RAG)
• và các token do chính mô hình tạo 

Quản lý tham số này sẽ giúp ngăn LLM cắt bớt nội dung trước đó (thường từ đầu) hoặc âm thầm làm mất chỉ dẫn hay dữ liệu quan trọng.

Tổng kết

Thư viện Python Ollama cung cấp giao diện đầy đủ để làm việc với LLM cục bộ và trên đám mây, từ tạo văn bản đơn giản đến các khả năng nâng cao như embedding, gọi công cụ và đầu vào đa phương thức. LLM trở thành một dịch vụ cục bộ mà bạn có thể viết script, kiểm thử và mở rộng như bất kỳ thành phần nào khác trong stack.

Theo trải nghiệm của tôi khi dùng Ollama, đây là một lựa chọn tốt khi bạn không muốn dùng LLM đám mây. Chẳng hạn, tôi có thể dùng các mô hình mã nguồn mở linh hoạt hơn. Nếu bạn cũng muốn có thêm tùy chọn để chuyển đổi giữa các mô hình, Ollama là một cánh cổng tốt để truy cập tất cả những điều này.

Nếu bạn muốn nâng cao kỹ năng, tôi khuyến nghị tham gia khóa học Developing LLM Applications with LangChain hoặc theo đuổi chứng chỉ Associate AI Engineer for Developers.