告别网络依赖：ollama-deep-researcher完全本地API指南

【免费下载链接】ollama-deep-researcher Fully local web research and report writing assistant 项目地址: https://gitcode.com/GitHub_Trending/ol/ollama-deep-researcher

你还在为研究工具依赖云端服务而担忧数据安全吗？还在因网络延迟影响研究效率吗？本文将带你全面掌握ollama-deep-researcher的API使用方法，无需联网即可完成深度网络研究与报告撰写。读完本文，你将能够：配置本地化模型引擎、调用核心API实现研究闭环、优化搜索策略提升结果质量。

核心架构概览

ollama-deep-researcher采用模块化设计，主要由配置模块、工作流引擎、搜索工具和状态管理四部分组成。项目结构如下：

ollama-deep-researcher/
├── src/ollama_deep_researcher/
│   ├── configuration.py  # API配置核心
│   ├── graph.py          # 研究工作流定义
│   ├── prompts.py        # 提示词模板管理
│   └── state.py          # 状态管理模型
└── docs/new_features_0.0.1.md  # 新功能文档

核心工作流基于LangGraph实现，通过状态机管理研究过程，支持动态调整研究深度和搜索策略。架构详情可参考graph.py中的StateGraph定义。

项目架构

配置API详解

配置模块是使用所有API的基础，通过configuration.py定义的Configuration类实现灵活配置。

主要配置参数

参数名	默认值	说明
max_web_research_loops	3	研究迭代次数，控制深度
local_llm	"llama3.2"	本地模型名称
llm_provider	"ollama"	模型提供商，可选"ollama"或"lmstudio"
search_api	"duckduckgo"	搜索引擎，支持四大引擎
fetch_full_page	True	是否抓取完整页面内容

配置优先级

配置值按以下顺序生效（优先级从高到低）：

1. 环境变量（如OLLAMA_BASE_URL）
2. LangGraph UI配置
3. Configuration类默认值

配置加载逻辑详见configuration.py的from_runnable_config方法。

工作流API核心节点

研究工作流由五个核心节点组成，通过graph.py定义，支持自定义扩展。

1. 查询生成（generate_query）

根据研究主题生成优化的搜索查询，支持工具调用和JSON两种输出模式。关键代码：

messages = [
    SystemMessage(content=formatted_prompt + (
        tool_calling_query_instructions if configurable.use_tool_calling 
        else json_mode_query_instructions
    )),
    HumanMessage(content="Generate a query for web search:"),
]

提示词模板定义在prompts.py的query_writer_instructions变量中，包含当前日期和研究主题上下文。

2. 网页搜索（web_research）

根据查询调用指定搜索引擎，支持四种搜索API动态切换。路由逻辑：

不同搜索引擎的实现细节可查看graph.py中web_research函数的switch-case逻辑。

3. 结果总结（summarize_sources）

整合新搜索结果与现有摘要，生成更新的研究总结。支持增量更新：

if existing_summary:
    human_message_content = (
        f"<Existing Summary> \n {existing_summary} \n <Existing Summary>\n\n"
        f"<New Context> \n {most_recent_web_research} \n <New Context>"
        f"Update the Existing Summary with the New Context..."
    )

总结提示词模板在prompts.py的summarizer_instructions变量中定义，包含详细的总结规则。

4. 反思优化（reflect_on_summary）

分析当前摘要找出知识缺口，生成后续查询。核心逻辑：

messages = [
    SystemMessage(content=formatted_prompt + (
        tool_calling_reflection_instructions if configurable.use_tool_calling 
        else json_mode_reflection_instructions
    )),
    HumanMessage(content=f"Reflect on our existing knowledge: \n === \n {state.running_summary}..."),
]

反思提示词模板在prompts.py的reflection_instructions变量中，强调技术细节和新兴趋势的挖掘。

5. 总结定稿（finalize_summary）

去重并格式化所有来源，生成带引用的最终报告：

state.running_summary = (
    f"## Summary\n{state.running_summary}\n\n ### Sources:\n{all_sources}"
)

来源去重逻辑通过哈希集合实现，确保引用唯一性，详见graph.py中finalize_summary函数的实现。

状态管理API

状态管理通过state.py定义的三个数据类实现：

• SummaryStateInput: 输入状态，包含研究主题
• SummaryState: 运行时状态，包含搜索查询、结果、摘要等
• SummaryStateOutput: 输出状态，包含最终报告

核心状态流转如图所示：

状态字段详细说明可参考state.py中的数据类定义。

高级使用技巧

模型切换策略

Ollama和LMStudio引擎各有优势，可根据模型特性切换：

# Ollama配置
OLLAMA_BASE_URL="http://localhost:11434/"
LOCAL_LLM="llama3.2"

# LMStudio配置
LLM_PROVIDER="lmstudio"
LMSTUDIO_BASE_URL="http://localhost:1234/v1"
LOCAL_LLM="qwen_qwq-32b"

LMStudio特别优化了JSON响应处理，详见lmstudio.py中的响应净化逻辑。

搜索工具选择指南

搜索引擎	优势	适用场景
DuckDuckGo	无需API密钥	快速测试
Tavily	全文抓取	深度研究
Perplexity	学术资源丰富	学术研究
SearXNG	可自建实例	隐私敏感场景

搜索工具配置示例可参考docs/new_features_0.0.1.md中的环境变量设置。

常见问题解决

JSON解析错误

若遇到JSON解析错误，可启用工具调用模式作为备选：

USE_TOOL_CALLING=true

工具调用实现详见graph.py中generate_search_query_with_structured_output函数的tool调用分支。

模型响应缓慢

可降低研究深度减少迭代次数：

MAX_WEB_RESEARCH_LOOPS=2

或选择更小的模型，如DeepSeek R1 (1.5B)，配置方法详见README.md中的模型选择部分。

总结与展望

ollama-deep-researcher通过全本地架构、模块化设计和智能工作流，为研究者提供了安全高效的研究工具。核心API涵盖配置、工作流、状态管理等关键环节，可灵活适应不同研究需求。

下一版本将重点提升多语言支持和报告模板系统，建议关注docs/new_features_0.0.1.md获取最新功能动态。

若在使用中遇到问题，欢迎查阅项目文档或提交Issue参与讨论。收藏本文，随时查阅API使用细节，提升你的本地研究效率！

【免费下载链接】ollama-deep-researcher Fully local web research and report writing assistant 项目地址: https://gitcode.com/GitHub_Trending/ol/ollama-deep-researcher