Local Deep Research API使用手册：从基础调用到高级集成
Local Deep Research API使用手册：从基础调用到高级集成
【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research
Local Deep Research是一款AI驱动的研究助手，能够将复杂问题转化为全面的引用报告，通过跨多样化知识源（包括学术数据库、科学存储库、网络内容和私人文档集合）使用任何LLM进行迭代分析。本手册将帮助你从基础调用到高级集成，轻松掌握Local Deep Research API的使用方法。
一、API基础概览
Local Deep Research提供HTTP REST API和程序化Python API两种访问方式。自1.0版本起，所有API端点都需要身份验证，系统使用每个用户的加密数据库。
Local Deep Research API工作流程示意图，展示了从查询到生成报告的完整过程
1.1 核心功能
- 研究启动：提交研究查询并获取结果
- 状态查询：检查研究任务的进度
- 结果获取：获取完整的研究报告
- 设置管理：配置API行为和参数
二、快速开始：Python客户端
最简单的API使用方式是使用内置客户端，它处理所有身份验证复杂性：
from local_deep_research.api import LDRClient, quick_query # 一行代码实现快速研究 summary = quick_query("username", "password", "What is DNA?") print(summary) # 或使用客户端进行多操作 client = LDRClient() client.login("username", "password") result = client.quick_research("What is machine learning?") print(result["summary"])无需担心CSRF令牌、HTML解析或会话管理！
三、API认证指南
3.1 Web UI认证
API需要先通过Web界面进行身份验证：
启动服务器：
python -m local_deep_research.web.app在浏览器中打开 http://localhost:5000
注册新账户或登录
会话cookie将用于API认证
3.2 HTTP API认证
对于HTTP API请求，你需要：
- 首先通过登录端点进行认证
- 在后续请求中包含会话cookie
- 对于状态更改操作，包含CSRF令牌
示例认证流程：
import requests from bs4 import BeautifulSoup # 创建会话以持久化cookies session = requests.Session() # 1. 获取登录页面并提取登录用的CSRF令牌 login_page = session.get("http://localhost:5000/auth/login") soup = BeautifulSoup(login_page.text, 'html.parser') csrf_input = soup.find('input', {'name': 'csrf_token'}) login_csrf = csrf_input.get('value') if csrf_input else None # 2. 使用包含CSRF的表单数据登录（不是JSON） login_response = session.post( "http://localhost:5000/auth/login", data={ "username": "your_username", "password": "your_password", "csrf_token": login_csrf } ) if login_response.status_code in [200, 302]: print("Login successful") # 会话cookie会自动存储 else: print(f"Login failed: {login_response.text}") # 3. 获取API请求的CSRF令牌 csrf_response = session.get("http://localhost:5000/auth/csrf-token") csrf_token = csrf_response.json()["csrf_token"] # 4. 使用CSRF头进行API请求 headers = {"X-CSRF-Token": csrf_token}四、程序化API访问
程序化API现在需要设置快照以获取适当的上下文：
from local_deep_research.api import quick_summary from local_deep_research.settings import CachedSettingsManager from local_deep_research.database.session_context import get_user_db_session # 获取用户会话和设置 with get_user_db_session(username="your_username", password="your_password") as session: settings_manager = CachedSettingsManager(session, "your_username") settings_snapshot = settings_manager.get_all_settings() # 使用带有设置快照的API result = quick_summary( query="What is machine learning?", settings_snapshot=settings_snapshot, iterations=2, questions_per_iteration=3 ) print(result["summary"])五、API端点详解
5.1 研究端点
研究端点位于/api/下：
POST /api/start_research- 开始新研究GET /api/research/{id}/status- 检查研究状态GET /api/report/{id}- 获取研究结果POST /api/terminate/{id}- 停止运行中的研究
5.2 设置端点
设置端点位于/settings/api/下：
GET /settings/api- 获取所有设置GET /settings/api/{key}- 获取特定设置PUT /settings/api/{key}- 更新设置GET /settings/api/available-models- 获取可用的LLM提供商GET /settings/api/available-search-engines- 获取搜索引擎
5.3 历史端点
GET /history/api- 获取研究历史GET /history/api/{id}- 获取特定研究详情
六、完整研究流程示例
import requests import time # 设置会话并登录 session = requests.Session() session.post( "http://localhost:5000/auth/login", json={"username": "user", "password": "pass"} ) # 获取CSRF令牌 csrf = session.get("http://localhost:5000/auth/csrf-token").json()["csrf_token"] headers = {"X-CSRF-Token": csrf} # 开始研究 research = session.post( "http://localhost:5000/api/start_research", json={ "query": "Latest advances in quantum computing", "model": "gpt-3.5-turbo", "search_engines": ["arxiv", "wikipedia"], "iterations": 3 }, headers=headers ).json() research_id = research["research_id"] # 轮询结果 while True: status = session.get( f"http://localhost:5000/api/research/{research_id}/status" ).json() if status["status"] in ["completed", "failed"]: break print(f"Progress: {status.get('progress', 'unknown')}") time.sleep(5) # 获取最终结果 results = session.get( f"http://localhost:5000/api/report/{research_id}" ).json() print(f"Summary: {results['summary']}") print(f"Sources: {len(results['sources'])}")七、API最佳实践
7.1 速率限制
API包含自适应速率限制：
- 默认：每个用户每分钟60个请求
- 自动重试与指数退避
- 速率限制是基于每个用户，而不是每个IP
7.2 错误处理
常见错误响应：
401：未认证 - 需要登录403：CSRF令牌缺失或无效404：资源未找到429：超出速率限制500：服务器错误
始终检查响应状态并适当处理错误。
八、高级集成指南
8.1 自定义LLM集成
要集成自定义LLM，请参考docs/CUSTOM_LLM_INTEGRATION.md文档，了解如何扩展API以支持新的语言模型。
8.2 检索器集成
如需自定义检索器，请阅读docs/LANGCHAIN_RETRIEVER_INTEGRATION.md，了解如何将自定义检索逻辑集成到API中。
8.3 完整示例代码
查看examples/api_usage/目录获取更多完整示例，包括HTTP和程序化API使用的详细演示。
九、从v1.x迁移的重要变化
- 强制认证：所有API端点现在都需要身份验证
- 设置快照：程序化API调用需要settings_snapshot参数
- 每用户数据库：每个用户都有自己的加密数据库
- CSRF保护：状态更改请求需要CSRF令牌
- 新端点结构：研究API位于
/api/下（例如/api/start_research）
十、开始使用Local Deep Research API
要开始使用Local Deep Research API，请先克隆仓库：
git clone https://gitcode.com/gh_mirrors/lo/local-deep-research然后按照项目文档中的安装说明进行设置，即可开始探索强大的AI驱动研究能力！
无论是构建自动化研究工具，还是将智能分析能力集成到现有应用中，Local Deep Research API都能提供灵活而强大的接口，帮助你轻松实现复杂的研究任务。
【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考