企业官网建设流程全解析

• AI Agent
• 大模型
• 交互助手
• 后端

本指南围绕 README.md 展开，系统讲解ollama-deep-researcher这一「完全本地化」的网络研究助手的完整落地方法：它如何借助 Ollama 或 LMStudio 托管的任意本地大模型，在没有 API Key 的情况下完成"生成搜索词 → 网络检索 → 摘要 → 反思知识缺口 → 新一轮检索"的迭代研究，并最终产出一份带来源引用的 Markdown 研究报告。读完本文，你将掌握从.env配置、模型与搜索工具选型、LangGraph Studio 可视化运行，到 Docker 容器化部署的完整实战链路，并能基于源码理解其循环研究机制与结构化输出（JSON mode / Tool Calling）的实现原理。

一、项目定位与核心能力

ollama-deep-researcher是一个完全本地的 Web 研究助手：LLM 推理与网络检索均不依赖云服务。用户只需给出一个研究主题（topic），它会自动：

1. 生成一条针对性 Web 搜索查询；
2. 采集搜索结果；
3. 对搜索结果进行摘要；
4. 反思摘要、识别知识缺口（knowledge gaps）；
5. 针对缺口生成新的搜索查询；
6. 按用户设定的循环次数重复上述过程；
7. 最终输出一份包含全部引用来源的 Markdown 总结。

这一设计来源于论文 IterDRAG 的思路——将查询拆分为子查询、逐个检索并回答、在已有答案基础上继续检索下一子查询，从而实现渐进式的知识构建（详见下文"工作原理"）。在本仓库中，LLM 侧支持Ollama与LMStudio两种本地托管方式，检索侧默认使用无需 API Key 的DuckDuckGo，同时可切换SearXNG / Tavily / Perplexity。

从工程实现看，该助手是一个基于 LangGraph 下，入口由 langgraph.json 声明为./src/ollama_deep_researcher/graph.py:graph。

二、快速开始

1. 克隆仓库并准备环境文件

git clone https://gitcode.com/GitHub_Trending/ol/ollama-deep-researcher.git cd ollama-deep-researcher

复制环境变量模板：

cp .env.example .env

随后按需编辑.env。这些环境变量控制模型选择、搜索工具及其他配置项；应用启动时会通过python-dotenv自动加载——langgraph.json 中的"env": "./.env"字段即指向该文件。

2. 依赖与运行环境

项目基于 Python（requires-python = ">=3.10"，LangGraph 开发服务器推荐 3.11），核心依赖声明于 pyproject.toml，包括langgraph>=1.1.0、langchain-ollama>=1.0.0、langchain-openai>=1.1.14、duckduckgo-search>=7.3.0、tavily-python>=0.7.23、markdownify>=0.11.0等。

三、选择本地模型：Ollama 配置

1. 安装并拉取模型

1. 下载安装 Ollama 桌面应用；
2. 拉取一个本地 LLM，例如 DeepSeek R1 的 8B 蒸馏版：

ollama pull deepseek-r1:8b

2. 在.env中配置 Ollama

LLM_PROVIDER=ollama OLLAMA_BASE_URL="http://localhost:11434" # Ollama 服务端点，默认 http://localhost:11434 LOCAL_LLM=model # 要使用的模型名，不设置时默认 llama3.2

若设置了这些环境变量，它们将优先于configuration.py 中Configuration类的默认值。

从源码看，Configuration对 Ollama 的默认值如下（configuration.py）：

• llm_provider默认"ollama"；
• local_llm默认"llama3.2"；
• ollama_base_url默认"http://localhost:11434/"。

在 graph.py 的get_llm()中，Ollama 通过langchain_ollama.ChatOllama实例化：非工具调用模式下传入format="json"以启用 JSON 结构化输出，工具调用模式下则不传该参数（见下文"结构化输出"）。

四、选择本地模型：LMStudio 配置

1. 在 LMStudio 中准备模型

1. 下载安装 LMStudio；
2. 下载并加载目标模型（例如qwen_qwq-32b）；
3. 打开Local Server标签页；
4. 启动 OpenAI 兼容 API 服务器，记下服务器地址（默认http://localhost:1234/v1）。

2. 在.env中配置 LMStudio

LLM_PROVIDER=lmstudio LOCAL_LLM=qwen_qwq-32b # 使用 LMStudio 中显示的精确模型名 LMSTUDIO_BASE_URL=http://localhost:1234/v1

源码中对应的默认值（configuration.py）：lmstudio_base_url默认http://localhost:1234/v1。

LMStudio 接入由 lmstudio.py 中的ChatLMStudio类实现——它继承langchain_openai.ChatOpenAI，通过 LMStudio 的 OpenAI 兼容接口通信。两个值得注意的实现细节：

• api_key参数被硬编码为"not-needed-for-local-models"（本地模型无需真实密钥，但 OpenAI 客户端要求该字段）；
• 当format="json"时，_generate()会设置response_format={"type": "json_object"}，并在返回前对原始文本做 JSON 清洗：定位首个{与最后一个}，截取并校验 JSON 片段，从而容忍部分模型输出中的多余前后缀（lmstudio.py）。

