ollama-deep-researcher源码贡献：新手入门指南
项目地址: https://gitcode.com/GitHub_Trending/ol/ollama-deep-researcher 你是否想为开源项目贡献代码但苦于没有清晰指引？作为完全本地化的AI研究助手，ollama-deep-researcher正需要社区力量完善功能。本文将从环境搭建到PR提交，手把手教你完成首次源码贡献，包括项目架构解析、代码规范、贡献流程全攻略，让你的每一行代码都产生价值。
一、开发环境准备
1.1 基础环境要求
- Python 3.9+（推荐3.11，项目依赖
python-dotenv==1.0.1） - Git 2.30+
- Ollama/LMStudio（本地LLM运行时）
- 网络环境（用于依赖安装和文档查阅）
1.2 环境搭建步骤
# 克隆仓库（使用国内GitCode地址）
git clone https://gitcode.com/GitHub_Trending/ol/ollama-deep-researcher.git
cd ollama-deep-researcher
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/Mac
.venv\Scripts\Activate.ps1 # Windows PowerShell
# 安装开发依赖
pip install -e .[dev] # 包含ruff代码检查工具
# 配置环境变量
cp .env.example .env
# 编辑.env文件设置LLM_PROVIDER、LOCAL_LLM等参数
⚠️ 依赖安装常见问题：若
uvx命令缺失，需先安装uv包管理器：
curl -LsSf https://astral.sh/uv/install.sh | sh（Linux/Mac）
二、项目架构解析
2.1 核心模块关系图
2.2 关键工作流（研究迭代流程）
2.3 代码目录结构
ollama-deep-researcher/
├── src/
│ └── ollama_deep_researcher/
│ ├── __init__.py # 包初始化
│ ├── configuration.py # 配置管理
│ ├── graph.py # 核心工作流逻辑
│ ├── state.py # 状态定义
│ ├── utils.py # 工具函数（搜索/格式化）
│ ├── prompts.py # 提示词模板
│ └── lmstudio.py # LMStudio LLM适配器
├── .env.example # 环境变量模板
├── pyproject.toml # 依赖和代码规范配置
└── README.md # 项目说明
三、贡献流程全攻略
3.1 标准贡献步骤
3.2 分支命名规范
| 分支类型 | 命名格式 | 示例 |
|---|---|---|
| 新功能 | feature/简短描述 | feature/add-searxng-support |
| Bug修复 | fix/问题描述 | fix/tavily-timeout-error |
| 文档更新 | docs/内容主题 | docs/update-install-guide |
| 代码重构 | refactor/模块名 | refactor/utils-search-functions |
3.3 PR提交模板
## 变更类型
- [ ] 新功能
- [ ] Bug修复
- [ ] 文档更新
- [ ] 代码重构
- [ ] 性能优化
## 描述
<!-- 详细说明变更内容 -->
## 测试
- [ ] 添加了新测试
- [ ] 现有测试全部通过
## 截图（如适用）
## 相关Issue
<!-- 关联的issue编号 #123 -->
四、代码规范与质量保障
4.1 代码风格要求
项目使用ruff进行代码检查，配置见pyproject.toml：
[tool.ruff]
lint.select = ["E", "F", "I", "D", "D401", "T201", "UP"]
lint.ignore = ["UP006", "UP007", "UP035", "D417", "E501"]
lint.pydocstyle.convention = "google"
提交前必须执行：
ruff check src/ # 检查代码风格
ruff format src/ # 自动格式化（若需）
4.2 文档字符串规范（Google风格）
def generate_search_query_with_structured_output(
configurable: Configuration,
messages: list,
tool_class,
fallback_query: str,
tool_query_field: str,
json_query_field: str,
):
"""生成结构化搜索查询的辅助函数。
支持工具调用模式和JSON模式两种方式提取查询。当LLM无法生成有效输出时，
返回预设的回退查询。
Args:
configurable: 配置对象，包含LLM提供商和调用模式设置
messages: 发送给LLM的消息列表
tool_class: 工具调用模式下使用的工具类
fallback_query: 提取失败时使用的回退查询
tool_query_field: 工具参数中查询字段的名称
json_query_field: JSON响应中查询字段的名称
Returns:
包含"search_query"键的字典
"""
五、功能开发实战示例
5.1 添加新的搜索后端（以SerpAPI为例）
- 在utils.py中实现搜索函数：
def serpapi_search(query: str, max_results: int = 3) -> Dict[str, List[Dict[str, Any]]]:
"""使用SerpAPI执行搜索并返回格式化结果"""
import os
from serpapi import GoogleSearch
params = {
"q": query,
"api_key": os.getenv("SERPAPI_KEY"),
"num": max_results
}
search = GoogleSearch(params)
results = search.get_dict()
# 转换为项目统一的结果格式
formatted_results = {
"organic_results": [
{
"title": item.get("title"),
"link": item.get("link"),
"snippet": item.get("snippet")
}
for item in results.get("organic_results", [])
]
}
return formatted_results
- 更新Configuration类：
# configuration.py中添加SERPAPI支持
class Configuration(BaseModel):
# ... 现有代码 ...
search_api: SearchAPI = Field(
default=SearchAPI.duckduckgo,
description="Search API to use (duckduckgo, tavily, perplexity, searxng, serpapi)",
)
- 在graph.py中添加路由逻辑：
# web_research函数中添加
elif search_api == "serpapi":
search_results = serpapi_search(state.search_query, max_results=3)
search_str = deduplicate_and_format_sources(...)
六、测试策略
⚠️ 当前项目未包含测试文件，贡献者可优先添加以下类型测试：
- 单元测试：使用pytest测试独立函数（如utils.py中的搜索格式化）
- 集成测试：验证完整研究流程（需本地LLM环境）
- 兼容性测试：不同模型（llama3.2/deepseek-r1）的JSON输出兼容性
示例单元测试（test_utils.py）：
def test_deduplicate_and_format_sources():
mock_results = {
"organic_results": [
{"title": "Test", "link": "https://example.com", "snippet": "Test content"}
]
}
result = deduplicate_and_format_sources(mock_results, 1000)
assert "https://example.com" in result
assert "Test content" in result
七、常见问题与解决方案
| 问题 | 解决方案 |
|---|---|
| LLM无法生成JSON格式 | 启用use_tool_calling配置，或使用更兼容的模型（如llama3.2） |
| 搜索结果重复 | 检查deduplicate_and_format_sources函数的去重逻辑 |
| LangGraph Studio无法打开 | 确保使用Firefox浏览器，关闭广告拦截插件 |
| 依赖冲突 | 使用uv代替pip：uv install -e .[dev] |
八、社区与资源
- 项目仓库：https://gitcode.com/GitHub_Trending/ol/ollama-deep-researcher
- Issue跟踪：通过仓库Issue功能提交问题和建议
- 开发交流：可在项目Discussions区提问（若有）
贡献者公约
- 保持友好和尊重的沟通
- 优先提交小而集中的PR，便于审核
- 新功能需包含文档更新
- 重大变更前建议先创建Issue讨论
通过以上步骤，你已经具备了为ollama-deep-researcher贡献代码的全部知识。开源贡献不仅是代码的提交，更是与社区共同成长的过程。期待你的第一个PR！
💡 读完本文你可以：
✅ 搭建完整的开发环境
✅ 理解项目核心工作流
✅ 提交符合规范的代码贡献
✅ 参与开源社区协作
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
