ollama

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 22, 2025 License: MIT Imports: 13 Imported by: 1

README

Ollama Go Client

中文文档 | English

A Go client library for Ollama, based on the official Python client.

Note: This is an unofficial Go client library inspired by the official Python client. It provides the same functionality and API design patterns with 98%+ feature parity.

✨ Features

  • Complete API Support: All Ollama REST API endpoints
  • Streaming Support: Real-time streaming for generation and chat
  • Type Safety: Full Go type definitions with compile-time checking
  • Flexible Configuration: Multiple client configuration options
  • Error Handling: Comprehensive error handling with JSON parsing
  • File Upload: Blob upload functionality for model creation
  • Advanced Options: 20+ configuration functions for fine-tuning
  • Context Support: Full context.Context support for cancellation

Installation

go get github.com/liliang-cn/ollama-go

Usage

Basic Usage
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/liliang-cn/ollama-go"
)

func main() {
    ctx := context.Background()
    
    // Generate a response
    response, err := ollama.Generate(ctx, "gemma3", "Why is the sky blue?")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response.Response)
}
Chat
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/liliang-cn/ollama-go"
)

func main() {
    ctx := context.Background()
    
    messages := []ollama.Message{
        {
            Role:    "user",
            Content: "Why is the sky blue?",
        },
    }

    response, err := ollama.Chat(ctx, "gemma3", messages)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response.Message.Content)
}
Streaming

Both Generate and Chat support streaming responses:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/liliang-cn/ollama-go"
)

func main() {
    ctx := context.Background()

    // Stream generation
    responseChan, errorChan := ollama.GenerateStream(ctx, "gemma3", "Tell me a story")

    for {
        select {
        case response, ok := <-responseChan:
            if !ok {
                return
            }
            fmt.Print(response.Response)
        case err := <-errorChan:
            if err != nil {
                log.Fatal(err)
            }
        }
    }
}
Custom Client

You can create a custom client with specific configuration:

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "time"

    "github.com/liliang-cn/ollama-go"
)

func main() {
    // Create a custom HTTP client
    httpClient := &http.Client{
        Timeout: 10 * time.Second,
    }

    // Create client with custom configuration
    client, err := ollama.NewClient(
        ollama.WithHost("http://localhost:11434"),
        ollama.WithHTTPClient(httpClient),
        ollama.WithHeaders(map[string]string{
            "Custom-Header": "custom-value",
        }),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()
    
    req := &ollama.GenerateRequest{
        Model:  "gemma3",
        Prompt: "Hello, world!",
    }

    response, err := client.Generate(ctx, req)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(response.Response)
}
Embeddings
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/liliang-cn/ollama-go"
)

func main() {
    ctx := context.Background()

    // Create embeddings
    response, err := ollama.Embed(ctx, "nomic-embed-text", "The quick brown fox")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Generated %d embeddings\n", len(response.Embeddings))
}
Model Creation with All Options
package main

import (
    "context"
    
    "github.com/liliang-cn/ollama-go"
)

func main() {
    ctx := context.Background()
    client, _ := ollama.NewClient()
    
    // Create model with complete configuration
    req := &ollama.CreateRequest{
        Model:     "my-custom-model",
        Modelfile: "FROM llama2\nSYSTEM \"You are a helpful assistant.\"",
        Files:     map[string]string{"data.txt": "training data"},
        Adapters:  map[string]string{"lora": "adapter_data"},
        Template:  "{{ .System }}{{ .Prompt }}",
        License:   "MIT",
        System:    "Custom system prompt",
        Parameters: &ollama.Options{
            Temperature: ollama.Float64Ptr(0.7),
        },
        Messages: []ollama.Message{
            {Role: "system", Content: "You are helpful"},
        },
    }
    
    status, err := client.Create(ctx, req)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Model created: %s\n", status.Status)
}
File Upload (Blob)
package main

import (
    "context"
    
    "github.com/liliang-cn/ollama-go"
)

func main() {
    ctx := context.Background()
    
    // Upload a file and get its digest
    digest, err := ollama.CreateBlob(ctx, "/path/to/file.bin")
    if err != nil {
        panic(err)
    }
    fmt.Printf("File uploaded with digest: %s\n", digest)
}
Progress Streaming

For operations like pulling models, you can stream progress updates:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/liliang-cn/ollama-go"
)

