在任意网页中嵌入 GPT Researcher 前端：Embed Script 完整接入指南

在任意网页中嵌入 GPT Researcher 前端Embed Script 完整接入指南【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcherGPT ResearcherGPTR不仅提供完整的 NextJS 前端应用还通过官方 Embed Script 提供了一键式嵌入方案只需要两行script标签就能把最新的 GPTR 前端界面嵌入到任何 HTML 页面或现有 Web 应用中。本文将以 docs/docs/gpt-researcher/frontend/embed-script.md 为核心结合仓库内的embed.js实现、getHost地址解析逻辑与前后端代理链路讲清嵌入原理、配置参数、自定义后端地址的方法与常见排障思路。读完你将能在 5 分钟内拥有一个可独立部署、可指向任意 GPTR 后端的嵌入式研究助手界面。Embed Script 的工作原理两行脚本背后的 iframe 机制Embed Script 的核心思路非常简单——用动态创建的 iframe 把托管在https://gptr.app的 GPTR NextJS 前端应用“搬”进你的页面而脚本在插入 iframe 前会先从宿主页面的localStorage中读取你预先写好的GPTR_API_URL通过 URL 查询参数传递给 iframe 内的前端从而实现后端地址的定制。这段逻辑可以从仓库内的 frontend/nextjs/public/embed.js 源码中完整看到(function () { window.GPTResearcher { init: function () { const parentApiUrl localStorage.getItem(GPTR_API_URL); // 创建容器 const container document.createElement(div); container.id gpt-researcher-container; container.style.width 100%; container.style.height 100vh; container.style.overflow hidden; // 创建 iframe const iframe document.createElement(iframe); iframe.src https://gptr.app (parentApiUrl ? ?GPTR_API_URL parentApiUrl : ); ... }, ... }; window.GPTResearcher.init(); })();关键点包括脚本自执行embed.js加载后立即调用window.GPTResearcher.init()无需手动调用任何初始化函数默认 iframe 地址为https://gptr.app当宿主页localStorage中设置了GPTR_API_URL时会自动拼接为?GPTR_API_URL你的后端地址脚本会注入一段隐藏滚动条的样式兼容 IE/Edge、Firefox、Chrome/Safari/Opera保证嵌入式界面与宿主页面融为一体容器 id 固定为gpt-researcher-container同时脚本暴露了window.GPTResearcher.configure({ height: N })方法用于在初始化后动态调整 iframe 高度。快速开始仅需两行脚本官方接入方式非常轻量在你的 HTML 页面head或body中加入以下两行脚本即可scriptlocalStorage.setItem(GPTR_API_URL, http://localhost:8000);/script script srchttps://app.gptr.dev/embed.js/script第一行负责在宿主页面写入自定义后端地址存于localStorage第二行加载并执行嵌入脚本。这里的http://localhost:8000即 GPTR API Server 的默认监听地址与后端默认端口一致见下文。最小化 HTML 示例保存即用官方文档提供了一个极简的完整示例你可以直接将其保存为index.html并用浏览器打开验证效果!DOCTYPE html html langen head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleGPT Researcher Embed Demo/title /head body stylemargin: 0; padding: 0; !-- GPT Researcher Embed -- scriptlocalStorage.setItem(GPTR_API_URL, http://localhost:8000);/script script srchttps://app.gptr.dev/embed.js/script /body /html值得注意的是该示例依赖自定义localStorage值GPTR_API_URL来指向后端。若你的 GPTR API Server 部署在其他地址只需把http://localhost:8000替换为你的服务器地址即可无需改动任何其他代码。自定义后端地址GPTR_API_URL 的完整解析优先级为了让嵌入的 iframe 前端正确连到你的后端理解GPTR_API_URL的解析顺序至关重要。仓库内的 frontend/nextjs/helpers/getHost.ts 定义了完整的优先级链路优先级来源说明1localStorage.getItem(GPTR_API_URL)Embed Script 写入的宿主页存储值优先级最高2URL 查询参数?GPTR_API_URL...iframe 地址中携带的参数由embed.js拼接产生3环境变量NEXT_PUBLIC_GPTR_API_URLNextJS 构建期注入的环境变量4环境变量REACT_APP_GPTR_API_URLReact 应用环境变量兼容场景5默认值本地为http://localhost:8000部署到非 localhost 域名时使用https://当前hostif (apiUrlInLocalStorage) { return apiUrlInLocalStorage; } else if (apiUrlInUrlParams) { return apiUrlInUrlParams; } else if (process.env.NEXT_PUBLIC_GPTR_API_URL) { return process.env.NEXT_PUBLIC_GPTR_API_URL; } else if (process.env.REACT_APP_GPTR_API_URL) { return process.env.REACT_APP_GPTR_API_URL; } else { return host.includes(localhost) ? http://localhost:8000 : https://${host}; }这意味着即使不设置任何环境变量只要 iframe 宿主与后端同源部署前端也会自动回退到https://当前域名而通过 Embed Script 嵌入时由于 iframe 的src是https://gptr.app因此必须以localStorage优先级最高方式显式传入后端地址这正是官方示例采用该写法的原因。前后端协作链路API 代理与 WebSocket嵌入的前端并不直接调用后端的所有能力而是通过 NextJS 应用层的 API 路由进行代理这从仓库代码中可以清楚看到聊天接口 frontend/nextjs/app/api/chat/route.ts 将前端请求转发至${backendUrl}/api/chat其中backendUrl取NEXT_PUBLIC_GPTR_API_URL || http://localhost:8000报告接口 frontend/nextjs/app/api/reports/route.ts 与 frontend/nextjs/app/api/reports/[id]/route.ts 分别代理报告的创建、列表与详情读取报告追问接口 frontend/nextjs/app/api/reports/[id]/chat/route.ts 代理基于已有报告的多轮追问。而研究任务的核心通信走 WebSocket。在 frontend/nextjs/hooks/useWebSocket.ts 中前端通过getHost()解析出的地址推导 WebSocket 地址地址含https时使用wss:协议否则使用ws:随后连接${host}/ws并发送start JSON消息启动研究任务同时每 30 秒发送一次ping心跳维持连接const protocol fullHost.includes(https) ? wss: : ws: const cleanHost fullHost.replace(http://, ).replace(https://, ) const ws_uri ${protocol}//${cleanHost}/ws因此自定义后端地址时务必确保该地址同时提供 HTTP API 与/wsWebSocket 端点。后端默认监听0.0.0.0:8000由 backend/run_server.py 通过 Uvicorn 启动uvicorn server.app:app。进阶React 组件级集成方案对比如果你的宿主项目本身就是 React 应用Embed Script 并非唯一选择——仓库还提供了官方 React 组件GPTResearcher见 frontend/nextjs/src/GPTResearcher.tsx 及类型声明 frontend/nextjs/src/index.d.ts组件接口如下export interface GPTResearcherProps { apiUrl?: string; apiKey?: string; defaultPrompt?: string; onResultsChange?: (results: any) void; theme?: any; }通过npm install gpt-researcher-ui安装后即可在任意 React 应用中直接渲染并借助onResultsChange回调实时接收研究结果数据。详细的安装与私有 npm 仓库发布流程见 docs/docs/gpt-researcher/frontend/react-package.md发布命令cd frontend/nextjs npm run build:lib npm run build:types npm publish。两种方案的选择建议需要快速把研究界面嵌入静态页面、营销落地页或非 React 站点时选 Embed Script需要深度定制交互、订阅结果流、或希望打包进现有 React 组件树时选 React 组件包。常见问题与排查要点页面空白但无报错检查localStorage中GPTR_API_URL是否在embed.js加载前完成写入两行脚本顺序不能颠倒并确认后端地址可访问研究任务无响应确认后端已启动且地址正确。后端默认在0.0.0.0:8000监听backend/run_server.py可先用浏览器直接访问http://localhost:8000验证WebSocket 连接失败embed.js生成的 iframe 地址带?GPTR_API_URL...参数前端会优先从 URL 参数读取地址注意该地址需要支持/ws端点的 WebSocket 升级跨域受限若自定义后端与前端不在同源下需在后端配置允许对应来源的 CORS 与 WebSocket 握手策略。小结Embed Script 用最小的接入成本两行script让任何网页都能拥有 GPT Researcher 的完整研究界面其背后的 iframe 机制、localStorage配置传递与getHost地址解析优先级构成了整套方案的基石。无论你选择官方托管的https://gptr.app前端还是自建后端并通过GPTR_API_URL指向本文覆盖的配置链路与源码依据都能帮助你快速落地、稳定排障。【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考