企业官网建设流程全解析

1. 本地 RAG 系统为什么总在“评测”这一步卡住

很多人第一次接触 DeepSeek R1 本地部署，路径都差不多：装 Ollama、拉模型、命令行里聊两句，感觉挺顺。可一旦要把“本地知识库问答”做成能持续迭代的东西，问题就来了——回答到底准不准？检索出来的片段有没有用？换个 chunk 大小、换个 embedding 模型，效果是变好还是变差？没有量化评测，这些全靠感觉，优化就变成了玄学。

RAG（Retrieval-Augmented Generation，检索增强生成）的核心链路其实就四步：检索准备、文档检索、结果精炼、答案生成。搭建本身不难，难的是让每个环节都可衡量。XRAG 这个框架的价值就在这儿：它把 RAG 拆成可对比的模块，提供 50 多个测试指标，支持查询重构、先进检索、问答模型、后处理四类 Advanced RAG 模块的横向对比，还能做失败点检测。配合本地 Ollama 跑的 DeepSeek R1，整条链路可以完全离线，数据不出本机。

这篇面向想入门大模型应用开发、又不想一上来就烧 API 额度的读者。我会给出可复制的 Ollama 拉取命令、XRAG 的 config.toml 配置片段、三步搭建流程，以及一个自动化评测脚本的验证动作。全程在本地环境跑通，不需要 GPU 集群，一台 16GB 内存的笔记本就能起步。如果你之前只会在网页端跟模型聊天，跟着走完能拿到一个能自己喂文档、自己打分、自己看指标的小系统。

先说清楚适合谁：有基本 Python 环境操作经验、能看懂命令行输出、愿意花半小时装环境的人。完全没碰过终端也没关系，命令我都写全了。不适合谁：想直接上生产、要处理千万级文档、要求毫秒级响应的场景——那是另一套工程，本文聚焦的是“本地跑通 + 可评测”这个入门到进阶的过渡阶段。

2. 前置准备：Ollama 拉取 DeepSeek R1 与 XRAG 环境搭建

2.1 Ollama 安装与 DeepSeek R1 模型拉取

Ollama 是个开源工具，让你在本地机器上跑 LLM。去官网 https://ollama.com 下载对应系统的安装包，Windows 和 macOS 都有图形化安装程序，Linux 用一条脚本。装完之后，先确认服务状态：

ollama serve

如果之前已经启动过，这条命令会报address already in use，说明服务在跑，不用重复启动。想确认版本：

ollama --version

接下来拉 DeepSeek R1。模型库里有多个参数量版本，本地入门建议从最小的开始：

ollama pull deepseek-r1:1.5b

资源充足的话可以换deepseek-r1:7b或deepseek-r1:8b，参数量越大回答质量越好，但对内存要求也越高。1.5b 版本在 8GB 内存机器上就能跑，7b 建议 16GB 以上。拉取完成后直接对话测试：

ollama run deepseek-r1:1.5b

输入一句“用一句话解释什么是 RAG”，能正常返回就说明模型就位。退出用/bye。这里有个细节：Ollama 默认监听127.0.0.1:11434，只允许本机访问。如果你后续要让 XRAG 通过 HTTP 调用，保持默认即可，不要改成0.0.0.0暴露到公网——这一点后面排障章节会展开。

2.2 XRAG 安装与虚拟环境

XRAG 要求 Python 3.11 或更高。用 conda 建一个干净环境，避免和系统包冲突：

conda create -n xrag python=3.11 -y conda activate xrag

然后从 GitHub 拉源码安装。XRAG 的仓库地址是 https://github.com/DocAILab/XRAG，论文在 https://arxiv.org/abs/2412.15529。安装方式：

git clone https://github.com/DocAILab/XRAG.git cd XRAG pip install -e .

-e是可编辑安装，方便你后面改配置。装完验证一下：

python -c "import xrag; print(xrag.__version__)"

能打印版本号就说明依赖都齐了。如果卡在某个包编译失败，大概率是缺少系统级依赖，Linux 下补build-essential，macOS 下补 Xcode Command Line Tools。

2.3 模型与框架的对接思路

Ollama 对外提供的是 OpenAI 兼容接口，地址是http://localhost:11434/v1。XRAG 支持 OpenAI 格式的 API，所以只要把 base_url 指向本地 Ollama，把 model 名字写成deepseek-r1:1.5b，就能让 XRAG 用上本地模型。这里不需要任何 API Key，随便填一个占位符即可。理解这一点很关键：本地部署的“钥匙”不是密钥，而是正确的 endpoint 和模型名。

