Go에서 Ollama Web Search API 사용하기

Go와 Ollama로 AI 검색 에이전트를 구축하세요

Page content

Ollama의 웹 검색 API는 로컬 LLM에 실시간 웹 정보를 추가할 수 있게 해줍니다. 이 가이드는 Go에서 웹 검색 기능 구현 방법을 보여줍니다. 간단한 API 호출부터 완전한 기능의 검색 에이전트까지.

자전거를 타는 고퍼

시작하기

Ollama에 웹 검색을 위한 공식 Go 라이브러리가 있나요? Ollama는 웹 검색을 위한 REST API를 제공하며, 이는 모든 Go HTTP 클라이언트와 호환됩니다. 웹 검색을 위한 공식 Go SDK는 아직 없지만, 표준 라이브러리 패키지 사용으로 API 호출을 쉽게 구현할 수 있습니다.

먼저 Ollama 계정에서 API 키를 생성하세요. Ollama 명령어 및 사용법에 대한 종합적인 참고서는 Ollama 체크리스트를 참조하세요.

API 키를 환경 변수로 설정하세요:

export OLLAMA_API_KEY="your_api_key"

Windows PowerShell에서:

$env:OLLAMA_API_KEY = "your_api_key"

프로젝트 설정

새로운 Go 모듈을 생성하세요:

mkdir ollama-search
cd ollama-search
go mod init ollama-search

기본 웹 검색

Go에서 Ollama 웹 검색 API에 인증하려면 어떻게 하나요? Authorization 헤더에 Bearer 토큰으로 API 키를 설정하세요. Ollama 계정에서 API 키를 생성한 후 요청 헤더에 전달하세요.

웹 검색 API의 완전한 구현 예시:

package main

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

// 웹 검색을 위한 요청/응답 타입
type WebSearchRequest struct {
	Query      string `json:"query"`
	MaxResults int    `json:"max_results,omitempty"`
}

type WebSearchResult struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Content string `json:"content"`
}

type WebSearchResponse struct {
	Results []WebSearchResult `json:"results"`
}

func webSearch(query string, maxResults int) (*WebSearchResponse, error) {
	apiKey := os.Getenv("OLLAMA_API_KEY")
	if apiKey == "" {
		return nil, fmt.Errorf("OLLAMA_API_KEY 환경 변수가 설정되지 않았습니다.")
	}

	reqBody := WebSearchRequest{
		Query:      query,
		MaxResults: maxResults,
	}
	jsonData, err := json.Marshal(reqBody)
	if err != nil {
		return nil, fmt.Errorf("요청을 marshaling하는 데 실패했습니다: %w", err)
	}

	req, err := http.NewRequest("POST", "https://ollama.com/api/web_search", bytes.NewBuffer(jsonData))
	if err != nil {
		return nil, fmt.Errorf("요청 생성 실패: %w", err)
	}

	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("요청 실패: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return nil, fmt.Errorf("API 오류 (상태 %d): %s", resp.StatusCode, string(body))
	}

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("응답 읽기 실패: %w", err)
	}

	var searchResp WebSearchResponse
	if err := json.Unmarshal(body, &searchResp); err != nil {
		return nil, fmt.Errorf("응답을 unmarshal하는 데 실패했습니다: %w", err)
	}

	return &searchResp, nil
}

func main() {
	results, err := webSearch("Ollama란 무엇인가요?", 5)
	if err != nil {
		fmt.Printf("오류: %v\n", err)
		return
	}

	fmt.Println("검색 결과:")
	fmt.Println("===============")
	for i, result := range results.Results {
		fmt.Printf("\n%d. %s\n", i+1, result.Title)
		fmt.Printf("   URL: %s\n", result.URL)
		fmt.Printf("   %s\n", truncate(result.Content, 150))
	}
}

func truncate(s string, maxLen int) string {
	if len(s) <= maxLen {
		return s
	}
	return s[:maxLen] + "..."
}

웹 가져오기 구현