func main() {
    ctx := context.Background()

    progressChan, errorChan := ollama.PullStream(ctx, "gemma3")

    for {
        select {
        case progress, ok := <-progressChan:
            if !ok {
                fmt.Println("Pull completed!")
                return
            }
            if progress.Total > 0 {
                percentage := float64(progress.Completed) / float64(progress.Total) * 100
                fmt.Printf("Progress: %.1f%% (%s)\n", percentage, progress.Status)
            } else {
                fmt.Printf("Status: %s\n", progress.Status)
            }
        case err := <-errorChan:
            if err != nil {
                log.Fatal(err)
            }
        }
    }
}

API

Client Methods
  • Generate(ctx, req) - Generate a completion
  • GenerateStream(ctx, req) - Generate a streaming completion
  • Chat(ctx, req) - Send a chat message
  • ChatStream(ctx, req) - Send a chat message with streaming response
  • Embed(ctx, req) - Create embeddings
  • Embeddings(ctx, req) - Create embeddings (legacy API)
  • List(ctx) - List available models
  • Show(ctx, req) - Show model information
  • Pull(ctx, req) - Download a model
  • PullStream(ctx, req) - Download a model with progress
  • Push(ctx, req) - Upload a model
  • PushStream(ctx, req) - Upload a model with progress
  • Create(ctx, req) - Create a model from a Modelfile
  • CreateStream(ctx, req) - Create a model with progress
  • Delete(ctx, req) - Delete a model
  • Copy(ctx, req) - Copy a model
  • Ps(ctx) - List running processes
Global Functions

For convenience, all client methods are also available as global functions that use a default client instance:

  • ollama.Generate(ctx, model, prompt, options...)
  • ollama.Chat(ctx, model, messages, options...)
  • ollama.Embed(ctx, model, input, options...)
  • And so on...
Configuration Options

The client can be configured using option functions:

  • WithHost(host) - Set the Ollama server URL
  • WithHTTPClient(client) - Use a custom HTTP client
  • WithHeaders(headers) - Add custom headers
Request Options

Many functions support option functions for common configurations:

  • WithOptions(options) - Set model options
  • WithSystem(prompt) - Set system prompt
  • WithFormat(format) - Set response format
  • WithKeepAlive(duration) - Set keep alive duration
  • WithImages(images) - Add images (for multimodal models)
  • WithTools(tools) - Add tools for function calling
  • WithThinking() - Enable thinking mode

