Clientes Go para Ollama: comparação de SDK e exemplos com Qwen3/GPT-OSS

Integre o Ollama com Go: guia do SDK, exemplos e melhores práticas para produção.

Conteúdo da página

Este guia fornece uma visão abrangente dos SDKs Go para Ollama disponíveis e compara seus conjuntos de recursos.

Vamos explorar exemplos práticos em Go para chamar os modelos Qwen3 e GPT-OSS hospedados no Ollama — tanto via chamadas REST API brutas quanto via cliente Go oficial — incluindo o tratamento detalhado dos modos de pensamento e não-pensamento no Qwen3.

go e ollama

Por que Ollama + Go?

Ollama expõe uma pequena API HTTP prática (normalmente executando em http://localhost:11434) projetada para cargas de trabalho de geração e chat, com suporte embutido para streaming e capacidades de gerenciamento de modelos. A documentação oficial aborda detalhadamente as estruturas de solicitação/resposta /api/generate e /api/chat e os semânticos de streaming.

Go é uma excelente escolha para construir clientes Ollama devido ao seu forte suporte da biblioteca padrão para HTTP, excelente manipulação de JSON, primitivos de concorrência nativos e interfaces estáticamente tipadas que capturam erros em tempo de compilação.

Até outubro de 2025, aqui estão as opções de SDK Go que você provavelmente considerará.

SDKs Go para Ollama — o que está disponível?

SDK / Pacote Status & “proprietário” Escopo (Gerar/Chat/Streaming) Gerenciamento de modelos (puxar/listar/etc.) Extras / Notas
github.com/ollama/ollama/api Pacote oficial dentro do repositório Ollama; usado pelo próprio CLI ollama Cobertura completa mapeada para REST; streaming suportado Sim Considerado o cliente Go canônico; API espelha as documentações de forma próxima.
LangChainGo (github.com/tmc/langchaingo/llms/ollama) Framework comunitário (LangChainGo) com módulo Ollama LLM Chat/Completar + streaming via abstrações do framework Limitado (gerenciamento de modelos não é o objetivo principal) Ótimo se quiser cadeias, ferramentas, armazenamento de vetores em Go; menos de um SDK bruto.
github.com/swdunlop/ollama-client Cliente comunitário Foco no chat; bons experimentos de chamada de ferramentas Parcial Construído para experimentar com chamadas de ferramentas; não é uma superfície completa 1:1.
Outros SDKs comunitários (ex., ollamaclient, terceirizados “go-ollama-sdk”) Comunidade Varia Varia Qualidade e cobertura variam; avalie por repositório.

Recomendação: Para produção, prefira github.com/ollama/ollama/api — é mantido com o projeto principal e espelha a API REST.

Qwen3 & GPT-OSS no Ollama: modo de pensamento vs não-pensamento (o que saber)

  • Modo de pensamento no Ollama separa o “raciocínio” do modelo da saída final quando ativado. Ollama documenta um comportamento de habilitar/desabilitar pensamento de primeira classe em todos os modelos suportados.
  • (https://www.glukhov.org/pt/post/2025/10/qwen3-30b-vs-gpt-oss-20b/ “Qwen3:30b vs GPT-OSS:20b: Detalhes técnicos, comparação de desempenho e velocidade”) suporta alternância dinâmica: adicione /think ou /no_think nas mensagens do sistema/usuário para alternar modos passo a passo; a última instrução vence.
  • GPT-OSS: usuários relatam que desativar o pensamento (ex., /set nothink ou --think=false) pode ser imprevisível no gpt-oss:20b; planeje filtrar/ocultar qualquer raciocínio que sua interface não deva exibir.

Parte 1 — Chamando Ollama via REST bruto (Go, net/http)

Tipos compartilhados

Primeiro, vamos definir os tipos comuns e funções auxiliares que usaremos em nossos exemplos:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"
)

// ---- Tipos da API de Chat ----

type ChatMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type ChatRequest struct {
	Model    string        `json:"model"`
	Messages []ChatMessage `json:"messages"`
	// Alguns servidores expõem o controle de pensamento como um sinal booleano.
	// Mesmo se omitido, você ainda pode controlar o Qwen3 via /think ou /no_think.
	Think   *bool          `json:"think,omitempty"`
	Stream  *bool          `json:"stream,omitempty"`
	Options map[string]any `json:"options,omitempty"`
}

type ChatResponse struct {
	Model     string `json:"model"`
	CreatedAt string `json:"created_at"`
	Message   struct {
		Role     string `json:"role"`
		Content  string `json:"content"`
		Thinking string `json:"thinking,omitempty"` // presente quando o pensamento está ativado
	} `json:"message"`
	Done bool `json:"done"`
}

// ---- Tipos da API de Geração ----

type GenerateRequest struct {
	Model   string         `json:"model"`
	Prompt  string         `json:"prompt"`
	Think   *bool          `json:"think,omitempty"`
	Stream  *bool          `json:"stream,omitempty"`
	Options map[string]any `json:"options,omitempty"`
}

type GenerateResponse struct {
	Model     string `json:"model"`
	CreatedAt string `json:"created_at"`
	Response  string `json:"response"`           // texto final para não-stream
	Thinking  string `json:"thinking,omitempty"` // presente quando o pensamento está ativado
	Done      bool   `json:"done"`
}

// ---- Funções auxiliares ----

func httpPostJSON(url string, payload any) ([]byte, error) {
	body, err := json.Marshal(payload)
	if err != nil {
		return nil, err
	}
	c := &http.Client{Timeout: 60 * time.Second}
	resp, err := c.Post(url, "application/json", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	return io.ReadAll(resp.Body)
}

// bptr retorna um ponteiro para um valor booleano
func bptr(b bool) *bool { return &b }

Chat — Qwen3 com pensamento ATIVADO (e como desativá-lo)

func chatQwen3Thinking() error {
	endpoint := "http://localhost:11434/api/chat"

	req := ChatRequest{
		Model:   "qwen3:8b-thinking", // qualquer tag :*-thinking que você tenha puxado
		Think:   bptr(true),
		Stream:  bptr(false),
		Messages: []ChatMessage{
			{Role: "system", Content: "Você é um assistente preciso."},
			{Role: "user",   Content: "Explique recursão com um exemplo curto em Go."},
		},
	}

	raw, err := httpPostJSON(endpoint, req)
	if err != nil {
		return err
	}
	var out ChatResponse
	if err := json.Unmarshal(raw, &out); err != nil {
		return err
	}
	fmt.Println("🧠 pensamento:\n", out.Message.Thinking)
	fmt.Println("\n💬 resposta:\n", out.Message.Content)
	return nil
}

// Para desativar o pensamento na próxima rodada, faça:
// (a) definindo Think=false, e/ou
// (b) adicionando "/no_think" na mensagem do sistema/usuário mais recente (chave de ativação suave do Qwen3).
// O Qwen3 honra a última instrução /think ou /no_think em conversas de múltiplas rodadas.
func chatQwen3NoThinking() error {
	endpoint := "http://localhost:11434/api/chat"

	req := ChatRequest{
		Model:  "qwen3:8b-thinking",
		Think:  bptr(false),
		Stream: bptr(false),
		Messages: []ChatMessage{
			{Role: "system", Content: "Você é breve. /no_think"},
			{Role: "user",   Content: "Explique recursão em uma frase."},
		},
	}

	raw, err := httpPostJSON(endpoint, req)
	if err != nil {
		return err
	}
	var out ChatResponse
	if err := json.Unmarshal(raw, &out); err != nil {
		return err
	}
	// Espere que o pensamento esteja vazio; ainda assim, trate defensivamente.
	if out.Message.Thinking != "" {
		fmt.Println("🧠 pensamento (inesperado):\n", out.Message.Thinking)
	}
	fmt.Println("\n💬 resposta:\n", out.Message.Content)
	return nil
}

(O soft switch de /think e /no_think do Qwen3 é documentado pela equipe do Qwen; a última instrução vence em conversas de múltiplas rodadas.)

Chat — GPT-OSS com pensamento (e uma observação)

func chatGptOss() error {
	endpoint := "http://localhost:11434/api/chat"

	req := ChatRequest{
		Model:  "gpt-oss:20b",
		Think:  bptr(true),   // solicita raciocínio separado se suportado
		Stream: bptr(false),
		Messages: []ChatMessage{
			{Role: "user", Content: "O que é programação dinâmica? Explique a ideia central."},
		},
	}

	raw, err := httpPostJSON(endpoint, req)
	if err != nil {
		return err
	}
	var out ChatResponse
	if err := json.Unmarshal(raw, &out); err != nil {
		return err
	}
	// Quirks conhecidos: desativar o pensamento pode não suprimir completamente o raciocínio no gpt-oss:20b.
	// Sempre filtre/oculte o pensamento na interface se não quiser exibi-lo.
	fmt.Println("🧠 pensamento:\n", out.Message.Thinking)
	fmt.Println("\n💬 resposta:\n", out.Message.Content)
	return nil
}

Usuários relatam que desativar o pensamento no gpt-oss:20b (ex., /set nothink ou --think=false) pode ser ignorado — planeje a filtragem no lado do cliente se necessário.

Geração — Qwen3 e GPT-OSS

func generateQwen3() error {
	endpoint := "http://localhost:11434/api/generate"
	req := GenerateRequest{
		Model:  "qwen3:4b-thinking",
		Prompt: "Em 2–3 frases, para que servem as árvores B em bancos de dados?",
		Think:  bptr(true),
	}
	raw, err := httpPostJSON(endpoint, req)
	if err != nil {
		return err
	}
	var out GenerateResponse
	if err := json.Unmarshal(raw, &out); err != nil {
		return err
	}
	if out.Thinking != "" {
		fmt.Println("🧠 pensamento:\n", out.Thinking)
	}
	fmt.Println("\n💬 resposta:\n", out.Response)
	return nil
}

func generateGptOss() error {
	endpoint := "http://localhost:11434/api/generate"
	req := GenerateRequest{
		Model:  "gpt-oss:20b",
		Prompt: "Explique brevemente a retropropagação em redes neurais.",
		Think:  bptr(true),
	}
	raw, err := httpPostJSON(endpoint, req)
	if err != nil {
		return err
	}
	var out GenerateResponse
	if err := json.Unmarshal(raw, &out); err != nil {
		return err
	}
	if out.Thinking != "" {
		fmt.Println("🧠 pensamento:\n", out.Thinking)
	}
	fmt.Println("\n💬 resposta:\n", out.Response)
	return nil
}

As formas REST e o comportamento de streaming vêm diretamente da referência da API Ollama.

Parte 2 — Chamando Ollama via o SDK Go oficial (github.com/ollama/ollama/api)

O pacote oficial expõe um Client com métodos que correspondem à API REST. O próprio CLI Ollama usa este pacote para se comunicar com o serviço, o que o torna a melhor escolha para compatibilidade.

Instalação

go get github.com/ollama/ollama/api

Chat — Qwen3 (pensamento ATIVADO / DESATIVADO)

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/ollama/ollama/api"
)

func chatWithQwen3Thinking(ctx context.Context, thinking bool) error {
	client, err := api.ClientFromEnvironment() // honra OLLAMA_HOST se definido
	if err != nil {
		return err
	}

	req := &api.ChatRequest{
		Model: "qwen3:8b-thinking",
		// Muitas construções de servidor expõem o pensamento como um sinal de nível superior;
		// além disso, você pode controlar o Qwen3 via /think ou /no_think nas mensagens.
		Think: api.Ptr(thinking),
		Messages: []api.Message{
			{Role: "system", Content: "Você é um assistente preciso."},
			{Role: "user",   Content: "Explique o merge sort com um snippet curto em Go."},
		},
	}

	var resp api.ChatResponse
	if err := client.Chat(ctx, req, &resp); err != nil {
		return err
	}

	if resp.Message.Thinking != "" {
		fmt.Println("🧠 pensamento:\n", resp.Message.Thinking)
	}
	fmt.Println("\n💬 resposta:\n", resp.Message.Content)
	return nil
}

func main() {
	ctx := context.Background()
	if err := chatWithQwen3Thinking(ctx, true); err != nil {
		log.Fatal(err)
	}
	// Exemplo: não-pensamento
	if err := chatWithQwen3Thinking(ctx, false); err != nil {
		log.Fatal(err)
	}
}

Chat — GPT-OSS (trate o raciocínio defensivamente)

func chatWithGptOss(ctx context.Context) error {
	client, err := api.ClientFromEnvironment()
	if err != nil {
		return err
	}
	req := &api.ChatRequest{
		Model: "gpt-oss:20b",
		Think: api.Ptr(true),
		Messages: []api.Message{
			{Role: "user", Content: "O que é memoização e quando é útil?"},
		},
	}
	var resp api.ChatResponse
	if err := client.Chat(ctx, req, &resp); err != nil {
		return err
	}
	// Se você pretende ocultar o raciocínio, faça-o aqui, independentemente dos sinalizadores.
	if resp.Message.Thinking != "" {
		fmt.Println("🧠 pensamento:\n", resp.Message.Thinking)
	}
	fmt.Println("\n💬 resposta:\n", resp.Message.Content)
	return nil
}

Geração — Qwen3 & GPT-OSS

func generateWithQwen3(ctx context.Context) error {
	client, err := api.ClientFromEnvironment()
	if err != nil {
		return err
	}
	req := &api.GenerateRequest{
		Model:  "qwen3:4b-thinking",
		Prompt: "Resuma o papel de uma árvore B no indexação.",
		Think:  api.Ptr(true),
	}
	var resp api.GenerateResponse
	if err := client.Generate(ctx, req, &resp); err != nil {
		return err
	}
	if resp.Thinking != "" {
		fmt.Println("🧠 pensamento:\n", resp.Thinking)
	}
	fmt.Println("\n💬 resposta:\n", resp.Response)
	return nil
}

func generateWithGptOss(ctx context.Context) error {
	client, err := api.ClientFromEnvironment()
	if err != nil {
		return err
	}
	req := &api.GenerateRequest{
		Model:  "gpt-oss:20b",
		Prompt: "Explique o descenso de gradiente em termos simples.",
		Think:  api.Ptr(true),
	}
	var resp api.GenerateResponse
	if err := client.Generate(ctx, req, &resp); err != nil {
		return err
	}
	if resp.Thinking != "" {
		fmt.Println("🧠 pensamento:\n", resp.Thinking)
	}
	fmt.Println("\n💬 resposta:\n", resp.Response)
	return nil
}

A superfície do pacote oficial espelha as documentações REST e é atualizada junto com o projeto principal.

Respostas de streaming

Para streaming em tempo real, defina Stream: bptr(true) em sua solicitação. A resposta será entregue como blocos JSON delimitados por nova linha:

func streamChatExample() error {
	endpoint := "http://localhost:11434/api/chat"
	req := ChatRequest{
		Model:  "qwen3:8b-thinking",
		Think:  bptr(true),
		Stream: bptr(true), // Ative o streaming
		Messages: []ChatMessage{
			{Role: "user", Content: "Explique o algoritmo de quicksort passo a passo."},
		},
	}

	body, _ := json.Marshal(req)
	resp, err := http.Post(endpoint, "application/json", bytes.NewReader(body))
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	decoder := json.NewDecoder(resp.Body)
	for {
		var chunk ChatResponse
		if err := decoder.Decode(&chunk); err == io.EOF {
			break
		} else if err != nil {
			return err
		}
		
		// Processar pensamento e conteúdo conforme chegam
		if chunk.Message.Thinking != "" {
			fmt.Print(chunk.Message.Thinking)
		}
		fmt.Print(chunk.Message.Content)
		
		if chunk.Done {
			break
		}
	}
	return nil
}

Com o SDK oficial, use uma função de callback para lidar com os blocos de streaming:

func streamWithOfficialSDK(ctx context.Context) error {
	client, _ := api.ClientFromEnvironment()
	
	req := &api.ChatRequest{
		Model: "qwen3:8b-thinking",
		Think: api.Ptr(true),
		Messages: []api.Message{
			{Role: "user", Content: "Explique árvores de busca binária."},
		},
	}
	
	err := client.Chat(ctx, req, func(resp api.ChatResponse) error {
		if resp.Message.Thinking != "" {
			fmt.Print(resp.Message.Thinking)
		}
		fmt.Print(resp.Message.Content)
		return nil
	})
	
	return err
}

Trabalhando com pensamento vs não-pensamento do Qwen3 (orientação prática)

  • Dois levers:

    1. Um sinal booleano thinking suportado pela funcionalidade de pensamento do Ollama; e
    2. O comando de chave de ativação suave do Qwen3 /think e /no_think na mensagem do sistema/usuário mais recente. A instrução mais recente governa a próxima(s) rodada(s).

  • Postura padrão: não-pensamento para respostas rápidas; escalone para pensamento para tarefas que precisam de raciocínio passo a passo (matemática, planejamento, depuração, análise complexa de código).

  • UIs de streaming: quando o pensamento está ativado, você pode ver raciocínio/contúdo intercalados em quadros de streaming — bufferize ou renderize-os separadamente e dê aos usuários um botão “mostrar raciocínio”. (Veja as documentações da API para o formato de streaming.)

  • Conversas de múltiplas rodadas: o Qwen3 lembra o modo de pensamento das rodadas anteriores. Se quiser alternar durante a conversa, use tanto o sinal quanto o comando de chave de ativação suave para confiabilidade.

Notas para GPT-OSS

  • Trate o raciocínio como presente mesmo se tentou desativá-lo; filtre no lado do cliente se sua UX não deve exibi-lo.
  • Para aplicações de produção usando GPT-OSS, implemente lógica de filtragem no lado do cliente que possa detectar e remover padrões de raciocínio se necessário.
  • Teste sua variante específica do modelo GPT-OSS de forma abrangente, pois o comportamento pode variar entre diferentes quantizações e versões.

Boas práticas e dicas para produção

Tratamento de erros e timeouts

Sempre implemente um tratamento adequado de timeout e recuperação de erros:

func robustChatRequest(ctx context.Context, model string, messages []api.Message) (*api.ChatResponse, error) {
	// Defina um timeout razoável
	ctx, cancel := context.WithTimeout(ctx, 2*time.Minute)
	defer cancel()
	
	client, err := api.ClientFromEnvironment()
	if err != nil {
		return nil, fmt.Errorf("criando cliente: %w", err)
	}
	
	req := &api.ChatRequest{
		Model:    model,
		Messages: messages,
		Options: map[string]interface{}{
			"temperature": 0.7,
			"num_ctx":     4096, // tamanho da janela de contexto
		},
	}
	
	var resp api.ChatResponse
	if err := client.Chat(ctx, req, &resp); err != nil {
		return nil, fmt.Errorf("solicitação de chat falhou: %w", err)
	}
	
	return &resp, nil
}

Pooling de conexões e reutilização

Reutilize o cliente Ollama entre solicitações em vez de criar um novo a cada vez:

type OllamaService struct {
	client *api.Client
}

func NewOllamaService() (*OllamaService, error) {
	client, err := api.ClientFromEnvironment()
	if err != nil {
		return nil, err
	}
	return &OllamaService{client: client}, nil
}

func (s *OllamaService) Chat(ctx context.Context, req *api.ChatRequest) (*api.ChatResponse, error) {
	var resp api.ChatResponse
	if err := s.client.Chat(ctx, req, &resp); err != nil {
		return nil, err
	}
	return &resp, nil
}

Configuração de ambiente

Use variáveis de ambiente para implantação flexível:

export OLLAMA_HOST=http://localhost:11434
export OLLAMA_NUM_PARALLEL=2
export OLLAMA_MAX_LOADED_MODELS=2

O SDK oficial respeita automaticamente OLLAMA_HOST via api.ClientFromEnvironment().

Monitoramento e logging

Implemente logging estruturado para sistemas de produção:

func loggedChat(ctx context.Context, logger *log.Logger, req *api.ChatRequest) error {
	start := time.Now()
	client, _ := api.ClientFromEnvironment()
	
	var resp api.ChatResponse
	err := client.Chat(ctx, req, &resp)
	
	duration := time.Since(start)
	logger.Printf("model=%s duration=%v error=%v tokens=%d", 
		req.Model, duration, err, len(resp.Message.Content))
	
	return err
}

Conclusão

  • Para projetos Go, github.com/ollama/ollama/api é a escolha mais completa e pronta para produção. É mantido junto com o projeto principal do Ollama, usado pelo CLI oficial e fornece cobertura abrangente da API com compatibilidade garantida.

  • Para abstrações de nível superior, considere LangChainGo quando precisar de cadeias, ferramentas, armazenamento de vetores e pipelines RAG — embora você tenha que trocar algum controle de nível baixo pela conveniência.

  • Qwen3 lhe dá controle limpo e confiável sobre o modo de pensamento com ambos os sinalizadores e comutadores de nível de mensagem (/think, /no_think), tornando-o ideal para aplicações que precisam de respostas rápidas e raciocínio profundo.

  • Para GPT-OSS, planeje sempre sanitizar a saída de raciocínio no lado do cliente quando necessário, pois o sinalizador de desativação de pensamento pode não ser respeitado consistentemente.

  • Em produção, implemente tratamento adequado de erros, pooling de conexões, timeouts e monitoramento para construir aplicações robustas com Ollama.

A combinação do forte tipagem do Go, excelente suporte à concorrência e da API direta do Ollama torna-o um stack ideal para construir aplicações com IA — desde chatbots simples até sistemas RAG complexos.

Principais lições aprendidas

Aqui está uma referência rápida para escolher sua abordagem:

Caso de uso Abordagem recomendada Por quê
Aplicação de produção github.com/ollama/ollama/api Suporte oficial, cobertura completa da API, mantido com o projeto principal
Pipeline de RAG/cadeias/ferramentas LangChainGo Abstrações de nível superior, integrações com armazenamento de vetores
Aprendizado/experimentação REST bruto com net/http Transparência total, sem dependências, educacional
Prototipagem rápida SDK oficial Equilíbrio entre simplicidade e poder
UI de chat de streaming SDK oficial com callbacks Suporte embutido a streaming, API limpa

Diretrizes para seleção de modelos:

  • Qwen3: Melhor para aplicações que exigem controle sobre o modo de pensamento, conversas confiáveis de múltiplas rodadas
  • GPT-OSS: Boem desempenho, mas requer tratamento defensivo da saída de raciocínio
  • Outros modelos: Teste abrangente; o comportamento de pensamento varia por família de modelos

Referências & leitura adicional

Documentação oficial

Alternativas ao SDK Go

Recursos específicos do modelo

Tópicos relacionados