# 用 Go + Ollama 构建本地离线 RAG 知识库系统

## 背景

大模型应用开发中，RAG（Retrieval-Augmented Generation，检索增强生成）已成为最主流的知识增强方案。但云端 API 调用存在成本、隐私、稳定性等问题。本文将介绍如何用 Go 语言 + Ollama 本地模型，构建一个完全离线运行的 RAG 知识库问答系统。

## 项目概述

本项目基于 Go 语言实现，核心特性：

- ✅ **完全离线运行** - 断网状态仍可正常问答

- ✅ **本地模型适配** - 支持 Ollama、OpenAI、DeepSeek 多后端

- ✅ **文档自动切片** - Markdown 按标题层级智能切分

- ✅ **多轮对话** - Session 上下文记忆管理

- ✅ **配置化设计** - 一个配置文件切换所有参数

## 技术架构

```

┌─────────────────────────────────────────────┐

│                   HTTP API                   │

│                   (Gin 框架)                  │

└─────────────────────────────────────────────┘

                      │

        ┌─────────────┼─────────────┐

        ▼             ▼             ▼

   文档服务       RAG 服务      会话管理

        │             │             │

        ▼             ▼             ▼

   文本切片       向量检索      SQLite

   (Markdown)    (Memory/         历史存储

                 Milvus)

        │             │

        ▼             ▼

┌──────────────┐  ┌──────────────┐

│   Embedding  │  │      LLM     │

│   (Ollama)   │  │   (Ollama)   │

│nomic-embed   │  │ qwen2.5:7b   │

│    -text     │  │              │

└──────────────┘  └──────────────┘

```

## 核心模块实现

### 1. 配置化管理

通过 TOML 配置文件管理所有参数，支持一键切换模型后端：

```toml

# config.toml

[vector]

type = "memory"           # 可切换为 milvus

dim = 768                 # nomic-embed-text 向量维度

[embedding]

provider = "ollama"       # 可切换为 openai、deepseek

model = "nomic-embed-text"

[llm]

provider = "ollama"

model = "qwen2.5:7b"

[rag]

topk = 5                  # 检索文档数量

min_score = 0.6           # 最小相似度阈值

```

配置解析核心代码：

```go

func LoadConfig(path string) (*Config, error) {

    data, err := os.ReadFile(path)

    if err != nil {

        return nil, err

    }

    cfg := &Config{

        Server:   ServerConfig{Host: "localhost", Port: 8080},

        Embedding: EmbeddingConfig{Provider: "ollama", Model: "nomic-embed-text"},

        LLM:      LLMConfig{Provider: "ollama", Model: "qwen2.5:7b"},

    }

    // TOML section 解析

    lines := strings.Split(string(data), "\n")

    currentSection := ""

    for _, line := range lines {

        if strings.HasPrefix(line, "[") && strings.HasSuffix(line, "]") {

            currentSection = line[1:len(line)-1]

            continue

        }

        // ... 解析 key=value

    }

    return cfg, nil

}

```

### 2. 本地 Embedding 实现

Ollama 提供了原生 Embedding API，无需 OpenAI Key：

```go

func (c *Client) ollamaEmbeddings(ctx context.Context, texts []string) ([][]float32, error) {

    baseURL := "http://localhost:11434"

    vectors := make([][]float32, 0, len(texts))

    for _, text := range texts {

        reqBody := map[string]interface{}{

            "model": c.config.Model,  // nomic-embed-text

            "input": text,

        }

        reqBytes, _ := json.Marshal(reqBody)

        // Ollama embed API

        resp, err := http.Post(baseURL+"/api/embed", "application/json", bytes.NewReader(reqBytes))

        if err != nil {

            return nil, err

        }

        var result struct {

            Embeddings [][]float32 `json:"embeddings"`

        }

        json.NewDecoder(resp.Body).Decode(&result)

        vectors = append(vectors, result.Embeddings[0])

    }

    return vectors, nil

}

```

**关键点**：

- 使用 Ollama 新版 `/api/embed` 接口

- nomic-embed-text 生成 768 维向量

- 支持批量处理提升效率

### 3. 统一 LLM 客户端接口

设计统一的 `Client` 接口，支持多后端切换：

```go

type Client interface {

    Chat(ctx context.Context, messages []Message) (string, error)

    ChatStream(ctx context.Context, messages []Message, callback func(string)) error

    GetModel() string

}

// Ollama 实现

type OllamaClient struct {

    model   string

    baseURL string

}

func (c *OllamaClient) Chat(ctx context.Context, messages []Message) (string, error) {

    reqBody := map[string]interface{}{

        "model":    c.model,

        "messages": messages,

        "stream":   false,

    }

    resp, err := http.Post(c.baseURL+"/api/chat", "application/json", bytes.NewReader(reqBytes))

    // ... 解析响应

    return result.Message.Content, nil

}

// OpenAI/DeepSeek 兼容实现

type OpenAIClient struct {

    model   string

    apiKey  string

    baseURL string

}

```

### 4. Markdown 文档切片器

按标题层级智能切分，保留文档结构：