Environment Variables

  • OLLAMA_HOST - Set the Ollama server URL (default: http://localhost:11434)

License

This project is licensed under the MIT License.

Documentation

Overview

Package ollama provides a Go client library for the Ollama API.

Ollama is a tool for running large language models locally. This package provides a comprehensive Go client that mirrors the functionality of the official Python client with 98%+ feature parity.

Quick Start

The simplest way to use this package is with the global functions: 

ctx := context.Background()
response, err := ollama.Generate(ctx, "gemma3", "Why is the sky blue?")
if err != nil {
	log.Fatal(err)
}
fmt.Println(response.Response)

Chat Interface

For conversational interactions, use the Chat functions: 

messages := []ollama.Message{
	{Role: "user", Content: "Hello!"},
}
response, err := ollama.Chat(ctx, "gemma3", messages)
if err != nil {
	log.Fatal(err)
}
fmt.Println(response.Message.Content)

Streaming

Both Generate and Chat support streaming responses: 

responseChan, errorChan := ollama.GenerateStream(ctx, "gemma3", "Tell me a story")
for {
	select {
	case response, ok := <-responseChan:
		if !ok {
			return
		}
		fmt.Print(response.Response)
	case err := <-errorChan:
		if err != nil {
			log.Fatal(err)
		}
	}
}

Custom Client

For advanced configuration, create a custom client: 

client, err := ollama.NewClient(
	ollama.WithHost("http://localhost:11434"),
	ollama.WithHeaders(map[string]string{
		"Authorization": "Bearer token",
	}),
)
if err != nil {
	log.Fatal(err)
}

Model Management

The package provides comprehensive model management capabilities: 

// List available models
models, err := ollama.List(ctx)

// Pull a model
err = ollama.Pull(ctx, "gemma3")

// Show model information
info, err := ollama.Show(ctx, "gemma3")

Embeddings

Generate embeddings for text: 

response, err := ollama.Embed(ctx, "nomic-embed-text", "The quick brown fox")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Generated %d embeddings\n", len(response.Embeddings))

Configuration

The client can be configured using environment variables:

For more examples and detailed usage, see the examples directory in the repository.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BoolPtr 

func BoolPtr(b bool) *bool

BoolPtr returns a pointer to a bool value

func ChatStream 

func ChatStream(ctx context.Context, model string, messages []Message, options ...func(*ChatRequest)) (<-chan *ChatResponse, <-chan error)

ChatStream sends a chat message with streaming response using the default client. Similar to Chat but returns streaming responses for real-time interaction.

Example: 

messages := []ollama.Message{
	{Role: "user", Content: "Tell me a joke"},
}
responseChan, errorChan := ollama.ChatStream(ctx, "gemma3", messages)
for {
	select {
	case response, ok := <-responseChan:
		if !ok {
			return
		}
		fmt.Print(response.Message.Content)
	case err := <-errorChan:
		if err != nil {
			log.Fatal(err)
		}
	}
}

func CreateBlob 

func CreateBlob(ctx context.Context, path string) (string, error)

CreateBlob uploads a file using the default client

func CreateStream 

func CreateStream(ctx context.Context, model, modelfile string, options ...func(*CreateRequest)) (<-chan *ProgressResponse, <-chan error)

CreateStream creates a new model with progress using the default client

func Float64Ptr 

func Float64Ptr(f float64) *float64

Float64Ptr returns a pointer to a float64 value

func GenerateStream 

func GenerateStream(ctx context.Context, model, prompt string, options ...func(*GenerateRequest)) (<-chan *GenerateResponse, <-chan error)

GenerateStream generates a streaming response using the default client. It returns channels for receiving streaming responses and errors. The response channel will be closed when the stream is complete.

Example: 

responseChan, errorChan := ollama.GenerateStream(ctx, "gemma3", "Tell me a story")
for {
	select {
	case response, ok := <-responseChan:
		if !ok {
			return
		}
		fmt.Print(response.Response)
	case err := <-errorChan:
		if err != nil {
			log.Fatal(err)
		}
	}
}

func IntPtr 

func IntPtr(i int) *int

IntPtr returns a pointer to an int value

func PullStream 

func PullStream(ctx context.Context, model string, options ...func(*PullRequest)) (<-chan *ProgressResponse, <-chan error)

PullStream downloads a model with progress updates using the default client. Returns channels for receiving progress updates and errors.

Example: 

progressChan, errorChan := ollama.PullStream(ctx, "gemma3")
for {
	select {
	case progress, ok := <-progressChan:
		if !ok {
			fmt.Println("Download completed!")
			return
		}
		if progress.Total > 0 {
			percentage := float64(progress.Completed) / float64(progress.Total) * 100
			fmt.Printf("Progress: %.1f%%\n", percentage)
		}
	case err := <-errorChan:
		if err != nil {
			log.Fatal(err)
		}
	}
}

func PushStream 

func PushStream(ctx context.Context, model string, options ...func(*PushRequest)) (<-chan *ProgressResponse, <-chan error)

PushStream uploads a model with progress using the default client

func StringPtr 

func StringPtr(s string) *string

StringPtr returns a pointer to a string value

func WithAdapters 

func WithAdapters(adapters map[string]string) func(*CreateRequest)

WithAdapters sets the adapters for create requests

func WithChatSystem 

func WithChatSystem(system string) func(*ChatRequest)

WithChatSystem sets the system prompt for chat

func WithContext 

func WithContext(context []int) func(*GenerateRequest)

WithContext sets the context for generate requests

func WithCreateMessages 

func WithCreateMessages(messages []Message) func(*CreateRequest)

WithCreateMessages sets the messages for create requests

func WithCreateOptions 

func WithCreateOptions(options *Options) func(*CreateRequest)

WithCreateOptions sets the parameters for create requests

func WithCreateSystem 

func WithCreateSystem(system string) func(*CreateRequest)

WithCreateSystem sets the system prompt for create requests

func WithFiles 

func WithFiles(files map[string]string) func(*CreateRequest)

WithFiles sets the files for create requests

func WithFormat 

func WithFormat(format interface{}) func(interface{})

WithFormat sets the response format

func WithFrom 

func WithFrom(from string) func(*CreateRequest)

WithFrom sets the from model for create requests

func WithGenerateTemplate 

func WithGenerateTemplate(template string) func(*GenerateRequest)

WithTemplate sets the template for generate requests

func WithImages 

func WithImages(images []Image) func(interface{})

WithImages adds images to the request

func WithInsecure 

func WithInsecure(insecure bool) func(interface{})

WithInsecure sets insecure option for pull/push requests

func WithKeepAlive 

func WithKeepAlive(keepAlive interface{}) func(interface{})

WithKeepAlive sets the keep alive duration

func WithLicense 

func WithLicense(license interface{}) func(*CreateRequest)

WithLicense sets the license for create requests

func WithOptions 

func WithOptions(options *Options) func(interface{})

WithOptions sets the model options

func WithQuantize 

func WithQuantize(quantize string) func(*CreateRequest)

WithQuantize sets the quantization for create requests

func WithRaw 

func WithRaw() func(*GenerateRequest)

WithRaw sets the raw mode for generate requests

func WithSuffix 

func WithSuffix(suffix string) func(*GenerateRequest)

WithSuffix sets the suffix for generate requests

func WithSystem 

func WithSystem(system string) func(*GenerateRequest)

WithSystem sets the system prompt

func WithTemplate 

func WithTemplate(template string) func(*CreateRequest)

WithTemplate sets the template for create requests

func WithThinking 

func WithThinking() func(interface{})

WithThinking enables thinking mode

func WithTools 

func WithTools(tools []Tool) func(*ChatRequest)

WithTools adds tools to the chat request

func WithTruncate 

func WithTruncate(truncate bool) func(*EmbedRequest)

WithTruncate sets truncate option for embed requests

Types

type ChatRequest 

type ChatRequest struct {
	Model     string      `json:"model"`
	Messages  []Message   `json:"messages,omitempty"`
	Tools     []Tool      `json:"tools,omitempty"`
	Stream    *bool       `json:"stream,omitempty"`
	Format    interface{} `json:"format,omitempty"`
	Options   *Options    `json:"options,omitempty"`
	KeepAlive interface{} `json:"keep_alive,omitempty"`
	Think     *bool       `json:"think,omitempty"`
}

ChatRequest represents a chat request

type ChatResponse 

type ChatResponse struct {
	Model              string  `json:"model,omitempty"`
	CreatedAt          string  `json:"created_at,omitempty"`
	Message            Message `json:"message"`
	Done               bool    `json:"done,omitempty"`
	DoneReason         string  `json:"done_reason,omitempty"`
	TotalDuration      int64   `json:"total_duration,omitempty"`
	LoadDuration       int64   `json:"load_duration,omitempty"`
	PromptEvalCount    int     `json:"prompt_eval_count,omitempty"`
	PromptEvalDuration int64   `json:"prompt_eval_duration,omitempty"`
	EvalCount          int     `json:"eval_count,omitempty"`
	EvalDuration       int64   `json:"eval_duration,omitempty"`
}

ChatResponse represents a chat response

func Chat 

func Chat(ctx context.Context, model string, messages []Message, options ...func(*ChatRequest)) (*ChatResponse, error)

Chat sends a chat message using the default client. It provides a conversational interface where you can maintain message history.

Example: 

messages := []ollama.Message{
	{Role: "user", Content: "Hello!"},
}
response, err := ollama.Chat(ctx, "gemma3", messages)
if err != nil {
	log.Fatal(err)
}
fmt.Println(response.Message.Content)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client represents the Ollama API client. It handles HTTP communication with the Ollama server and manages authentication headers, base URL, and HTTP client configuration.

func NewClient 

func NewClient(options ...ClientOption) (*Client, error)

NewClient creates a new Ollama client with optional configuration. It reads the OLLAMA_HOST environment variable or uses localhost:11434 as default.

Example: 

client, err := ollama.NewClient(
	ollama.WithHost("http://localhost:11434"),
	ollama.WithHeaders(map[string]string{
		"Authorization": "Bearer token",
	}),
)
if err != nil {
	log.Fatal(err)
}

func (*Client) Chat 

func (c *Client) Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

Chat sends a chat request and returns the response

func (*Client) ChatStream 

func (c *Client) ChatStream(ctx context.Context, req *ChatRequest) (<-chan *ChatResponse, <-chan error)

ChatStream sends a chat request and returns a streaming response

func (*Client) CheckBlob 

func (c *Client) CheckBlob(ctx context.Context, digest string) (bool, error)

CheckBlob checks if a blob exists on the server

func (*Client) Copy 

func (c *Client) Copy(ctx context.Context, req *CopyRequest) (*StatusResponse, error)

Copy copies a model

func (*Client) Create 

func (c *Client) Create(ctx context.Context, req *CreateRequest) (*StatusResponse, error)

Create creates a new model

func (*Client) CreateBlob 

func (c *Client) CreateBlob(ctx context.Context, path string) (string, error)

CreateBlob uploads a file and returns its digest

func (*Client) CreateStream 

func (c *Client) CreateStream(ctx context.Context, req *CreateRequest) (<-chan *ProgressResponse, <-chan error)

CreateStream creates a new model with progress updates

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, req *DeleteRequest) (*StatusResponse, error)

