GPT Academic 部署与自定义实战：从三级配置体系到快捷按钮与函数插件扩展

GPT Academic 部署与自定义实战：从三级配置体系到快捷按钮与函数插件扩展

【免费下载链接】gpt_academic为GPT/GLM等LLM大语言模型提供实用化交互接口，特别优化论文阅读/润色/写作体验，模块化设计，支持自定义快捷按钮&函数插件，支持Python和C++等项目剖析&自译解功能，PDF/LaTex论文翻译&总结功能，支持并行问询多种LLM模型，支持chatglm3等本地模型。接入通义千问, deepseekcoder, 讯飞星火, 文心一言, llama2, rwkv, claude2, moss等。项目地址: https://gitcode.com/GitHub_Trending/gp/gpt_academic

本篇技术指南以 GPT Academic（gpt_academic）项目的法语版 README（docs/README.French.md）为主线，完整覆盖项目安装（直接运行与 Docker 两种路径）、config.py配置体系、快捷按钮（core_functional）定制与函数插件（crazy_functions）扩展四大主题。读完本文，你将能够独立完成该项目的部署与模型接入，并在源码层面理解“前缀/后缀按钮”“插件热重载”“环境变量覆写配置”等机制的实现原理。

一、项目定位与核心能力

GPT Academic 是一个面向 GPT/GLM 等大语言模型的实用化交互接口，特别优化论文阅读、润色与写作体验。其法语版 README 开头的功能矩阵概括了项目的核心卖点，这些功能在当前仓库中均有对应实现：

需要说明的是，README（含法语版）中的版本动态截至 3.70 系列；而当前仓库 version 文件显示版本号为4.00，新增特性为“优化文件对话使用逻辑、新增速读论文”。因此本文中的配置项、模型列表等以后文“源码实际内容”为准，README 中出现的旧模型名（如api2d-gpt-4）仅为历史记载。

法语版 README 还特别提醒：本项目可用multi_language.py将整个项目翻译成任意语言（实验性功能）。该脚本读取 config.py 中的LLM_MODEL与API_KEY，将界面文本通过 LLM 翻译后输出到multi-language/<语言>/目录，翻译映射缓存于docs/translation_xxxx.json（如 docs/translate_english.json）。仓库中已有的法语版 README 正是这一机制的产物，文档本身也注明“由 GPT 翻译，请仔细核对”。

二、安装与运行

2.1 方法一：直接运行（Windows / Linux / macOS）

步骤 1：获取项目代码

git clone --depth=1 https://gitcode.com/GitHub_Trending/gp/gpt_academic cd gpt_academic

步骤 2：配置 API_KEY

在 config.py 中填写 API KEY。README 强调：安装依赖时务必选择requirements.txt中指定的版本，安装命令为pip install -r requirements.txt。

步骤 3：安装依赖

# 方式一：直接使用 pip（python>=3.9） python -m pip install -r requirements.txt # 方式二：使用 Anaconda conda create -n gptac_venv python=3.11 conda activate gptac_venv python -m pip install -r requirements.txt

从源码看，版本锁定并非建议而是硬性要求：requirements.txt 第 1 行直接以 wheel 链接锁定了gradio-3.32.15，而 main.py 启动时会显式校验 Gradio 版本：

import gradio as gr if gr.__version__ not in ['3.32.15']: raise ModuleNotFoundError("使用项目内置Gradio获取最优体验! 请运行 `pip install -r requirements.txt` ...")

这与 README“已知问题”一节相互印证：Gradio 官方存在较多兼容性问题，必须使用项目锁定的版本。此外requirements.txt中还包含pymupdf、scipdf_parser、dashscope、llama-index-core等，分别支撑 PDF 解析、通义千问接入与 RAG 向量库等插件能力。

步骤 4：运行

python main.py

运行后程序会在 main.py 中启动三个后台线程：自动更新检查（check_proxy.py中的auto_update）、tiktoken 模块预热、自动打开浏览器；最后经由 shared_utils/fastapi_server.py 的start_app启动服务。端口由WEB_PORT配置决定，-1表示随机选取空闲端口。

2.2 本地模型可选依赖

若需要以清华 ChatGLM、复旦 MOSS、RWKV 等作为后端，需要额外安装依赖（前提：熟悉 Python 与 PyTorch、机器配置充足）：

# [可选步骤一] 支持清华 ChatGLM python -m pip install -r request_llms/requirements_chatglm.txt # [可选步骤二] 支持复旦 MOSS python -m pip install -r request_llms/requirements_moss.txt git clone --depth=1 <MOSS 仓库地址> request_llms/moss # 需在项目根目录执行