如果你后续想把这套配置迁移到云端做对比评测，或者团队里有人用托管服务，可以了解下 TaoToken 的接入方式，它的 API 地址是 https://taotoken.net/api，模型对话入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。本地和云端用同一套 OpenAI 兼容格式，切换成本很低。

3. 可复制配置：XRAG 的 config.toml 与本地模型对接

3.1 config.toml 关键字段说明

XRAG 用config.toml管理配置。默认配置能跑，但要用本地模型必须改几个字段。下面是一份可直接复制的片段，路径放在项目根目录的config.toml：

[llm] provider = "openai" model = "deepseek-r1:1.5b" base_url = "http://localhost:11434/v1" api_key = "ollama" [embedding] provider = "openai" model = "nomic-embed-text" base_url = "http://localhost:11434/v1" api_key = "ollama" [retrieval] top_k = 5 chunk_size = 512 chunk_overlap = 64 [evaluation] metrics = ["faithfulness", "answer_relevancy", "context_precision", "context_recall"]

逐段解释。[llm]段是答案生成用的模型，provider写openai是因为 Ollama 兼容这个协议，base_url指向本地 11434 端口，api_key随便填，Ollama 不校验。[embedding]段是向量化用的模型，需要单独拉一个 embedding 模型：

ollama pull nomic-embed-text

[retrieval]段控制检索行为，top_k是每次召回片段数，chunk_size是文档切块大小，chunk_overlap是块间重叠字符数。这三个参数是 RAG 调优最常动的地方，先按默认跑通，后面再对比。[evaluation]段列出要算的指标，XRAG 支持 50 多个，这里先选四个最经典的。

3.2 用可视化界面覆盖配置

XRAG 1.0 提供了 Web UI，可以在界面上直接改配置，不用手写 toml。启动方式：

xrag ui

默认会在http://localhost:7860起一个页面。打开后能看到数据上传、配置选择、评测运行三个区域。在配置区把 LLM 和 Embedding 的 base_url 都填http://localhost:11434/v1，模型名分别填deepseek-r1:1.5b和nomic-embed-text。界面上的改动会覆盖 config.toml 里的对应字段，适合快速试参数。

3.3 知识库数据格式

XRAG 对上传数据有统一格式要求，一般是 JSON 或 JSONL，每条包含question、answer、contexts三个字段。如果你只有原始文档、没有标注问答对，可以先用文档切片做检索测试，评测指标里context_precision和context_recall仍然能算。准备一份最小测试集：

[ { "question": "Ollama 默认监听哪个端口？", "answer": "11434", "contexts": ["Ollama 默认监听 127.0.0.1:11434，仅允许本机访问。"] } ]

存成test_set.json，在 Web UI 里上传即可。数据量不用大，10 到 20 条就能看出指标趋势。

3.4 与 TaoToken 配置的对照

如果你想把同一份测试集在云端模型上跑一遍做对比，TaoToken 的配置结构和上面几乎一样，只是base_url换成https://taotoken.net/api，api_key换成在控制台申请的密钥。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，密钥管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。这种“本地跑基线、云端跑对比”的做法，在评测阶段很实用，因为本地小模型和云端大模型的差距能直接量化出来。

4. 验证请求：跑通检索增强生成与自动化评测

4.1 启动服务并确认端口

先确保 Ollama 在跑：

curl http://localhost:11434/v1/models

返回 JSON 里能看到deepseek-r1:1.5b和nomic-embed-text就对了。如果返回空列表，说明模型没拉成功，回到 2.1 重拉。然后启动 XRAG 的评测流程。命令行方式：

xrag evaluate --config config.toml --dataset test_set.json --output result.json

Web UI 方式就是前面说的xrag ui，在页面上点“运行评估”。两种方式底层一样，命令行适合脚本化，UI 适合看指标可视化。

4.2 评测脚本的验证动作

为了确认整条链路真的通了，写一个最小验证脚本verify_rag.py：

import requests import json OLLAMA_URL = "http://localhost:11434/v1/chat/completions" def ask(question, context): payload = { "model": "deepseek-r1:1.5b", "messages": [ {"role": "system", "content": "根据以下上下文回答问题，不要编造。"}, {"role": "user", "content": f"上下文：{context}\n问题：{question}"} ], "temperature": 0.1 } resp = requests.post(OLLAMA_URL, json=payload, timeout=120) return resp.json()["choices"][0]["message"]["content"] if __name__ == "__main__": ctx = "Ollama 默认监听 127.0.0.1:11434，仅允许本机访问。" q = "Ollama 默认监听哪个端口？" print(ask(q, ctx))

运行python verify_rag.py，如果输出里包含11434，说明“检索片段 + 本地模型生成”这条最小链路是通的。这一步很关键，它把 RAG 的“答案生成”环节单独拎出来验证，排除了检索和评测框架的干扰。很多新手一上来就跑完整评测，报错后分不清是模型问题还是框架问题，先用这个脚本定位。