五、选择搜索工具

项目默认使用DuckDuckGo进行网络搜索，无需任何 API Key；也可切换为SearXNG、Tavily或Perplexity。在.env中追加：

SEARCH_API=xxx # 搜索 API，如 duckduckgo（默认） TAVILY_API_KEY=xxx # Tavily API Key PERPLEXITY_API_KEY=xxx # Perplexity API Key MAX_WEB_RESEARCH_LOOPS=xxx # 最大研究循环步数，默认 3 FETCH_FULL_PAGE=xxx # 是否抓取完整页面内容（duckduckgo），默认 false

Configuration中的对应字段与默认值（configuration.py）：

注意：README 与.env.example均标注FETCH_FULL_PAGE默认false，而 configuration.py 中fetch_full_page的 Pydantic 默认值为True。由于配置读取顺序是"环境变量 > UI 配置 > 类默认值"，显式在.env中设置该变量才是行为可控的做法。

各搜索实现位于 utils.py：

• DuckDuckGo（duckduckgo_search）：通过DDGS.text()检索，默认取max_results=3；启用fetch_full_page时，会用httpx（10 秒超时）抓取原始页面并经markdownify转为 Markdown（utils.py）。
• SearXNG（searxng_search）：读取环境变量SEARXNG_URL（默认http://localhost:8888），通过SearxSearchWrapper检索（utils.py）。该变量可追加到.env：SEARXNG_URL=http://localhost:8888。
• Tavily（tavily_search）：使用TavilyClient，include_raw_content由fetch_full_page控制（utils.py）。
• Perplexity（perplexity_search）：调用sonar-pro模型接口，将首个引文作为主来源、其余引文作为纯引用（raw_content=None）加入结果列表（utils.py）。

另外，多来源结果会经deduplicate_and_format_sources按 URL 去重，并限制每源最多MAX_TOKENS_PER_SOURCE = 1000tokens（按CHARS_PER_TOKEN = 4估算截断，graph.py、utils.py）。

六、运行方式与配置优先级

1. 通过 LangGraph Studio 运行

Mac（推荐方式）：

# 创建虚拟环境 python -m venv .venv source .venv/bin/activate # 安装 uv 包管理器 curl -LsSf https://astral.sh/uv/install.sh | sh # 启动 LangGraph 开发服务器 uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.11 langgraph dev

Windows：

# 安装 Python 3.11（并加入 PATH），重启终端后创建虚拟环境 python -m venv .venv .venv\Scripts\Activate.ps1 # 安装依赖 pip install -e . pip install -U "langgraph-cli[inmem]" # 启动 LangGraph 服务器 langgraph dev

启动成功后，终端会出现类似输出，浏览器将打开 Studio Web UI：

Ready! API: http://127.0.0.1:2024 Docs: http://127.0.0.1:2024/docs LangGraph Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

在 Studio 的configuration标签页中可直接设置各项助手配置（如Research Depth、LLM Model Name、LLM Provider、Search API、Fetch Full Page、Strip Thinking Tokens、Use Tool Calling等，字段定义见 configuration.py）。然后输入研究主题，即可在界面中实时可视化整个研究过程。

2. 配置优先级（重要）

1. 环境变量（最高优先级） 2. LangGraph UI 配置 3. Configuration 类的默认值（最低优先级）

该优先级由 configuration.py 的Configuration.from_runnable_config()保证：代码先取os.environ.get(name.upper(), configurable.get(name))——即环境变量优先于RunnableConfig中的 UI 配置，最后再用 Pydantic 默认值兜底。

3. 浏览器兼容性提示

访问 LangGraph Studio UI 时：

• 推荐使用Firefox获得最佳体验；
• Safari可能因混合内容（HTTPS/HTTP）出现安全警告；
• 如遇问题，依次尝试：改用 Firefox 或其他浏览器、关闭广告拦截扩展、查看浏览器控制台中的具体错误信息。

七、工作原理：从 IterDRAG 到 LangGraph 状态机

1. 方法论来源

项目受IterDRAG（Iterative Retrieval-Augmented Generation）论文启发：该方法把查询分解为子查询，为每个子查询检索文档并作答，再基于已有答案继续检索下一子查询。ollama-deep-researcher的迭代循环与之类似，但加入了"反思（reflection）"环节：

• 给定用户研究主题，用本地 LLM（Ollama / LMStudio）生成一条 Web 搜索查询；
• 用搜索引擎/工具查找相关来源；
• 用 LLM 对检索到的内容做摘要；
• 用 LLM反思摘要、识别知识缺口；
• 针对缺口生成新的搜索查询；
• 循环重复，摘要随每次新检索不断迭代更新；
• 运行次数由max_web_research_loops（Research Depth，默认 3）控制。

2. 图结构与执行流程

图的编排在 graph.py，包含 5 个节点：

START → generate_query → web_research → summarize_sources → reflect_on_summary │ （research_loop_count 未超上限）◄──────────┘ │ ▼ finalize_summary → END