README 还给出了两条排错提示：若报“Call ChatGLM generated an error and cannot load the parameters”，一是默认安装为 torch CPU 版，用 CUDA 需重装 torch+cuda；二是显存不足时可把 request_llms/bridge_chatglm.py 中加载的THUDM/chatglm-6b改为THUDM/chatglm-6b-int4量化版本。当前仓库的本地模型相关配置还包括CHATGLM_LOCAL_MODEL_PATH、LOCAL_MODEL_DEVICE（cpu/cuda）、LOCAL_MODEL_QUANT（FP16/INT4/INT8）等，见 config.py。

2.3 方法二：Docker 部署

docker-compose.yml 提供了「方案零」到「方案五」共 6 个部署方案，使用前只需保留其中一个方案并修改其environment环境变量：

端口暴露支持两种方法（方案头部注释中有说明）：network_mode: "host"（与宿主网络融合，默认配置，Linux 专用）或ports: - "12345:12345"（端口映射，需先删除network_mode: "host"，且映射端口必须与WEB_PORT环境变量一致）。需要显卡时启用runtime: nvidia与/dev/nvidia0设备映射，并关注LOCAL_MODEL_DEVICE=cuda。选定方案后执行：

docker-compose up

Docker 方式下所有配置都通过environment注入，这正是 README 强调“环境变量 > config_private.py > config.py”优先级在容器场景的实际体现（修改docker-compose.yml等价于修改容器内环境变量）。

2.4 方法三：其他部署方式

• Windows 一键脚本：不熟悉 Python 环境的用户可使用 Release 页的一键运行脚本（无本地模型版本，由 oobabooga 贡献）。
• 子路径运行：如需要在http://localhost/subpath下运行，设置 config.py 的CUSTOM_PATH，详见 docs/WithFastapi.md。
• 第三方 API/Azure/文心/星火：配置方法见 config.py 尾部注释中的“配置关联关系示意图”，例如 Azure 需要AZURE_ENDPOINT/AZURE_API_KEY/AZURE_ENGINE三项配套。

三、配置体系深度解析：环境变量、config_private.py 与 config.py

README 给出的配置读取优先级为：环境变量 > config_private.py > config.py。这一机制的完整实现位于 shared_utils/config_loader.py 的read_single_conf_with_lru_cache：

# 优先级1. 获取环境变量作为配置 default_ref = getattr(importlib.import_module('config'), arg) # 读取默认值作为类型转换参考 r = read_env_variable(arg, default_ref) except: try: # 优先级2. 获取config_private中的配置 r = getattr(importlib.import_module('config_private'), arg) except: # 优先级3. 获取config中的配置 r = getattr(importlib.import_module('config'), arg)

由此可以得出几个实操要点：

1. 推荐做法：在 config.py 旁边新建config_private.py，只把修改过的配置项复制进去，避免把密钥写进会被git pull覆盖的公共文件。程序启动时先检查config_private.py是否存在并用其覆写config.py中的同名配置。
2. 环境变量两种写法：既可写USE_PROXY=True，也可写带前缀的GPT_ACADEMIC_USE_PROXY=True（见 shared_utils/config_loader.py 的注释示例）。变量值会按config.py中默认值的类型自动转换：bool只接受True/False字面量，dict/list则按 Python 字面量解析（如proxies写成{"http": "http://127.0.0.1:10085"}）。
3. 启动时的自检日志：读取API_KEY时会通过 shared_utils/key_pattern_manager.py 的is_any_api_key校验密钥是否匹配已知格式（OpenAI/Azure 等），不匹配会在控制台红字告警；读取proxies时会检查USE_PROXY是否为 True，防止代理配置“单独起作用”。
4. API_KEY 支持多密钥：API_KEY = "openai-key1,openai-key2,azure-key3"，用英文逗号分隔，用于多密钥负载均衡；也可在界面输入区临时输入密钥并回车提交生效（刷新网页后失效）。

3.1 关键配置项速查

结合 config.py 当前实际内容，常用配置项如下：

LLM_MODEL必须存在于AVAIL_LLM_MODELS这一约束在 main.py 中有兜底处理：若不在列表中会自动追加，保证下拉菜单不报错。README 提到的LAYOUT选项在 main.py 中生效——TOP-DOWN布局下CHATBOT_HEIGHT会减半用于上下分栏。

四、自定义快捷按钮（学术快捷键）

README“Utilisation avancée”第一部分讲的是最轻量的定制方式：编辑 core_functional.py 添加条目，重启程序后新按钮即出现在“基础功能区”。文档给出的示例（法语版原文）：