Delete deletes a model

func (*Client) Embed 

func (c *Client) Embed(ctx context.Context, req *EmbedRequest) (*EmbedResponse, error)

Embed creates embeddings for the given input

func (*Client) Embeddings 

func (c *Client) Embeddings(ctx context.Context, req *EmbeddingsRequest) (*EmbeddingsResponse, error)

Embeddings creates embeddings for the given prompt (legacy API)

func (*Client) Generate 

func (c *Client) Generate(ctx context.Context, req *GenerateRequest) (*GenerateResponse, error)

Generate generates a response from a prompt

func (*Client) GenerateStream 

func (c *Client) GenerateStream(ctx context.Context, req *GenerateRequest) (<-chan *GenerateResponse, <-chan error)

GenerateStream generates a streaming response from a prompt

func (*Client) List 

func (c *Client) List(ctx context.Context) (*ListResponse, error)

List lists available models

func (*Client) Ps 

func (c *Client) Ps(ctx context.Context) (*ProcessResponse, error)

Ps shows running processes

func (*Client) Pull 

func (c *Client) Pull(ctx context.Context, req *PullRequest) (*StatusResponse, error)

Pull downloads a model

func (*Client) PullStream 

func (c *Client) PullStream(ctx context.Context, req *PullRequest) (<-chan *ProgressResponse, <-chan error)