web_search와 web_fetch 엔드포인트의 차이점은 무엇인가요? web_search 엔드포인트는 인터넷을 검색하여 제목, URL, 요약문을 포함한 여러 검색 결과를 반환합니다. web_fetch 엔드포인트는 특정 URL의 전체 내용을 가져오며, 페이지 제목, 내용, 링크를 반환합니다.

package main

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

// 웹 가져오기를 위한 요청/응답 타입
type WebFetchRequest struct {
	URL string `json:"url"`
}

type WebFetchResponse struct {
	Title   string   `json:"title"`
	Content string   `json:"content"`
	Links   []string `json:"links"`
}

func webFetch(url string) (*WebFetchResponse, error) {
	apiKey := os.Getenv("OLLAMA_API_KEY")
	if apiKey == "" {
		return nil, fmt.Errorf("OLLAMA_API_KEY 환경 변수가 설정되지 않았습니다.")
	}

	reqBody := WebFetchRequest{URL: url}
	jsonData, err := json.Marshal(reqBody)
	if err != nil {
		return nil, fmt.Errorf("요청을 marshaling하는 데 실패했습니다: %w", err)
	}

	req, err := http.NewRequest("POST", "https://ollama.com/api/web_fetch", bytes.NewBuffer(jsonData))
	if err != nil {
		return nil, fmt.Errorf("요청 생성 실패: %w", err)
	}

	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("요청 실패: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		body, _ := io.ReadAll(resp.Body)
		return nil, fmt.Errorf("API 오류 (상태 %d): %s", resp.StatusCode, string(body))
	}

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("응답 읽기 실패: %w", err)
	}

	var fetchResp WebFetchResponse
	if err := json.Unmarshal(body, &fetchResp); err != nil {
		return nil, fmt.Errorf("응답을 unmarshal하는 데 실패했습니다: %w", err)
	}

	return &fetchResp, nil
}

func main() {
	result, err := webFetch("https://ollama.com")
	if err != nil {
		fmt.Printf("오류: %v\n", err)
		return
	}

	fmt.Printf("제목: %s\n\n", result.Title)
	fmt.Printf("내용:\n%s\n\n", result.Content)
	fmt.Printf("찾은 링크 수: %d\n", len(result.Links))
	for i, link := range result.Links {
		if i >= 5 {
			fmt.Printf("  ... 그리고 %d개 더\n", len(result.Links)-5)
			break
		}
		fmt.Printf("  - %s\n", link)
	}
}

재사용 가능한 클라이언트 패키지

더 깔끔한 코드를 위해 재사용 가능한 Ollama 클라이언트 패키지를 생성하세요:

// ollama/client.go
package ollama

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

type Client struct {
	apiKey     string
	httpClient *http.Client
	baseURL    string
}

func NewClient() (*Client, error) {
	apiKey := os.Getenv("OLLAMA_API_KEY")
	if apiKey == "" {
		return nil, fmt.Errorf("OLLAMA_API_KEY 환경 변수가 설정되지 않았습니다.")
	}

	return &Client{
		apiKey: apiKey,
		httpClient: &http.Client{
			Timeout: 30 * time.Second,
		},
		baseURL: "https://ollama.com/api",
	}, nil
}

type SearchResult struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Content string `json:"content"`
}

type SearchResponse struct {
	Results []SearchResult `json:"results"`
}

type FetchResponse struct {
	Title   string   `json:"title"`
	Content string   `json:"content"`
	Links   []string `json:"links"`
}

func (c *Client) WebSearch(query string, maxResults int) (*SearchResponse, error) {
	payload := map[string]interface{}{
		"query":       query,
		"max_results": maxResults,
	}
	return doRequest[SearchResponse](c, "/web_search", payload)
}

func (c *Client) WebFetch(url string) (*FetchResponse, error) {
	payload := map[string]string{"url": url}
	return doRequest[Fetch端](c, "/web_fetch", payload)
}

