{"id":34422208,"url":"https://github.com/cat3399/deepresearch","last_synced_at":"2026-01-17T05:36:52.604Z","repository":{"id":300564218,"uuid":"993764860","full_name":"cat3399/deepresearch","owner":"cat3399","description":"一个openai api格式的开源deepresearch方案，专注于提高搜索质量","archived":false,"fork":false,"pushed_at":"2025-10-04T07:02:15.000Z","size":11900,"stargazers_count":77,"open_issues_count":0,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T09:07:40.338Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cat3399.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-31T13:26:44.000Z","updated_at":"2025-10-04T07:02:19.000Z","dependencies_parsed_at":"2025-06-29T13:37:18.950Z","dependency_job_id":null,"html_url":"https://github.com/cat3399/deepresearch","commit_stats":null,"previous_names":["cat3399/deepresearch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cat3399/deepresearch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cat3399%2Fdeepresearch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cat3399%2Fdeepresearch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cat3399%2Fdeepresearch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cat3399%2Fdeepresearch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cat3399","download_url":"https://codeload.github.com/cat3399/deepresearch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cat3399%2Fdeepresearch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28500326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T04:31:57.058Z","status":"ssl_error","status_checked_at":"2026-01-17T04:31:45.816Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-21T08:00:28.120Z","updated_at":"2026-01-17T05:36:52.596Z","avatar_url":"https://github.com/cat3399.png","language":"Python","funding_links":[],"categories":["A01_文本生成_文本对话"],"sub_categories":["大语言对话模型及数据"],"readme":"[English](README_en.md) | 简体中文\n\n---\n\n# DeepRearch 深度研究\n\n本项目是一个基于 Python 实现的 AI 驱动的智能搜索与深度研究解决方案。它旨在通过良好的 Agent 架构设计和精密的搜索策略，帮助用户从海量信息中获取高质量、高相关的资料。\n\n\u003e **核心理念：** 提高搜索资料的质量，远比罗列上百个网页更有价值。\n\n## ✨ 主要特性\n\n*   **可完全本地部署**: 使用到的所有服务,均可本地部署,除大模型API外,不依赖任何在线服务\n*   **可视化的研究过程**: 整个研究过程完全透明，它会实时地向您“直播” AI 从初步规划、动态搜索、评估网页到迭代深化的每一步\n*   **兼容OpenAI格式的 API 服务**: 基于 Flask 构建，提供符合 OpenAI 格式的 API 接口\n*   **网页内容压缩**: 使用大模型压缩网页内容，减少上下文长度，提高有效信息密度，在相同的上下文下，可以访问更多的网页\n*   **多个大模型协同工作**: 充分发挥各个模型的能力，协同完成整个任务\n*   **可控的过程**: 用户通过提示词，即可控制搜索使用的语言，资料来源限制等\n*   **精密的提示工程**: 内置大量精心设计的 Prompt与消息处理，指导 LLM 完成复杂的搜索规划、信息评估和内容生成任务，在全部使用Gemini 2.5 flash模型的情况下，测试数十次未出现任何差错\n\n\n## 目录\n- [✨ 主要特性](#-主要特性)\n- [🏗️ 系统架构](#-系统架构)\n- [🚀 快速开始](#-快速开始)\n  - [方法一：使用 Docker (推荐)](#方法一使用-docker-推荐)\n  - [方法二：本地部署](#方法二本地部署)\n- [🧩 外部服务依赖](#-外部服务依赖)\n- [🛠️ API 使用示例](#-api-使用示例)\n- [📦 Python 库依赖](#-python-库依赖)\n- [💡 效果展示](#-效果展示)\n  - [总结类](#总结类)\n  - [冷门问题](#冷门问题)\n- [🤔 已知问题](#-已知问题)\n- [✍️ TODO](#-todo)\n- [🤝 贡献](#-贡献)\n- [📄 开源许可](#-开源许可)\n- [Star History](#star-history)\n\n## 🏗️ 系统架构\n\n![系统架构图](img/系统架构图.png)\n\n## 🚀 快速开始\n\n我们提供两种部署方式：使用 Docker（推荐）或直接在本地环境运行。\n\n### **方法一：使用 Docker (推荐)**\n\n这是最简单、最推荐的部署方式，无需手动管理 Python 环境和依赖。项目根目录已提供 `Dockerfile` 和 `docker-compose.yml` 文件。\n\n#### 启动服务\n\n您可以选择使用 Docker Compose 或 Docker CLI 来启动服务。\n\n**A. 使用 Docker Compose (推荐)**\n\n项目根目录已包含 `docker-compose.yml` 文件，内容如下：\n\n```yaml\nversion: '3'\n\nservices:\n  deepresearch:\n    container_name: deepresearch\n    image: cat3399/deepresearch:latest\n    ports:\n      - \"5000:5000\"\n    # volumes:\n    #   - ./.env:/app/.env # 如果您想使用本地的 .env 文件，请取消此行的注释\n```\n\n在项目根目录下运行以下命令即可启动服务：\n\n```bash\ndocker-compose up -d\n```\n\u003e **注意**：`docker-compose.yml` 文件中的 `volumes` 部分默认被注释。如果您希望将本地的 `.env` 文件直接映射到容器中（推荐做法），请**取消该行的注释**后再运行\n\n**B. 使用 Docker CLI**\n\n如果您不使用 Docker Compose，也可以使用以下命令直接运行 Docker 容器：\n\n```bash\ndocker run -d --name deepresearch -p 5000:5000 cat3399/deepresearch:latest\n```\n\n#### **3. 访问服务**\n服务启动后，即可通过 `http://127.0.0.1:5000` 访问 API 服务，或通过 `http://127.0.0.1:5000/setting` 访问可视化配置页面。\n\n---\n\n### **方法二：本地部署**\n\n#### **1. 环境准备**\n\n*   确保您已安装 Python 3.8+\n*   建议使用 `uv` 或 `venv` 等虚拟环境。\n\n#### **2. 安装依赖**\n\n克隆本仓库到本地后，在项目根目录下运行：\n\n```bash\npip install -r requirements.txt\n```\n\n#### **3. 配置环境变量**\n\n\u003e 可使用浏览器访问`http://127.0.0.1:5000/setting`进入配置文件的webui,进行可视化的配置。\n\u003e 保存后配置会立即生效，无需重启服务。\n\n**A. 快速上手 (仅使用 Gemini)**\n\n这是最简单的配置方式，如果您只想使用 Gemini API，请采用此方法。\n\n*   复制 `.env.template` 文件并重命名为 `.env`\n```bash\ncp .env.template .env\n```\n*   **唯一步骤**: 只需在配置文件中填入 `ALL_IN_GEMINI_KEY` 即可。\n*   **多 Key 支持**: 您可以填入多个 Gemini API Key，并用英文逗号 `,` 分隔。\n\u003e此配置基础与总结模型使用2.5pro,评估使用2.5flash 压缩使用 2.5flash lite 具体模型配置优先级高于此默认值\n---\n\n**B. 完整配置 (适用于所有模型)**\n*   复制 `.env.template` 文件并重命名为 `.env`\n```bash\ncp .env.template .env\n```\n*   根据您的实际情况，在 `.env` 文件中填写必要的 API 密钥和 URL。\n\n\u003e **通用说明**:\n\u003e *   所有模型的 `API_KEY` 字段均支持填写多个密钥，用逗号 `,` 分隔，程序会从中随机选择一个使用。\n\u003e *   对于除内容压缩模型外的其他模型，如果将特定模型的配置项（如 `SEARCH_KEYWORD_API_KEY`, `SEARCH_KEYWORD_API_URL` 等）留空，系统将默认使用 `BASE_CHAT_*` 的配置。\n\u003e *   `API_TYPE` 字段用于指定 API 格式，留空默认为 `OPENAI` 格式,除内容压缩模型,其余暂不支持Gemini格式(Gemini有OpenAI兼容模式[OpenAI 兼容性  | Gemini API  | Google AI for Developers](https://ai.google.dev/gemini-api/docs/openai?hl=zh-cn))。\n\n以下是关键配置项的详细说明：\n\n#### **基础配置**\n*   `API_KEY`: 访问本项目 API 服务时所需的授权密钥。\n\n#### **搜索引擎配置**\n\u003e 优先使用 `SearXNG`，当 `SearXNG` 请求失败时，会自动切换到 `Tavily`。\n\n* `SEARXNG_URL`: 自建 或 公共 SearXNG 实例，**必须支持 JSON 格式输出**。 \n\n  \n\n* `TAVILY_KEY`: Tavily 服务的 API 密钥。\n\n* `TAVILY_MAX_NUM`: 使用 Tavily 搜索时，返回结果的最大数量 建议`20`。\n\n  \n\n  \u003e `SEARCH_API_LIMIT`: 限制搜索引擎 API 的并发请求数，请根据您使用的服务商限制进行设置。\n\n#### **网页爬虫配置 (至少配置一个)**\n\u003e 如果全部配置,优先级FireCrawl\u003eCrawl4ai\u003eJina\n\n* `FIRECRAWL_API_URL`: FireCrawl 服务的 URL。如果使用官方 API，此项可留空。\n\n* `FIRECRAWL_API_KEY`: FireCrawl 服务的 API 密钥。本地部署时若未设置可留空，使用官方 API 则必须填写。\n\n  \n\n* `CRAWL4AI_API_URL`: Crawl4AI 服务的 URL。\n\n  \n\n* `JINA_API_URL`: Jina 服务的URL (官方提供免费版,详见 https://jina.ai/reader/ )\n\n*   `JINA_API_KEY`: Jina 服务的API 密钥\n\n#### **搜索与研究参数**\n*   `CRAWL_THREAD_NUM`: 抓取网页时的并发任务数。建议根据网络和服务器性能适当调低以提高成功率（例如，FireCrawl 官方免费版限制为 10次/分钟）。\n*   `MAX_SEARCH_RESULTS`: 普通搜索模式下，单次搜索最多处理的网页数量。\n*   `MAX_DEEPRESEARCH_RESULTS`: 深度研究模式下，每次迭代最多处理的网页数量，不建议设置过大 建议`3`。\n*   `MAX_STEPS_NUM`: 深度研究模式下的最大迭代次数 建议 `12`。\n\n#### **大模型 (LLM) 配置**\n\n*   **基础对话模型 (必须配置)**\n    \u003e 用于处理用户交互和工具调用，**模型需要支持 Function Calling**。\n    *   `BASE_CHAT_API_KEY`: API 密钥。\n    *   `BASE_CHAT_API_URL`: API 地址。\n    *   `BASE_CHAT_MODEL`: 模型名称。\n\n*   **搜索关键词生成模型 (必须配置)**\n    \n    *   `SEARCH_KEYWORD_API_KEY`, `SEARCH_KEYWORD_API_URL`, `SEARCH_KEYWORD_MODEL`\n    \u003e SEARCH_KEYWORD_MODEL 最好使用性能较好并且拥有长上下文处理能力的模型\n    \n*   **搜索结果评估模型 (必须配置)**\n    \n    *   `EVALUATE_THREAD_NUM`: 评估网页价值时的并发任务数。\n    *   `EVALUATE_API_KEY`, `EVALUATE_API_URL`, `EVALUATE_MODEL`\n    \n*   **网页内容压缩模型 (必须配置)**\n    \n    \u003e 建议选择支持长上下文、响应速度快的模型。\n    *   `COMPRESS_API_TYPE`: 指定 API 格式，如 `GEMINI` 或 `OPENAI`。\n    *   `COMPRESS_API_KEY`: API 密钥。若使用 Gemini，建议至少提供两个密钥以避免速率限制问题。\n    *   `COMPRESS_API_URL`: API 地址。\n    *   `COMPRESS_MODEL`: 模型名称。\n    \n*   **最终总结生成模型 (必须配置)**\n    \n    *   `SUMMARY_API_TYPE`, `SUMMARY_API_KEY`, `SUMMARY_API_URL`, `SUMMARY_MODEL`\n\n#### **4. 运行服务**\n\n一键测试所有API是否正常\n```\npython main.py --test\n```\n\n在项目根目录下运行：\n\n```bash\npython main.py\n```\n\n服务默认启动在 `http://0.0.0.0:5000`。\n\n## 🧩 外部服务依赖\n\n**搜索引擎 API (二选一)**:\n\n*   **Searxng**: [自建](https://docs.searxng.org/admin/installation-docker.html) 或使用 [公共服务器](https://searx.space/)。需开启 JSON 格式支持。\n*   **Tavily**: [Tavily 官网](https://www.tavily.com/)\n\n**网页爬虫 (三选一)**:\n\n*   **FireCrawl**: [自建](https://docs.firecrawl.dev/contributing/self-host#docker-containers-fail-to-start) 或使用 [官方 API](https://firecrawl.dev)\n*   **Crawl4AI**: [自建](https://docs.crawl4ai.com/core/docker-deployment/)\n*   **Jina**: [官方免费API](https://jina.ai/reader/) 或者 [自建](https://github.com/intergalacticalvariable/reader)\n\n**LLM**: 大模型 API 供应商\n\n## 🛠️ API 使用示例\n\n您可以使用任何兼容 OpenAI API 格式的客户端（如 LobeChat, One-API, OpenWebui, Cherry Studio）与服务进行交互。\n\n以Cherry Studio为例\n\n![使用示例_CherryStudio](img/使用示例_CherryStudio.png)\n\n\u003e **提示**: 使用带 `deep-research` 的模型 ID 即可触发深度研究模式。支持的模型 ID 列表可通过 `/v1/models` 接口获取。\n\n## 📦 Python 库依赖\n\n*   **Flask**: Web 框架。\n*   **OpenAI Python SDK**: 与 OpenAI 兼容的 API 进行交互。\n*   **Requests**: HTTP 请求库。\n*   **BeautifulSoup4**: HTML/XML 解析。\n*   **PyMuPDF, python-docx, openpyxl**: 用于解析 PDF, DOCX, XLSX 等文件。\n*   **python-dotenv**: 加载环境变量。\n\n完整的依赖列表请查看 `requirements.txt`。\n\n## 💡 效果展示\n\n### 总结类\n\u003e prompt:获取gemini claude deepseek glm qwen全部对话模型的参数,和官方api的价格,用表格清晰的展示,我要非常完整的数据,最后总结的时候不要有遗漏\n\n\u003e 本项目效果 (除最后总结使用 Gemini 2.5 Pro, 其余均使用 2.5 Flash 模型)\n\n![模型总结1](img/模型总结1.png)\n![模型总结2](img/模型总结2.png)\n\n\u003e OpenAI 免费版本 Deepresearch 效果 (欢迎提供付费版效果示例)\n\u003e\n\u003e [查看完整对话](https://chatgpt.com/share/6856adee-76ec-8004-a601-132d43ed1dab)\n\n![模型总结-openai](img/模型总结-openai.png)\n\n### 冷门问题\n\u003e prompt:rk3399 怎么在linux下,使用qemu 的kvm加速\n\n\u003e 关于 \"RK3399 QEMU 启用 KVM\"，重点在于大小核，**需要使用 `taskset` 绑核**。\n\n![RK3399-kvm1](img/RK3399-kvm1.png)\n![RK3399-kvm2](img/RK3399-kvm2.png)\n\n\u003e OpenAI 免费版本 Deepresearch 效果\n\n![RK3399-kvm-openai](img/RK3399-kvm-openai.png)\n\n## 🤔 已知问题\n*   过早结束研究 - 发起请求时带上\"详细研究\"之类的关键词\n\n## ✍️ TODO\n\n*   更加完善的项目管理\n*   使用asyncio重构,避免超时,增强并发能力\n*   更加优秀的架构设计(目前为顺序迭代,部分任务并不适合这个模式)\n*   智能读取网页结果中的URL和图片\n*   追问\n\n\n## 🤝 贡献\n\n欢迎通过提交 Pull Requests 或 Issues 来改进本项目。您的每一个贡献都非常有价值！\n\n## 📄 开源许可\n\n本项目采用 [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) 许可证](http://creativecommons.org/licenses/by-nc-sa/4.0/)。\n\n简单来说，这意味着：\n\n*   **您可以自由地**：\n    *   **共享** — 在任何媒介以任何形式复制、发行本作品\n    *   **演绎** — 修改、转换或以本作品为基础进行创作\n*   **惟须遵守下列条件**：\n    *   **署名** — 您必须给出适当的署名，提供指向本许可的链接，并标明是否对原作品作了修改。\n    *   **非商业性使用** — 您不得将本作品用于商业目的。\n    *   **相同方式共享** — 如果您再混合、转换，或者基于本作品进行创作，您必须基于与原先许可协议相同的许可协议来分发您的贡献。\n\n\u003e 如果您希望将本项目用于商业目的，请联系作者获取商业授权。\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=cat3399/deepresearch\u0026Date)](https://star-history.com/#cat3399/deepresearch\u0026Date)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcat3399%2Fdeepresearch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcat3399%2Fdeepresearch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcat3399%2Fdeepresearch/lists"}