各节点职责（graph.py）：

循环控制由条件边route_research完成（graph.py）：当research_loop_count <= max_web_research_loops时回到web_research，否则进入finalize_summary。

3. 图状态（State）

状态定义于 state.py：

• SummaryState：research_topic、search_query、web_research_results（operator.add累加）、sources_gathered（operator.add累加）、research_loop_count、running_summary；
• SummaryStateInput：仅接收research_topic（用户输入）；
• SummaryStateOutput：仅暴露running_summary（最终报告）。

所有检索来源都会被累积保存在图状态中，因此可直接在 LangGraph Studio 里查看每轮收集到的全部来源；最终 Markdown 总结也会写入图状态。

4. 结构化输出的两种模式与回退机制

为保证循环各环节可靠地提取查询字符串，项目提供了两种结构化输出路径（graph.py）：

• JSON mode（默认）：ChatOllama/ChatLMStudio以format="json"调用，提示词（prompts.py 中的json_mode_query_instructions、json_mode_reflection_instructions）要求输出含指定键的 JSON 对象，解析失败则使用回退查询；
• Tool Calling（use_tool_calling=true）：LLM 通过bind_tools调用Query/FollowUpQuery工具（Pydantic 模型定义了query/rationale或follow_up_query/knowledge_gap字段），从tool_calls[0]["args"]中提取字段，失败同样回退。

该机制由generate_search_query_with_structured_output()统一封装。注意以下几点：

• 模型兼容性：使用结构化 JSON 输出时，部分小模型难以稳定产出合法 JSON。例如 DeepSeek R1 7B / 1.5B 蒸馏版就存在此问题，此时助手会走回退机制（用主题构造兜底查询），保证流程不断。
• strip_thinking_tokens（默认true）：推理型模型（如 DeepSeek R1）会在回复中包裹<think>...</think>，utils.py 的strip_thinking_tokens()会迭代式剥离这些标记，避免污染摘要与 JSON 解析。
• gpt-oss 与 Tool Calling（2025-08-06 更新）：项目新增了对工具调用与gpt-oss模型的支持。⚠️ 由于Ollama 中的gpt-oss模型不支持 JSON mode，使用该系列模型时必须在配置中开启use_tool_calling，改用工具调用方式获取结构化输出。

八、输出结果

图的输出是一份Markdown 文件，包含研究总结及其引用来源。最终报告格式由finalize_summary节点拼接为：

## Summary <研究总结正文> ### Sources: * 标题1 : URL1 * 标题2 : URL2 ...

其中来源列表来自format_sources()（* title : url格式），并在拼接前按行去重（utils.py、graph.py）。所有检索到的来源与最终总结都会保存在图状态中，可在 LangGraph Studio 的状态面板中随时查看。

九、Docker 容器化部署

仓库自带的 Dockerfile仅以 LangGraph Studio 服务形式运行本项目，并不包含 Ollama 依赖服务——Ollama 需要单独运行，并通过OLLAMA_BASE_URL环境变量接入。

构建镜像：

docker build -t local-deep-researcher .

运行容器（示例使用 Tavily 搜索 + Ollama 模型）：

docker run --rm -it -p 2024:2024 \ -e SEARCH_API="tavily" \ -e TAVILY_API_KEY="tvly-***YOUR_KEY_HERE***" \ -e LLM_PROVIDER=ollama \ -e OLLAMA_BASE_URL="http://host.docker.internal:11434/" \ -e LOCAL_LLM="llama3.2" \ local-deep-researcher

说明：

• OLLAMA_BASE_URL指向宿主机上的 Ollama 服务（Docker Desktop 场景下为http://host.docker.internal:11434/）；
• 容器内会打印🎨 Opening Studio in your browser...日志，但浏览器不会在容器中自动打开（Dockerfile 的 CMD 使用了--host 0.0.0.0，Dockerfile）；
• 请在宿主机浏览器中访问 LangGraph Studio Web UI，并将baseUrl指向http://127.0.0.1:2024；
• 日志中出现的 URL 默认使用0.0.0.0:2024，直接访问时需替换为127.0.0.1:2024。

十、部署选项与衍生实现

本项目本质上是一个 LangGraph 图应用（graph.py 中graph = builder.compile()），因此可复用 LangGraph 生态的各类部署方式（LangGraph Platform 等）将图发布为服务。官方还提供了对应的 TypeScript 移植版本（不含 Perplexity 搜索），便于在 Node.js / TS 技术栈中复用同样的研究流程。

附录：配置速查表

以下环境变量均写入.env（参考 .env.example）：

对应地，LangGraph Studio 的 configuration 面板中还提供Strip Thinking Tokens（剥离<think>标记）与Use Tool Calling（以工具调用替代 JSON mode）两个开关，分别对应Configuration.strip_thinking_tokens与Configuration.use_tool_calling字段。合理组合这些配置，即可让ollama-deep-researcher在低配本地模型与推理型模型上都稳定产出带引用的深度研究报告。

• AI Agent
• 大模型
• 交互助手
• 后端