func doRequest[T any](c *Client, endpoint string, payload interface{}) (*T, error) {
	jsonData, err := json.Marshal(payload)
	if err != nil {
		return nil, err
	}

	req, err := http.NewRequest("POST", c.baseURL+endpoint, bytes.NewBuffer(jsonData))
	if err != nil {
		return nil, err
	}

	req.Header.Set("Authorization", "Bearer "+c.apiKey)
	req.Header.Set("Content-Type", "application/json")

	resp, err := c.httpClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, err
	}

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("API 오류 (상태 %d): %s", resp.StatusCode, string(body))
	}

	var result T
	if err := json.Unmarshal(body, &result); err != nil {
		return nil, err
	}

	return &result, nil
}

사용 예시:

package main

import (
	"fmt"
	"log"
	"ollama-search/ollama"
)

func main() {
	client, err := ollama.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	// 검색
	results, err := client.WebSearch("Ollama 새로운 기능", 5)
	if err != nil {
		log.Fatal(err)
	}

	for _, r := range results.Results {
		fmt.Printf("- %s\n  %s\n\n", r.Title, r.URL)
	}

	// 가져오기
	page, err := client.WebFetch("https://ollama.com")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("페이지: %s\n", page.Title)
}

검색 에이전트 구축

Go 기반 Ollama 검색 에이전트에 적합한 모델은 무엇인가요? 강력한 도구 사용 기능을 갖춘 모델이 가장 적합합니다. qwen3, gpt-oss, 그리고 클라우드 모델인 qwen3:480b-cloud 및 deepseek-v3.1-cloud가 있습니다. Qwen3 모델과 함께 작업 중이고 검색 결과를 처리하거나 재정렬하려면, Ollama와 Qwen3 임베딩 모델을 사용하여 텍스트 문서 재정렬하기에 있는 가이드를 참조하세요.

완전한 검색 에이전트 구현 예시:

package main

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