```go

type MarkdownSplitter struct{}

func (s *MarkdownSplitter) Split(text string) []Chunk {

    chunks := make([]Chunk, 0)

    headingRegex := regexp.MustCompile(`^(#{1,6})\s+(.+)`)

    var currentContent strings.Builder

    var currentHeading string

    for _, line := range strings.Split(text, "\n") {

        if match := headingRegex.FindStringSubmatch(line); match != nil {

            // 遇到新标题，保存上一个切片

            if currentContent.Len() > 0 {

                chunks = append(chunks, Chunk{

                    Content: currentContent.String(),

                    Metadata: map[string]interface{}{

                        "heading": currentHeading,

                    },

                })

            }

            currentContent.Reset()

            currentHeading = match[2]

        } else {

            currentContent.WriteString(line + "\n")

        }

    }

    return chunks

}

```

### 5. 多轮对话上下文管理

基于 Session ID + SQLite 存储历史消息：

```go

func (s *RAGService) Ask(req *AskRequest) (*AskResponse, error) {

    // 1. 获取或创建会话

    sessionID := req.SessionID

    if sessionID == "" {

        sessionID = fmt.Sprintf("session_%d", time.Now().UnixNano())

    }

    // 2. 获取历史消息（限制最近 10 条）

    history, _ := s.repo.GetChatHistory(sessionID)

    messages := make([]llm.Message, 0)

    startIdx := 0

    if len(history) > 10 {

        startIdx = len(history) - 10

    }

    for _, msg := range history[startIdx:] {

        messages = append(messages, llm.Message{

            Role:    msg.Role,

            Content: msg.Content,

        })

    }

    // 3. 添加当前问题

    messages = append(messages, llm.Message{

        Role:    "user",

        Content: req.Question,

    })

    // 4. 调用 LLM

    answer, _ := s.llmClient.Chat(ctx, messages)

    // 5. 保存对话记录

    s.repo.CreateMessage(&ChatMessage{

        SessionID: sessionID,

        Role:      "user",

        Content:   req.Question,

    })

    s.repo.CreateMessage(&ChatMessage{

        SessionID: sessionID,

        Role:      "assistant",

        Content:   answer,

    })

    return &AskResponse{

        SessionID: sessionID,

        Answer:    answer,

    }, nil

}

```

## 部署与测试

### 前置条件

```bash

# 1. 安装 Ollama

winget install Ollama.Ollama

# 2. 拉取模型

ollama pull nomic-embed-text  # Embedding 模型（274MB）

ollama pull qwen2.5:7b        # LLM 模型（4.7GB）

```

### 启动服务

```bash

cd cmd/rag

go build -o rag-server.exe .

./rag-server.exe

```

### 测试流程

```bash

# 1. 健康检查

curl http://localhost:8080/api/v1/health

# 2. 上传文档

curl -X POST http://localhost:8080/api/v1/documents/upload \

  -F "file=@test.md"

# 3. 单轮问答

curl -X POST http://localhost:8080/api/v1/chat/ask \

  -H "Content-Type: application/json" \

  -d '{"question": "Go语言的特性有哪些？"}'

# 4. 多轮追问（使用返回的 session_id）

curl -X POST http://localhost:8080/api/v1/chat/ask \

  -H "Content-Type: application/json" \

  -d '{"session_id": "session_xxx", "question": "详细说说并发性"}'

```

## 测试结果

| 功能 | 状态 | 说明 |

|------|------|------|

| 文档切片 | ✅ | Markdown 9 个切片成功入库 |

| 向量化 | ✅ | 768 维向量生成正常 |

| RAG 检索 | ✅ | Top-5 文档召回准确 |

| LLM 回答 | ✅ | Qwen2.5:7b 响应正常 |

| 多轮对话 | ✅ | 上下文传递正确 |

| 离线运行 | ✅ | 断网状态仍可问答 |

## 遇到的问题与解决

### 问题 1: Embedding URL 拼接错误

**错误**：`ollama request failed: 404`

**原因**：OpenAI 兼容接口配置了 `/v1` 前缀，但 Ollama 原生 API 是 `/api/embed`

**解决**：在 `ollamaEmbeddings` 方法中正确处理 baseURL：

```go

baseURL := "http://localhost:11434"

if c.config.BaseURL != "" {

    baseURL = strings.TrimSuffix(c.config.BaseURL, "/v1")

}

```

### 问题 2: TOML 配置解析失败

**错误**：配置值包含注释内容，如 `ollama"       # 可选...`

**原因**：解析器未处理 `#` 注释

**解决**：添加注释处理逻辑：

```go

value := strings.TrimSpace(parts[1])

if idx := strings.Index(value, "#"); idx != -1 {

    value = strings.TrimSpace(value[:idx])

}

```

### 问题 3: 向量维度不匹配

**错误**：`vector dim 0 not match collection definition`

**原因**：Embedding 返回空向量，因 baseURL 配置问题

**解决**：统一 Embedding 和 LLM 客户端的 baseURL 处理逻辑

## 下一步优化

1. **流式输出** - 添加 SSE 接口 `/api/v1/chat/stream`

2. **Milvus 集成** - 替换内存存储，支持大规模数据

3. **更多文档格式** - 支持 PDF、Word 解析

4. **混合检索** - BM25 + 向量混合检索

5. **Web UI** - 添加前端界面

## 项目地址

GitHub: https://github.com/Blue-wu/golllm

分支: `feature/local-model`

---

**总结**：通过本项目，实现了完全离线的 RAG 知识库系统。核心在于：

1. Ollama 本地模型替代云端 API

2. 统一客户端接口设计实现多后端切换

3. 配置化管理降低维护成本

这为后续的私有化部署、敏感数据处理、成本控制等场景提供了可行的技术方案。