一、项目改造背景

原项目 DeepSearchAgent 依赖 DeepSeek API 实现大模型调用，存在两个核心问题：

1. DeepSeek API 需付费（免费额度耗尽后无法使用，报错 Insufficient Balance）；
2. 必须配置 DeepSeek API Key，否则无法运行。

改造目标

• 完全移除 DeepSeek API 依赖，改用 本地Ollama部署的DeepSeek模型（免费无调用限制）；
• 保持项目核心功能（深度搜索、报告生成、状态管理）不变；
• 兼容原有 basic_usage.py、advanced_usage.py 脚本及 Streamlit Web 界面；
• 仅保留必要配置（Ollama本地模型 + Tavily搜索API Key）。

二、核心改造内容

1. 配置文件重构（src/utils/config.py）

关键修改

• 移除所有 DeepSeek 相关配置项，新增 Ollama 核心配置（模型名称、API地址）；
• 简化配置验证逻辑：仅在选择 OpenAI 时检查其 API Key，选择 Ollama 时跳过 LLM 密钥检查（仅验证 Tavily Key）；
• 加载逻辑优化：从根目录 config.py 读取 Ollama 配置，减少重复输入。

核心代码片段

@dataclass
class Config:
    # Ollama配置（核心新增）
    ollama_model: str = "deepseek-r1:14b"  # 本地模型名称
    ollama_api_base: str = "http://localhost:11434/api/chat"  # Ollama默认接口
    # 必要配置（保留）
    tavily_api_key: Optional[str] = None  # 搜索功能必须
    default_llm_provider: str = "ollama"  # 默认使用Ollama

    def validate(self) -> bool:
        # Ollama模式仅验证Tavily Key
        if self.default_llm_provider == "ollama":
            if not self.tavily_api_key:
                print("错误: Tavily API Key未设置")
                return False
            return True
        # 其他提供商验证逻辑（可选保留）
        ...

2. Ollama LLM 实现（src/llms/ollama_llm.py）

新增本地模型调用类，通过 Ollama 提供的 HTTP API 与本地模型交互，无需 API Key：

• 适配项目 BaseLLM 抽象接口，无缝替换原有 DeepSeekLLM；
• 支持自定义生成参数（temperature、max_tokens）；
• 内置连接校验，确保 Ollama 服务正常运行。

3. Agent 初始化逻辑修改（src/agent.py）

• 在 _initialize_llm 方法中新增 Ollama 分支，加载本地模型；
• 移除 DeepSeek 相关初始化代码，避免冗余依赖。

def _initialize_llm(self) -> BaseLLM:
    if self.config.default_llm_provider == "ollama":
        from .llms.ollama_llm import OllamaLLM
        return OllamaLLM(
            model_name=self.config.ollama_model,
            api_base=self.config.ollama_api_base
        )
    elif self.config.default_llm_provider == "openai":
        # 保留OpenAI支持（可选）
        ...

4. 示例脚本适配（basic_usage.py / advanced_usage.py）

• basic_usage.py：无需修改，直接加载重构后的配置（默认使用 Ollama）；
• advanced_usage.py：修复配置加载逻辑，从 config.py 读取 Tavily Key，避免手动配置遗漏。

5. Streamlit Web 界面改造（examples/streamlit_app.py）

关键优化

• 移除 DeepSeek 相关配置项，新增 Ollama 模型名称、API地址输入框（默认加载本地配置）；
• 模型提供商下拉框仅保留 ollama、openai 选项，避免无效配置；
• 进度条、结果展示等功能保持不变，新增报告下载（Markdown/JSON）。

三、运行流程（最终版）

1. 前置准备

1. 安装 Ollama 客户端：官方下载地址；
2. 拉取并启动 DeepSeek 本地模型：

   ollama pull deepseek-r1:14b  # 下载模型（约10GB）
   ollama run deepseek-r1:14b   # 启动服务（默认端口11434）
   

3. 获取 Tavily API Key：免费注册地址，填入根目录 config.py。

2. 项目配置（根目录 config.py）

# 核心配置（仅需3行）
OLLAMA_MODEL = "deepseek-r1:14b"  # 本地模型名称
OLLAMA_API_BASE = "http://localhost:11434/api/chat"
TAVILY_API_KEY = "tvly-xxxxxx"  # 你的Tavily密钥

# 其他配置（默认即可）
DEFAULT_LLM_PROVIDER = "ollama"
MAX_REFLECTIONS = 2
SEARCH_RESULTS_PER_QUERY = 3

3. 启动方式

（1）基础示例

python examples/basic_usage.py

• 功能：单查询研究，生成报告并保存到 reports/ 目录。

（2）高级示例（多任务+状态管理）

python examples/advanced_usage.py

• 功能：批量处理多个查询，支持状态保存与恢复。

（3）Web 界面

streamlit run examples/streamlit_app.py

• 功能：可视化操作，支持查询输入、进度查看、报告下载。

四、关键注意事项

1. Ollama 服务必须启动：运行项目前需确保 ollama run deepseek-r1:14b 已启动（单独窗口运行，不可关闭）；
2. 硬件要求：deepseek-r1:14b 模型需至少 16GB GPU 显存（无GPU则用CPU，速度较慢）；
3. Tavily Key 不可缺失：搜索功能依赖 Tavily API，免费额度每月 1000 次，足够测试；
4. 端口冲突：若 11434 端口被占用，需修改 OLLAMA_API_BASE 并同步 Ollama 启动端口。

五、改造价值

1. 零成本运行：替代付费的 DeepSeek API，本地模型无调用次数限制；
2. 功能无损：核心流程（搜索→总结→反思→报告）完全保留；
3. 部署灵活：支持离线运行（仅搜索时需联网），隐私性更强；
4. 兼容性强：可无缝切换到其他 Ollama 模型（如 Llama 3、Qwen），只需修改 OLLAMA_MODEL。

六、常见问题排查

错误信息	解决方案
Ollama调用失败: Connection refused	启动 Ollama 服务（ollama run deepseek-r1:14b）
Tavily API Key未设置	检查根目录 config.py 中 Tavily 密钥是否填写
内存溢出	降低 max_tokens 参数，或更换更小参数量模型（如 deepseek-r1:7b）
Streamlit 语法错误	移除代码中中文全角符号（如 ：→:），确保 Python 版本≥3.9

总结

本次改造以「本地免费替代付费API」为核心，通过 Ollama 实现 DeepSeek 模型本地化部署，同时保持项目原有功能完整性。改造后项目更适合个人开发者、学生等无付费需求的用户，且部署流程简单，无需复杂环境配置，是一个低成本、高实用性的深度搜索工具。