4.3 看评测结果

result.json里会列出每条问题的各项指标。以faithfulness为例，它衡量答案是否忠实于检索到的上下文，取值 0 到 1。如果某条问题得分很低，点开看它的contexts和answer，大概率是检索没召回正确片段，或者模型在上下文里没找到答案就开始编。context_recall低则说明知识库里根本没有相关内容，需要补文档。这种“指标低 → 定位环节 → 针对性改”的循环，就是 XRAG 相比裸跑 RAG 的最大价值。

4.4 长期编码与 Agent 场景的延伸

如果你打算把 RAG 能力接到编码助手或 Agent 工作流里，比如让模型基于本地代码库回答问题，可以考虑用 Coding Plan 这类长期方案来管理模型调用和额度。入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。它和本地 Ollama 不冲突，本地负责隐私敏感数据，云端负责复杂推理，按场景分流。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

5.1 401 Unauthorized

本地 Ollama 场景下出现 401，通常是配置里api_key留空或写了特殊字符。Ollama 不校验密钥，但 OpenAI 客户端库要求这个字段非空。解决办法：填任意字符串，比如ollama或sk-local。如果你用的是云端服务，401 就是密钥真的不对，去控制台重新生成。TaoToken 的密钥管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，生成后复制完整字符串，注意不要带空格。

5.2 local proxy failed

这个报错一般出现在客户端尝试走系统代理、但代理没开或配置错误时。本地 Ollama 是localhost直连，不应该走代理。检查环境变量：

echo $HTTP_PROXY echo $HTTPS_PROXY

如果有值，临时清掉：

unset HTTP_PROXY HTTPS_PROXY

或者在代码里显式禁用代理：

import os os.environ["NO_PROXY"] = "localhost,127.0.0.1"

注意，这里说的是本地回环地址不走代理，和网络访问方式无关。本地服务就该直连。

5.3 reading choices 报错

KeyError: 'choices'或reading choices failed说明返回的 JSON 结构不符合 OpenAI 格式。常见原因有两个：一是base_url写成了http://localhost:11434而漏了/v1，Ollama 的兼容接口在/v1路径下；二是模型名写错，Ollama 返回了错误信息而不是标准响应。先用 curl 确认：

curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-r1:1.5b","messages":[{"role":"user","content":"hi"}]}'

返回里有choices数组就说明接口正常，问题在客户端配置。

5.4 OAuth 相关报错

如果你在配置里看到 OAuth 字样，通常是误用了需要 OAuth2.0 的托管服务端点。本地 Ollama 和标准 OpenAI 兼容接口都用 Bearer Token，不涉及 OAuth 流程。检查base_url是否指向了错误的地址。如果你确实需要 OAuth 保护的公网服务，那是另一套鉴权体系，本文的本地场景不涉及。

5.5 模型加载慢或超时

1.5b 模型首次加载需要几秒到十几秒，7b 更久。如果请求超时，把客户端 timeout 调大：

resp = requests.post(url, json=payload, timeout=300)

另外确认内存够用，ollama ps能看到当前加载的模型和占用。内存不足时模型会反复换入换出，表现为响应极慢。

5.6 端口冲突

11434被占用时 Ollama 起不来。查占用：

lsof -i :11434

如果是残留进程，kill 掉重启。不要为了“省事”把 Ollama 改成监听0.0.0.0，那会让本机服务暴露在局域网甚至公网，前面提到的未授权访问风险就是这么来的。保持127.0.0.1默认值。

6. 从本地跑通到持续迭代：把评测变成日常动作

跑通一次评测不算完，真正有用的是把它变成习惯。我的做法是：每次改chunk_size、换 embedding 模型、调整 prompt 模板，都跑一遍同一份测试集，把result.json按日期存档。两周下来就能看出哪个参数组合在faithfulness和answer_relevancy上更稳。XRAG 的失败点检测会直接告诉你哪条问题在哪个环节掉链子，比人肉翻日志快得多。

本地 Ollama 的优势是零成本、数据不出机，适合做高频迭代的基线。当基线稳定后，再把同一份测试集丢给云端模型跑对比，看看差距值不值得为它付费。TaoToken 的模型对话入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，配置格式和本地一致，切换只改两行。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后提醒一句：评测集要自己标，别直接用网上的通用集。你的知识库长什么样，测试集就该覆盖那些问题。10 条真实业务问题，比 100 条通用问答更能暴露系统短板。跑通之后，把verify_rag.py和config.toml一起提交到 git，下次换机器五分钟就能复现整套环境。