PullStream downloads a model with progress updates

func (*Client) Push 

func (c *Client) Push(ctx context.Context, req *PushRequest) (*StatusResponse, error)

Push uploads a model

func (*Client) PushStream 

func (c *Client) PushStream(ctx context.Context, req *PushRequest) (<-chan *ProgressResponse, <-chan error)

PushStream uploads a model with progress updates

func (*Client) Show 

func (c *Client) Show(ctx context.Context, req *ShowRequest) (*ShowResponse, error)

Show returns information about a model

func (*Client) Version 

func (c *Client) Version(ctx context.Context) (*VersionResponse, error)

Version gets the Ollama server version

type ClientOption 

type ClientOption func(*Client)

ClientOption defines a function type for configuring the client. Options are applied during client creation to customize behavior.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client

func WithHeaders 

func WithHeaders(headers map[string]string) ClientOption

WithHeaders adds custom headers

func WithHost 

func WithHost(host string) ClientOption

WithHost sets the Ollama host URL

type CopyRequest 

type CopyRequest struct {
	Source      string `json:"source"`
	Destination string `json:"destination"`
}

CopyRequest represents a copy model request

type CreateRequest 

type CreateRequest struct {
	Model      string            `json:"model"`
	Modelfile  string            `json:"modelfile,omitempty"`
	Quantize   string            `json:"quantize,omitempty"`
	From       string            `json:"from,omitempty"`
	Files      map[string]string `json:"files,omitempty"`
	Adapters   map[string]string `json:"adapters,omitempty"`
	Template   string            `json:"template,omitempty"`
	License    interface{}       `json:"license,omitempty"` // string or []string
	System     string            `json:"system,omitempty"`
	Parameters *Options          `json:"parameters,omitempty"`
	Messages   []Message         `json:"messages,omitempty"`
	Stream     *bool             `json:"stream,omitempty"`
	Path       string            `json:"path,omitempty"`
}

CreateRequest represents a create model request

type DeleteRequest 

type DeleteRequest struct {
	Model string `json:"model"`
}

DeleteRequest represents a delete model request

type EmbedRequest 

type EmbedRequest struct {
	Model     string      `json:"model"`
	Input     interface{} `json:"input"` // string or []string
	Truncate  *bool       `json:"truncate,omitempty"`
	Options   *Options    `json:"options,omitempty"`
	KeepAlive interface{} `json:"keep_alive,omitempty"`
}

EmbedRequest represents an embedding request

type EmbedResponse 

type EmbedResponse struct {
	Model              string      `json:"model,omitempty"`
	Embeddings         [][]float64 `json:"embeddings"`
	TotalDuration      int64       `json:"total_duration,omitempty"`
	LoadDuration       int64       `json:"load_duration,omitempty"`
	PromptEvalCount    int         `json:"prompt_eval_count,omitempty"`
	PromptEvalDuration int64       `json:"prompt_eval_duration,omitempty"`
}

