如何在 Win 上配置 Agent 开发常见环境

本文记录在 Windows 上配置 GopherPaper 本地开发环境的过程。需要准备四类内容：

  • 语言运行：Go（编译跑后端）
  • 容器：Docker Desktop（一键起 MySQL / Redis / RabbitMQ / Milvus）
  • 四个密钥：火山方舟大模型 API key、MinerU 解析 token、网易邮箱 SMTP 授权码、硅基流动的 API key
盯 先确认运行时、容器、模型和密钥四件事，后面基本就是按步骤检查。

1. 安装 Go

到官网 go.dev/dl 下载 Windows 安装包，认准 goX.Y.Z.windows-amd64.msi。项目要求 Go 1.26 及以上（go.mod 写的是 go 1.26.3），别装太旧的版本。

截止 2026 年 6 月 9 日

下载链接是有效的

双击 .msi 安装即可，安装器会自动把 Go 加入 PATH。安装完成后，重新打开 PowerShell 验证：

go version

看到 go version go1.26.x windows/amd64 就对了。

国内拉依赖慢的话，配一下模块代理（一次就够，全局生效）：

go env -w GOPROXY=https://goproxy.cn,direct

强烈建议开启喵喵工具的虚拟网卡或者TUN模式，方便在终端使用，镜像还是不方便，下文的docker、ollama拉取模型和go的依赖(类似于Java中的Maven)下载时都默认你在国外。

2. 安装 Docker Desktop

后端依赖 MySQL、Redis、RabbitMQ、Milvus 等中间件，统一通过 Docker Compose 启动。

如果你已经有有了WSL，直接跳转到安装docker即可，不需要执行下面的命令。

Windows 上的 Docker Desktop 推荐使用 WSL2。先用管理员身份打开 PowerShell，执行：

wsl --install

这条命令会自动开启所需的 Windows 功能并装上一个 Ubuntu 子系统，装完重启电脑。

然后到 docker.com/products/docker-desktop 下载 Docker Desktop 安装包，安装时勾选 Use WSL 2 instead of Hyper-V。装完启动 Docker Desktop，等右下角小鲸鱼图标不再转圈，验证：

docker version
docker compose version

两条都能打印出版本号，说明容器环境就绪了。

3. 拉起基础设施

进入项目目录，使用仓库内的 Compose 编排启动基础设施：

docker compose -f deploy/docker-compose.yml up -d

该命令会启动 MySQL / Redis / RabbitMQ / Milvus（含 etcd、MinIO）以及 Milvus 可视化界面 Attu。第一次拉取镜像耗时较长，等待容器启动完成后访问：

  • Milvus 可视化 Attu：http://localhost:8000
  • RabbitMQ 管理台：http://localhost:15672（账号密码都是 gopher）
  • Navicat 或者其他数据库的连接软件想要连接MySQL数据库的话，账号和密码都是root

用 docker ps 看一眼，所有容器状态是 Up / healthy 就没问题。

attu 的初始化启动时间较长是正常的，等待即可。

加油 第一次拉镜像慢是正常的，等容器健康后再继续启动后端。

4. 安装 Ollama（可以暂时不安装）

目前的 GopherPaper 的本地轻量化翻译功能还在测试，而且我们的embedding模型和reranker模型都没有再使用 Ollama 了，可以不用安装。

你可以选择直接跳到第5步骤。

RAG 检索需要把文本向量化，这里使用本地 Ollama 运行 bge-m3 模型。

到 ollama.com/download 下载 Windows 版安装包，装完它会常驻后台（任务栏有个羊驼图标）。然后在 PowerShell 拉模型：

ollama pull bge-m3

bge-m3 大概 1～2 GB，拉完验证服务在跑：

ollama list

能看到 bge-m3 这一行就行。Ollama 默认监听 http://localhost:11434，正好对上配置里的 [embedding].base_url。

5. 拿四个密钥

项目需要三个外部服务凭据，分别是大模型 API key、MinerU token 和邮箱 SMTP 授权码。

5.1 大模型 API key

项目对话模型直连火山方舟（火山引擎），走 OpenAI 兼容端点。到 火山方舟控制台 开通服务，在「API Key 管理」页面新建一个 API Key 并复制保存，base_url 固定为 https://ark.cn-beijing.volces.com/api/v3。意图模型和下游问答模型可以共用同一个 key，也可以分别配置不同模型。

火山方舟默认用模型 ID（如 doubao-seed-2-0-pro-260215）直接调用，无需自行创建推理接入点。项目默认配置：

  • 意图路由小模型用 doubao-seed-2-0-mini-260215（小杯、延迟低）
  • 下游问答 / 抽取 / 报告用 doubao-seed-2-0-pro-260215（pro 主力）