"Traduction avancée de l'anglais vers le français": { # 前缀，加在你的输入之前，例如描述你的要求（翻译、解释代码、润色等） "Prefix": "Veuillez traduire le contenu suivant en français, puis expliquez chaque terme ...", # 后缀，加在你的输入之后，例如配合前缀用引号包住内容 "Suffix": "", },

对照当前 core_functional.py 的实现，每个按钮是一个字典，支持以下键（以“学术语料润色”按钮为例，见 core_functional.py）：

按钮的触发链路在 main.py 中注册：每个基础功能按钮的click事件都绑定ArgsGeneralWrapper(predict)，并通过gr.State(k)把按钮名传入后端；后端在 core_functional.py 的handle_core_functionality中拼接Prefix + inputs + Suffix。该函数每次都会importlib.reload(core_functional)，所以 README 所说“若按钮已存在，前缀/后缀可热修改而无需重启程序”在源码上是成立的——改提示词即时生效，但新增按钮仍需重启（因为按钮控件本身在main.py构建界面时静态生成）。

界面中另有NUM_CUSTOM_BASIC_BTN（默认 4）个“自定义按钮”占位，其前缀/后缀保存在浏览器 cookie 中，无需改代码即可通过界面增改，这与 README“按钮读取core_functional.py动态生成、可添加自定义功能”的描述一致。

五、自定义函数插件（crazy_functions 扩展）

README“Utilisation avancée”第二部分介绍重量级扩展方式：编写函数插件（function plugin）完成任意任务，只要具备 Python 基础知识即可借助官方模板实现。插件的注册表位于 crazy_functional.py：

function_plugins = { "虚空终端": { "Group": "对话|编程|学术|智能体", # 插件分组，'|' 表示多分组 "Color": "stop", # 按钮颜色 "AsButton": True, # False 时仅出现在“更多函数插件”下拉菜单 "Info": "使用自然语言实现您的想法", # 按钮悬停提示 "Function": HotReload(Void_Terminal), # 插件实现函数 }, ... }

两个关键机制：

1. 热更新（HotReload）：所有插件函数都用 toolbox.py 的HotReload装饰器包裹。它会在每次调用时检查源文件修改时间并重载模块，因此修改插件代码后无需重启服务即可生效——这正是 README 功能表中“插件热更新（mise à jour à chaud）”的实现。
2. 分组与下拉菜单：main.py 根据Group与DEFAULT_FN_GROUPS（默认['对话', '编程', '学术', '智能体']，见 config.py）决定按钮显隐；AsButton=False的插件（如“多媒体智能体”）以及带高级参数（AdvancedArgs）的插件会出现在“更多函数插件”下拉菜单中，通过隐藏的回调按钮route（main.py）路由执行。

新插件可直接参考仓库内的模板文件 crazy_functions/高级功能函数模板.py（含高阶功能模板函数与Demo_Wrap两个范例），在 crazy_functional.py 中导入并加入function_plugins字典即可完成扩展；插件类形式的 UI 模板可参考 themes/gui_advanced_plugin_class.py。

六、版本、已知问题与工程结构

版本节奏：README 记载了从 1.0（基础功能）到 3.70 的完整版本史，其中与架构关系最大的节点包括：2.0 引入模块化函数插件、2.2 支持插件热重载、3.0 支持 ChatGLM 等本地小模型、3.1 支持多模型并行问询与多密钥负载均衡、3.50 虚空终端。当前 version 文件显示版本 4.00（“优化文件对话使用逻辑、新增速读论文”），界面标题中的版本号由 check_proxy.py 的get_current_version读取该文件得到（见 main.py）。

已知问题（README 明确列出，值得部署前知晓）：

• 某些浏览器翻译插件会干扰本项目的 Web 界面运行，建议禁用；
• Gradio 官方存在兼容性问题，务必按requirements.txt锁定版本安装（如第 2.1 节所述，main.py 会硬性校验）。

分支策略：master为主分支（稳定版），frontier为开发分支（测试版）。

自译解能力：项目可通过自身插件对任意开源项目（含自身）生成剖析报告，报告模板与示例见 docs/self_analysis.md，其中逐文件列出了config.py、main.py、toolbox.py、request_llms/*等模块的职责；界面中的“解析项目本身”按钮即调用 crazy_functions/SourceCode_Analyse.py 实现。

运行入口总览：整个系统的最小调用链为 main.py（Gradio 界面构建与事件绑定）→ shared_utils/config_loader.py（三级配置读取）→ request_llms/bridge_all.py（按LLM_MODEL路由到bridge_chatgpt.py/bridge_chatglm.py等各模型桥接层）→ shared_utils/fastapi_server.py（服务启动）。理解这条链路后，README 中提到的所有“模型切换”“临时换密钥”“主题/布局切换”行为都能在此找到落点。

【免费下载链接】gpt_academic为GPT/GLM等LLM大语言模型提供实用化交互接口，特别优化论文阅读/润色/写作体验，模块化设计，支持自定义快捷按钮&函数插件，支持Python和C++等项目剖析&自译解功能，PDF/LaTex论文翻译&总结功能，支持并行问询多种LLM模型，支持chatglm3等本地模型。接入通义千问, deepseekcoder, 讯飞星火, 文心一言, llama2, rwkv, claude2, moss等。项目地址: https://gitcode.com/GitHub_Trending/gp/gpt_academic