EmbedResponse represents an embedding response

func Embed 

func Embed(ctx context.Context, model string, input interface{}, options ...func(*EmbedRequest)) (*EmbedResponse, error)

Embed creates embeddings using the default client. It converts text into numerical vectors that can be used for semantic similarity.

The input parameter can be a string or []string for multiple inputs.

Example: 

response, err := ollama.Embed(ctx, "nomic-embed-text", "The quick brown fox")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Generated %d embeddings\n", len(response.Embeddings))

type EmbeddingsRequest 

type EmbeddingsRequest struct {
	Model     string      `json:"model"`
	Prompt    string      `json:"prompt,omitempty"`
	Options   *Options    `json:"options,omitempty"`
	KeepAlive interface{} `json:"keep_alive,omitempty"`
}

EmbeddingsRequest represents an embeddings request (legacy)

type EmbeddingsResponse 

type EmbeddingsResponse struct {
	Embedding []float64 `json:"embedding"`
}

EmbeddingsResponse represents an embeddings response (legacy)

func Embeddings 

func Embeddings(ctx context.Context, model, prompt string, options ...func(*EmbeddingsRequest)) (*EmbeddingsResponse, error)

Embeddings creates embeddings using the legacy API and default client

type ErrorResponse 

type ErrorResponse struct {
	Error string `json:"error"`
}

ErrorResponse represents an error response

type Function 

type Function struct {
	Name      string                 `json:"name"`
	Arguments map[string]interface{} `json:"arguments"`
}

Function represents the actual function call details. Contains the function name and its arguments.

type GenerateRequest 

type GenerateRequest struct {
	Model     string      `json:"model"`
	Prompt    string      `json:"prompt,omitempty"`
	Suffix    string      `json:"suffix,omitempty"`
	System    string      `json:"system,omitempty"`
	Template  string      `json:"template,omitempty"`
	Context   []int       `json:"context,omitempty"`
	Stream    *bool       `json:"stream,omitempty"`
	Raw       *bool       `json:"raw,omitempty"`
	Format    interface{} `json:"format,omitempty"`
	Options   *Options    `json:"options,omitempty"`
	Images    []Image     `json:"images,omitempty"`
	KeepAlive interface{} `json:"keep_alive,omitempty"`
	Think     *bool       `json:"think,omitempty"`
}

GenerateRequest represents a generation request

type GenerateResponse 

type GenerateResponse struct {
	Model              string `json:"model,omitempty"`
	CreatedAt          string `json:"created_at,omitempty"`
	Response           string `json:"response"`
	Done               bool   `json:"done,omitempty"`
	DoneReason         string `json:"done_reason,omitempty"`
	Context            []int  `json:"context,omitempty"`
	TotalDuration      int64  `json:"total_duration,omitempty"`
	LoadDuration       int64  `json:"load_duration,omitempty"`
	PromptEvalCount    int    `json:"prompt_eval_count,omitempty"`
	PromptEvalDuration int64  `json:"prompt_eval_duration,omitempty"`
	EvalCount          int    `json:"eval_count,omitempty"`
	EvalDuration       int64  `json:"eval_duration,omitempty"`
	Thinking           string `json:"thinking,omitempty"`
}

GenerateResponse represents a generation response

func Generate 

func Generate(ctx context.Context, model, prompt string, options ...func(*GenerateRequest)) (*GenerateResponse, error)

Generate generates a response using the default client. It sends a prompt to the specified model and returns the complete response.

Example: 

response, err := ollama.Generate(ctx, "gemma3", "Why is the sky blue?")
if err != nil {
	log.Fatal(err)
}
fmt.Println(response.Response)

type Image 

type Image struct {
	Data string `json:"-"`
}

Image represents an image input for multimodal models. The Data field can contain:

  • A file path to an image file
  • A data URI (data:image/...)
  • Base64 encoded image data

func (Image) MarshalJSON 

func (i Image) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for Image

type ListResponse 

type ListResponse struct {
	Models []ModelInfo `json:"models"`
}

ListResponse represents a model list response

func List 

func List(ctx context.Context) (*ListResponse, error)

List lists all available models using the default client. Returns information about each model including name, size, and modification time.

Example: 