注意：对话模型必须是多模态模型，因为 RAG 的召回会把图片一起发给它。doubao-seed-2.0-pro 本身支持图文，直接用即可；不要换成纯文本模型（如 DeepSeek），否则带图召回会出问题。

5.2 MinerU 解析 token

PDF 解析走 MinerU 在线 API。

  1. 到 mineru.net 注册并登录
  2. 点击在线使用在线使用
  3. 进个人中心，找到 API / 申请 API 使用（开放平台页面）
  4. 进入开发者API申请界面开发者申请，然后创建TOKEN
  5. 申请通过后会给你一个 API Token，复制下来

这个 token 填到配置的 [parser].token，base_url 保持默认的 https://mineru.net/api/v4 即可。

5.3 网易邮箱 SMTP 授权码

注意：这里要的不是邮箱登录密码，而是一串单独的「客户端授权码」。以 163 邮箱为例：

  1. 浏览器登录 mail.163.com
  2. 顶部进入 设置 → POP3/SMTP/IMAP
  3. 开启 SMTP 服务（和 IMAP/POP3 一起开）
  4. 按提示用手机发一条短信做验证
  5. 验证通过后弹出的那串字符，就是 授权码，只显示一次，立刻复制保存

网易云邮箱

对应配置里的 [mail]：

  • smtp_host = smtp.163.com
  • smtp_port = 465（SSL 端口）
  • server_mail = 你的 163 邮箱地址
  • key = 刚拿到的授权码

如果用的是 126 邮箱就把 host 换成 smtp.126.com，QQ 邮箱同理换成 smtp.qq.com，流程都是「开服务 → 拿授权码」。

5.4 配置 embedding 和 reranker 模型

点击硅基流动的中国官方网站硅基流动

点击 API 密钥硅基流动API

复制保存即可。

我们的模型使用为Qwen/Qwen3-Reranker-4B和Qwen/Qwen3-Embedding-0.6B

6. 写配置文件

项目使用 TOML 配置。先从示例文件复制一份本地配置：

copy config\config.example.toml config\config.toml

config.toml 已被 gitignore，不会误提交。然后打开 config\config.toml，填写前面获取的密钥。关键配置如下：

[models.intent]      # 意图路由小模型：火山方舟
provider = "openai"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
api_key = "你的火山方舟-api-key"
model = "doubao-seed-2-0-mini-260215"
 
[models.chat]        # 下游问答/抽取/报告大模型：火山方舟
provider = "openai"
base_url = "https://ark.cn-beijing.volces.com/api/v3"
api_key = "你的火山方舟-api-key"
model = "doubao-seed-2-0-pro-260215"
 
[parser]             # MinerU
token = "你申请到的-mineru-token"
 
[mail]               # 网易 SMTP
smtp_host = "smtp.163.com"
smtp_port = 465
server_mail = "你的邮箱@163.com"
key = "网易授权码"

火山方舟是 OpenAI 兼容端点，provider 仍写 openai，base_url 指向 https://ark.cn-beijing.volces.com/api/v3，api_key 用火山方舟控制台拿到的那把。[models.vlm] / [models.pioneer] 同样指向火山方舟，照搬示例配置即可。

[embedding] / [rerank] 指向硅基流动（第 5.4 步的 key），[mysql] / [redis] / [mq] / [milvus] 保持默认即可，它们对应第 3 步启动的本地容器。

7. 小云雀 Agent 工具清单

7.1 联网搜索能力

我们使用tavily的免费搜索额度的服务：tavily

8. 跑起来

新建一个终端，进入项目文件夹，进入web文件夹

整体的流程步骤，先启动docker，把compose跑起来，然后进入web文件夹编译前端

npm run build

然后回到主文件夹

go run ./cmd/server

然后访问127.0.0.1:8080即可。

第一次启动会自动下载 Go 依赖并建表（AutoMigrate）。看到服务监听 :8080 且没有报错，说明后端启动成功。

完整流程可以按以下顺序验证：

  1. 注册账号，确认邮箱验证码可以正常发送
  2. 上传一篇 PDF
  3. 查看解析状态是否从 parsing 推进到 ready
  4. 打开 RabbitMQ 管理台和 Attu，确认消息与向量数据是否正常写入

验证清单

配置完成后检查：

  • go version 是 1.26+
  • docker ps 里 MySQL / Redis / RabbitMQ / Milvus 全是 Up
  • ollama list 里有 bge-m3
  • config\config.toml 里三个密钥都填了，没有残留 xxxx
  • go run ./cmd/server 启动无报错，监听 :8080
  • 注册能收到验证码邮件，上传 PDF 能解析到 ready
自豪 清单全部通过后，Windows 本地开发环境就配置完成了。