// 채팅 타입
type Message struct {
	Role      string     `json:"role"`
	Content   string     `json:"content,omitempty"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	ToolName  string     `json:"tool_name,omitempty"`
}

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

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

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

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

type ChatRequest struct {
	Model    string    `json:"model"`
	Messages []Message `json:"messages"`
	Tools    []Tool    `json:"tools,omitempty"`
	Stream   bool      `json:"stream"`
}

type ChatResponse struct {
	Message Message `json:"message"`
}

// 검색 에이전트는 웹 검색과 LLM을 조절합니다
type SearchAgent struct {
	model      string
	ollamaURL  string
	apiKey     string
	maxIter    int
	httpClient *http.Client
}

func NewSearchAgent(model string) *SearchAgent {
	return &SearchAgent{
		model:      model,
		ollamaURL:  "http://localhost:11434/api/chat",
		apiKey:     os.Getenv("OLLAMA_API_KEY"),
		maxIter:    10,
		httpClient: &http.Client{},
	}
}

func (a *SearchAgent) Query(question string) (string, error) {
	tools := []Tool{
		{
			Type: "function",
			Function: ToolFunction{
				Name:        "web_search",
				Description: "현재 정보를 위해 웹을 검색합니다",
				Parameters: map[string]interface{}{
					"type": "object",
					"properties": map[string]interface{}{
						"query": map[string]string{
							"type":        "string",
							"description": "검색 쿼리",
						},
					},
					"required": []string{"query"},
				},
			},
		},
		{
			Type: "function",
			Function: ToolFunction{
				Name:        "web_fetch",
				Description: "웹 페이지의 전체 내용을 가져옵니다",
				Parameters: map[string]interface{}{
					"type": "object",
					"properties": map[string]interface{}{
						"url": map[string]string{
							"type":        "string",
							"description": "가져올 URL",
						},
					},
					"required": []string{"url"},
				},
			},
		},
	}

	messages := []Message{
		{Role: "user", Content: question},
	}

	for i := 0; i < a.maxIter; i++ {
		response, err := a.chat(messages, tools)
		if err != nil {
			return "", fmt.Errorf("채팅 오류: %w", err)
		}

		messages = append(messages, response.Message)

		// 도구 호출이 없으면 최종 답변입니다
		if len(response.Message.ToolCalls) == 0 {
			return response.Message.Content, nil
		}

		// 도구 호출 실행
		for _, toolCall := range response.Message.ToolCalls {
			fmt.Printf("🔧 호출: %s\n", toolCall.Function.Name)

			result, err := a.executeTool(toolCall)
			if err != nil {
				result = fmt.Sprintf("오류: %v", err)
			}

			// 맥락 한도를 위해 결과 잘라내기
			if len(result) > 8000 {
				result = result[:8000] + "... [잘림]"
			}

			messages = append(messages, Message{
				Role:     "tool",
				Content:  result,
				ToolName: toolCall.Function.Name,
			})
		}
	}

	return "", fmt.Errorf("최대 반복 횟수에 도달했습니다")
}

func (a *SearchAgent) chat(messages []Message, tools []Tool) (*ChatResponse, error) {
	reqBody := ChatRequest{
		Model:    a.model,
		Messages: messages,
		Tools:    tools,
		Stream:   false,
	}

	jsonData, _ := json.Marshal(reqBody)

	resp, err := a.httpClient.Post(a.ollamaURL, "application/json", bytes.NewBuffer(jsonData))
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)

	var chatResp ChatResponse
	if err := json.Unmarshal(body, &chatResp); err != nil {
		return nil, err
	}

	return &chatResp, nil
}

func (a *SearchAgent) executeTool(toolCall ToolCall) (string, error) {
	switch toolCall.Function.Name {
	case "web_search":
		query, ok := toolCall.Function.Arguments["query"].(string)
		if !ok {
			return "", fmt.Errorf("잘못된 쿼리 인수")
		}
		return a.webSearch(query)

	case "web_fetch":
		url, ok := toolCall.Function.Arguments["url"].(string)
		if !ok {
			return "", fmt.Errorf("잘못된 URL 인수")
		}
		return a.webFetch(url)

	default:
		return "", fmt.Errorf("알 수 없는 도구: %s", toolCall.Function.Name)
	}
}

func (a *SearchAgent) webSearch(query string) (string, error) {
	payload := map[string]interface{}{"query": query, "max_results": 5}
	jsonData, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://ollama.com/api/web_search", bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer "+a.apiKey)
	req.Header.Set("Content-Type", "application/json")

	resp, err := a.httpClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	return string(body), nil
}

func (a *SearchAgent) webFetch(url string) (string, error) {
	payload := map[string]string{"url": url}
	jsonData, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://ollama.com/api/web_fetch", bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer "+a.apiKey)
	req.Header.Set("Content-Type", "application/json")

	resp, err := a.httpClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	return string(body), nil
}

func main() {
	agent := NewSearchAgent("qwen3:4b")

	answer, err := agent.Query("Ollama의 최신 기능은 무엇인가요?")
	if err != nil {
		fmt.Printf("오류: %v\n", err)
		return
	}

	fmt.Println("\n📝 답변:")
	fmt.Println(answer)
}

Go에서 대규모 웹 검색 응답을 처리하려면 어떻게 하나요? 모델 맥락에 전달하기 전에 응답 내용을 잘라내세요. 문자열 슬라이싱을 사용하여 맥락 한도 내에서 내용을 약 8000자로 제한하세요.

병렬 검색

Go는 병렬 작업에 탁월합니다. 여러 검색을 병렬로 수행하는 방법은 다음과 같습니다. Ollama가 병렬 요청을 어떻게 처리하는지를 이해하면 병렬 검색 구현을 최적화하는 데 도움이 됩니다.

package main

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

type SearchResult struct {
	Query   string
	Results []struct {
		Title   string `json:"title"`
		URL     string `json:"url"`
		Content string `json:"content"`
	} `json:"results"`
	Error error
}

func concurrentSearch(queries []string) []SearchResult {
	results := make([]SearchResult, len(queries))
	var wg sync.WaitGroup

	for i, query := range queries {
		wg.Add(1)
		go func(idx int, q string) {
			defer wg.Done()

			result := SearchResult{Query: q}

			payload := map[string]string{"query": q}
			jsonData, _ := json.Marshal(payload)

			req, _ := http.NewRequest("POST", "https://ollama.com/api/web_search", bytes.NewBuffer(jsonData))
			req.Header.Set("Authorization", "Bearer "+os.Getenv("OLLAMA_API_KEY"))
			req.Header.Set("Content-Type", "application/json")

			resp, err := http.DefaultClient.Do(req)
			if err != nil {
				result.Error = err
				results[idx] = result
				return
			}
			defer resp.Body.Close()

			body, _ := io.ReadAll(resp.Body)
			json.Unmarshal(body, &result)
			results[idx] = result
		}(i, query)
	}

	wg.Wait()
	return results
}

func main() {
	queries := []string{
		"Ollama 최신 기능",
		"로컬 LLM 배포",
		"AI 검색 에이전트 Go",
	}

	results := concurrentSearch(queries)

	for _, r := range results {
		fmt.Printf("\n🔍 쿼리: %s\n", r.Query)
		if r.Error != nil {
			fmt.Printf("   오류: %v\n", r.Error)
			continue
		}
		for _, item := range r.Results[:min(3, len(r.Results))] {
			fmt.Printf("   • %s\n", item.Title)
		}
	}
}

func min(a, b int) int {
	if a < b {
		return a
	}
	return b
}

맥락 및 취소

타임아웃 및 취소를 위해 맥락 지원을 추가하세요:

package main

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

func webSearchWithContext(ctx context.Context, query string) (string, error) {
	payload := map[string]string{"query": query}
	jsonData, _ := json.Marshal(payload)

	req, err := http.NewRequestWithContext(ctx, "POST", "https://ollama.com/api/web_search", bytes.NewBuffer(jsonData))
	if err != nil {
		return "", err
	}

	req.Header.Set("Authorization", "Bearer "+os.Getenv("OLLAMA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}

	return string(body), nil
}

func main() {
	// 10초 타임아웃으로 맥락 생성
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	result, err := webSearchWithContext(ctx, "Ollama 웹 검색 API")
	if err != nil {
		if ctx.Err() == context.DeadlineExceeded {
			fmt.Println("요청 시간 초과")
		} else {
			fmt.Printf("오류: %v\n", err)
		}
		return
	}

	fmt.Println(result)
}

추천 모델

Go 검색 에이전트에 사용해야 할 맥락 길이는 무엇인가요? 약 32000 토큰의 맥락 길이를 설정하세요. 웹 검색 결과가 광범위할 수 있으므로, 검색 에이전트는 전체 맥락 길이를 사용하는 것이 가장 좋습니다. Ollama 모델을 관리하거나 다른 위치로 이동하려면, Ollama 모델을 다른 드라이브 또는 폴더로 이동하는 방법을 참조하세요.

모델 파라미터 최적 사용
qwen3:4b 4B 빠른 로컬 검색
qwen3 8B 일반 목적 에이전트
gpt-oss 다양한 연구 작업
qwen3:480b-cloud 480B 복잡한 추론 (클라우드)
gpt-oss:120b-cloud 120B 긴 형식 연구 (클라우드)
deepseek-v3.1-cloud - 고급 분석 (클라우드)

텍스트와 시각 콘텐츠를 결합한 고급 AI 애플리케이션을 고려하는 경우, 크로스 모달 임베딩을 탐구하여 텍스트만이 아닌 쿼리에도 검색 기능을 확장하세요.

최선의 실천 방법

  1. 오류 처리: 항상 오류를 확인하고 API 실패를 부드럽게 처리하세요
  2. 타임아웃: 네트워크 요청에 타임아웃을 사용하세요
  3. 레이트 제한: Ollama의 API 레이트 제한을 존중하세요. Ollama의 API 변경 가능성에 대해 Ollama Enshittification의 첫 징후를 참조하세요
  4. 결과 잘라내기: 약 8000자로 결과를 잘라내어 맥락 한도를 준수하세요
  5. 병렬 요청: 병렬 검색을 위해 goroutines을 사용하세요
  6. 연결 재사용: 더 나은 성능을 위해 HTTP 클라이언트를 재사용하세요
  7. 테스트: 검색 구현에 대한 포괄적인 단위 테스트를 작성하세요. Go 단위 테스트 최선의 실천 방법을 따르면 코드가 견고하고 유지보수가 가능해집니다.

유용한 링크