models, err := ollama.List(ctx)
if err != nil {
	log.Fatal(err)
}
for _, model := range models.Models {
	fmt.Println(model.Name)
}

type Message 

type Message struct {
	Role      string     `json:"role"`
	Content   string     `json:"content,omitempty"`
	Images    []Image    `json:"images,omitempty"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	ToolName  string     `json:"tool_name,omitempty"`
	Thinking  string     `json:"thinking,omitempty"`
}

Message represents a chat message in the conversation. It contains the role (system, user, assistant), content, and optional multimedia elements.

type ModelDetails 

type ModelDetails struct {
	ParentModel       string   `json:"parent_model,omitempty"`
	Format            string   `json:"format,omitempty"`
	Family            string   `json:"family,omitempty"`
	Families          []string `json:"families,omitempty"`
	ParameterSize     string   `json:"parameter_size,omitempty"`
	QuantizationLevel string   `json:"quantization_level,omitempty"`
}

ModelDetails represents detailed model information

type ModelInfo 

type ModelInfo struct {
	Model      string        `json:"model,omitempty"`
	ModifiedAt *time.Time    `json:"modified_at,omitempty"`
	Digest     string        `json:"digest,omitempty"`
	Size       int64         `json:"size,omitempty"`
	Details    *ModelDetails `json:"details,omitempty"`
}

ModelInfo represents information about a model

type Options 

type Options struct {
	// Load time options
	Numa          *bool `json:"numa,omitempty"`
	NumCtx        *int  `json:"num_ctx,omitempty"`
	NumBatch      *int  `json:"num_batch,omitempty"`
	NumGPU        *int  `json:"num_gpu,omitempty"`
	MainGPU       *int  `json:"main_gpu,omitempty"`
	LowVRAM       *bool `json:"low_vram,omitempty"`
	F16KV         *bool `json:"f16_kv,omitempty"`
	LogitsAll     *bool `json:"logits_all,omitempty"`
	VocabOnly     *bool `json:"vocab_only,omitempty"`
	UseMmap       *bool `json:"use_mmap,omitempty"`
	UseMlock      *bool `json:"use_mlock,omitempty"`
	EmbeddingOnly *bool `json:"embedding_only,omitempty"`
	NumThread     *int  `json:"num_thread,omitempty"`

	// Runtime options
	NumKeep          *int     `json:"num_keep,omitempty"`
	Seed             *int     `json:"seed,omitempty"`
	NumPredict       *int     `json:"num_predict,omitempty"`
	TopK             *int     `json:"top_k,omitempty"`
	TopP             *float64 `json:"top_p,omitempty"`
	MinP             *float64 `json:"min_p,omitempty"`
	TFSZ             *float64 `json:"tfs_z,omitempty"`
	TypicalP         *float64 `json:"typical_p,omitempty"`
	RepeatLastN      *int     `json:"repeat_last_n,omitempty"`
	Temperature      *float64 `json:"temperature,omitempty"`
	RepeatPenalty    *float64 `json:"repeat_penalty,omitempty"`
	PresencePenalty  *float64 `json:"presence_penalty,omitempty"`
	FrequencyPenalty *float64 `json:"frequency_penalty,omitempty"`
	Mirostat         *int     `json:"mirostat,omitempty"`
	MirostatTau      *float64 `json:"mirostat_tau,omitempty"`
	MirostatEta      *float64 `json:"mirostat_eta,omitempty"`
	PenalizeNewline  *bool    `json:"penalize_newline,omitempty"`
	Stop             []string `json:"stop,omitempty"`
}

Options contains model configuration and inference parameters. These options control model behavior, performance, and resource usage. All fields use pointers to allow distinguishing between zero values and unset values.

type ProcessModel 

type ProcessModel struct {
	Model         string        `json:"model,omitempty"`
	Name          string        `json:"name,omitempty"`
	Digest        string        `json:"digest,omitempty"`
	ExpiresAt     *time.Time    `json:"expires_at,omitempty"`
	Size          int64         `json:"size,omitempty"`
	SizeVRAM      int64         `json:"size_vram,omitempty"`
	Details       *ModelDetails `json:"details,omitempty"`
	ContextLength int           `json:"context_length,omitempty"`
}

ProcessModel represents a running model process

type ProcessResponse 

type ProcessResponse struct {
	Models []ProcessModel `json:"models"`
}

ProcessResponse represents running processes

func Ps 

func Ps(ctx context.Context) (*ProcessResponse, error)

Ps shows running processes using the default client

type ProgressResponse 

type ProgressResponse struct {
	Status    string `json:"status,omitempty"`
	Digest    string `json:"digest,omitempty"`
	Total     int64  `json:"total,omitempty"`
	Completed int64  `json:"completed,omitempty"`
}

ProgressResponse represents a progress response for long-running operations

type PullRequest 

type PullRequest struct {
	Model    string `json:"model"`
	Insecure *bool  `json:"insecure,omitempty"`
	Stream   *bool  `json:"stream,omitempty"`
}

PullRequest represents a pull model request

type PushRequest 

type PushRequest struct {
	Model    string `json:"model"`
	Insecure *bool  `json:"insecure,omitempty"`
	Stream   *bool  `json:"stream,omitempty"`
}

PushRequest represents a push model request

type ResponseError 

type ResponseError struct {
	StatusCode int
	Message    string
}

ResponseError represents a response error

func (*ResponseError) Error 

func (e *ResponseError) Error() string

type ShowRequest 

type ShowRequest struct {
	Model   string `json:"model"`
	Verbose *bool  `json:"verbose,omitempty"`
}

ShowRequest represents a show model request

type ShowResponse 

type ShowResponse struct {
	ModifiedAt   *time.Time             `json:"modified_at,omitempty"`
	Template     string                 `json:"template,omitempty"`
	Modelfile    string                 `json:"modelfile,omitempty"`
	License      string                 `json:"license,omitempty"`
	Details      *ModelDetails          `json:"details,omitempty"`
	ModelInfo    map[string]interface{} `json:"model_info,omitempty"`
	Parameters   string                 `json:"parameters,omitempty"`
	Capabilities []string               `json:"capabilities,omitempty"`
}

ShowResponse represents a show model response

func Show 

func Show(ctx context.Context, model string) (*ShowResponse, error)

Show returns detailed information about a specific model using the default client. Includes model parameters, template, and system information.

Example: 

info, err := ollama.Show(ctx, "gemma3")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Model: %s, Size: %d\n", info.Details.Family, info.Details.ParameterSize)

type StatusResponse 

type StatusResponse struct {
	Status string `json:"status,omitempty"`
}

StatusResponse represents a simple status response

func Copy 

func Copy(ctx context.Context, source, destination string) (*StatusResponse, error)

Copy copies a model using the default client

func Create 

func Create(ctx context.Context, model, modelfile string, options ...func(*CreateRequest)) (*StatusResponse, error)

Create creates a new model using the default client

func Delete 

func Delete(ctx context.Context, model string) (*StatusResponse, error)

Delete deletes a model using the default client

func Pull 

func Pull(ctx context.Context, model string, options ...func(*PullRequest)) (*StatusResponse, error)

Pull downloads a model using the default client. Downloads the specified model from the Ollama registry.

Example: 

err := ollama.Pull(ctx, "gemma3")
if err != nil {
	log.Fatal(err)
}
fmt.Println("Model downloaded successfully")

func Push 

func Push(ctx context.Context, model string, options ...func(*PushRequest)) (*StatusResponse, error)

Push uploads a model using the default client

type Tool 

type Tool struct {
	Type     string        `json:"type,omitempty"`
	Function *ToolFunction `json:"function,omitempty"`
}

Tool represents a tool/function definition that can be used by the model. Tools allow the model to call external functions and get results.

type ToolCall 

type ToolCall struct {
	Function Function `json:"function"`
}

ToolCall represents a function call made by the model. Used when the model decides to call a tool/function during conversation.

type ToolFunction 

type ToolFunction struct {
	Name        string                 `json:"name,omitempty"`
	Description string                 `json:"description,omitempty"`
	Parameters  map[string]interface{} `json:"parameters,omitempty"`
}

ToolFunction represents the detailed specification of a tool function. Includes name, description, and parameter schema for the function.

type VersionResponse 

type VersionResponse struct {
	Version string `json:"version"`
}

VersionResponse represents a version response

Source Files

View all Source files

Directories

Path Synopsis
examples
chat command
chat-stream command
chat-with-history command
check-blob command
create command
debug command
embeddings command
fill-in-middle command
generate command
generate-stream command
gpt-oss-tools command
gpt-oss-tools-stream command
list command
multi-tool command
multimodal-chat command
multimodal-generate command
ps command
pull command
show command
show-verbose command
stream-debug command
structured-outputs command
structured-outputs-image command
test-suite command
thinking command
thinking-generate command
tools command
version command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.