KTransformers 服务端 Web 前端构建实战从 npm 编译到 /web 静态挂载的完整链路【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformersKTransformers 的推理服务不仅提供 Chat Completion / Assistant 等 API还内置了一个基于 Vue 3 的 Web 前端页面用户可以在浏览器中直接进行对话、管理模型与查看运行状态。本篇技术指南聚焦 doc/zh/api/server/website.md 所讲解的 Web 服务启动流程如何准备 Node.js 环境、编译前端代码并将产物打包进 ktransformers 安装包并结合仓库源码深入剖析前端静态资源是如何被 FastAPI 服务挂载到/web路由、以及前端请求地址如何被自动对齐到服务端口的。读完本文你可以独立完成 Web 前端的编译、打包与部署并理解其背后的挂载机制与配置联动逻辑。一、Web 前端在 KTransformers 中的定位KTransformers 的 server 采用分层设计API 层同时暴露 Ollama / OpenAI 兼容接口与 Web API后端通过 Backend Interface 调度 Transformers、ExLlamaV2 等推理框架模型与会话数据由 sqlite 持久化对应archive/ktransformers/server/下的 api、backend、models 等模块。其中 Web API 分支服务的对象正是本文的主角——website/目录下的 Vue 单页应用。从源码结构看当前仓库将这套 Web 前端代码存放在归档目录中存在两个副本archive/ktransformers/website/主推理服务对应的前端archive/kt-sft/ktransformers/website/kt-sft 版本对应的前端。而文档 doc/zh/api/server/website.md 中使用的ktransformers/website路径对应的是旧版目录布局操作顺序与当前仓库的归档结构一致只是目录前缀不同。下文命令请以仓库实际路径为准。1.1 前端技术栈概览查看 package.json 可以确认前端的完整技术栈与构建方式类别依赖作用框架vue ^3.4.27、vue-router、vuex、vue-i18nVue 3 单页应用骨架与国际化UI 组件ant-design-vue、element-plus页面组件库图表apexcharts、vue3-apexcharts运行指标可视化网络axios、axios-extensions、websocket与后端 REST / WebSocket 通信文档pdfobject、vue-pdf、marked模型卡片 PDF 渲染与 Markdown 展示构建vue/cli-service ~5.0.0、webpack ^5.91.0、typescript ~4.5.5开发服务与生产构建package.json中定义的 npm scripts 也直接印证了文档中的两条命令scripts: { serve: vue-cli-service serve, build: vue-cli-service build, test:unit: vue-cli-service test:unit, lint: vue-cli-service lint }即npm run build实际执行的是vue-cli-service build产物输出到默认的dist/目录——这正是后端服务读取静态资源的目录见第三节。二、环境准备Node.js 版本要求与安装2.1 版本要求文档明确要求编译 Web 代码之前必须安装Node.js 18.3 或更高版本。这一点很重要因为前端工程使用了 Vue 3 Webpack 5 TypeScript 4.5 工具链对 Node 版本的最低要求高于许多发行版软件源提供的旧版本。针对 Ubuntu / Debian 用户的注意事项见英文版文档 doc/en/api/server/website.md 的补充说明Ubuntu / Debian 软件仓库中的 Node.js 版本过低会导致编译报错。官方建议先卸载旧版本再通过 Nodesource 官方源安装# 卸载系统自带的旧版本 nodejs / npm sudo apt-get remove nodejs npm -y sudo apt-get autoremove -y sudo apt-get update -y sudo apt-get install -y apt-transport-https ca-certificates curl gnupg curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg sudo chmod 644 /usr/share/keyrings/nodesource.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_23.x nodistro main | sudo tee /etc/apt/sources.list.d/nodesource.list sudo apt-get update -y sudo apt-get install nodejs -y注意上述脚本会安装 node_23.x 大版本的 Node.js满足 18.3 的要求。如果你已通过 nvm 等工具管理 Node 版本只需确保node -v输出不低于 v18.3 即可跳过此步骤。2.2 安装依赖并安装 Vue CLI进入 Web 前端目录旧版布局为ktransformers/website当前仓库归档路径为archive/ktransformers/websitecd ktransformers/website安装 Vue CLInpm install vue/cli这里需要留意一个细节vue/cli ^5.0.8本身就声明在 package.json 的dependencies中因此执行npm install安装项目依赖时也会一并引入 CLI文档中单独执行npm install vue/cli是为了确保vue-cli-service命令可用作为兜底操作没有副作用。三、编译前端并打包进 ktransformers3.1 执行生产构建依赖就绪后执行构建npm run buildvue-cli-service build会由 Webpack 5 完成 TypeScript / Vue SFC 编译、资源打包与压缩产出位于website/dist/目录。构建产物的入口是 index.html其第 7 行引入了一个关键的运行时配置脚本script src./config.js/script该 config.js 位于website/public/下会在构建时被原样拷贝进dist/。前端启动时读取其中的localhost:端口形式地址作为访问后端 API 的基址——这与下一节后端的自动改写逻辑直接呼应。3.2 将前端产物随 ktransformers 一起安装文档给出的最后一步是回到仓库根目录执行完整安装cd ../../ pip install .这一步的意义在于pip install .会把 Python 包含 server 与 website/dist 静态资源一起装入 site-packages之后启动 server 时即可直接访问/web页面而无需额外的静态服务器。若前端未编译服务启动会直接失败原因见下一节的源码分析。四、源码深潜/web 静态挂载与端口自动对齐4.1 mount_index_routes静态资源挂载与失败兜底Web 前端的“上线”逻辑集中在 archive/ktransformers/server/main.py 的mount_index_routes函数中def mount_index_routes(app: FastAPI): project_dir os.path.dirname(os.path.dirname(__file__)) web_dir os.path.join(project_dir, website/dist) web_config_file os.path.join(web_dir, config.js) update_web_port(web_config_file) if os.path.exists(web_dir): app.mount(/web, StaticFiles(directoryweb_dir), namestatic) else: err_str fNo website resources in {web_dir}, please complile the website by npm first logger.error(err_str) print(err_str) exit(1)从源码可以确认三个关键事实静态目录定位服务以 server 包上一级目录为基准查找website/dist。因此npm run build必须在 website 目录内执行、且 dist 必须最终随 pip 包分发/web路由才能生效失败即退出若dist/不存在服务打印please complile the website by npm first并exit(1)。这就是文档坚持“先编译、后pip install .”这一顺序的根本原因——Web 前端不是可选组件而是服务启动的硬依赖挂载路径FastAPI 通过app.mount(/web, StaticFiles(...))将整个 dist 目录挂载到/web因此浏览器访问形如http://host:port/web/的地址即可加载前端页面。4.2 update_web_port前端地址与后端端口的自动对齐紧接着 main.py 中的update_web_port函数在每次挂载前会执行一次运行时配置改写def update_web_port(config_file: str): ip_port_pattern ( r(localhost|((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)):[0-9]{1,5} ) with open(config_file, r, encodingutf-8) as f_cfg: web_config f_cfg.read() ip_port localhost: str(Config().server_port) new_web_config re.sub(ip_port_pattern, ip_port, web_config) with open(config_file, w, encodingutf-8) as f_cfg: f_cfg.write(new_web_config)其工作原理是用正则匹配config.js中所有IP:端口形式的地址支持 localhost 与任意 IPv4将它们统一替换为localhost:server_port其中server_port取自服务端配置见 config.pyself.server_port self.server.get(port, 9016)即服务端口由配置文件server段的port字段决定缺省为9016。这套机制解决了前端工程化中的一个经典难题静态页面的 API 基址在构建期是写死的而部署期的服务端口可能变化。KTransformers 选择在每次启动时动态改写 dist 内的 config.js保证无论用户把服务跑在哪个端口前端页面的请求地址始终与后端一致无需重新编译。4.3 端到端流程小结把文档命令与源码行为串起来完整的调用链是npm install vue/cli/npm install安装 package.json 声明的 Vue 3 依赖npm run build执行vue-cli-service build产出website/dist/含index.html与运行时config.jspip install .将 Python 包连同 dist 一并分发启动 server 时mount_index_routes检查website/dist存在性缺失则报错退出存在则调用update_web_port将前端配置对齐到Config().server_port默认 9016再通过app.mount(/web, StaticFiles(...))对外暴露浏览器访问http://localhost:server_port/web/即可进入 Web 界面页面经config.js中的地址回连后端的 Chat Completion / Assistant / Web API。五、常见问题与验证要点服务启动即退出并提示 “No website resources ... please complile the website by npm first”website/dist不存在或未随 pip 包分发。回到 website 目录执行npm run build后重新安装即可对应 main.py 的兜底分支。编译报错且 Node 版本低于 18.3按第二节方法从 Nodesource 源升级 Node.js不要使用发行版软件源中的旧版。页面能打开但请求失败检查浏览器实际访问端口与server配置中的port是否一致正常情况下update_web_port已保证 config.js 与后端端口对齐若手动修改过 dist 内的 config.js 需注意保持localhost:port格式。验证编译产物构建完成后确认website/dist/中存在index.html与config.js即可按文档流程继续pip install .。参考路径本文主体文档doc/zh/api/server/website.md英文版补充说明doc/en/api/server/website.md前端工程配置package.json、public/index.html、public/config.js静态挂载与端口改写实现server/main.py服务端口默认值server/config/config.py【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 KTransformers 服务端 Web 前端构建实战：从 npm 编译到 /web 静态挂载的完整链路
KTransformers 服务端 Web 前端构建实战从 npm 编译到 /web 静态挂载的完整链路【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformersKTransformers 的推理服务不仅提供 Chat Completion / Assistant 等 API还内置了一个基于 Vue 3 的 Web 前端页面用户可以在浏览器中直接进行对话、管理模型与查看运行状态。本篇技术指南聚焦 doc/zh/api/server/website.md 所讲解的 Web 服务启动流程如何准备 Node.js 环境、编译前端代码并将产物打包进 ktransformers 安装包并结合仓库源码深入剖析前端静态资源是如何被 FastAPI 服务挂载到/web路由、以及前端请求地址如何被自动对齐到服务端口的。读完本文你可以独立完成 Web 前端的编译、打包与部署并理解其背后的挂载机制与配置联动逻辑。一、Web 前端在 KTransformers 中的定位KTransformers 的 server 采用分层设计API 层同时暴露 Ollama / OpenAI 兼容接口与 Web API后端通过 Backend Interface 调度 Transformers、ExLlamaV2 等推理框架模型与会话数据由 sqlite 持久化对应archive/ktransformers/server/下的 api、backend、models 等模块。其中 Web API 分支服务的对象正是本文的主角——website/目录下的 Vue 单页应用。从源码结构看当前仓库将这套 Web 前端代码存放在归档目录中存在两个副本archive/ktransformers/website/主推理服务对应的前端archive/kt-sft/ktransformers/website/kt-sft 版本对应的前端。而文档 doc/zh/api/server/website.md 中使用的ktransformers/website路径对应的是旧版目录布局操作顺序与当前仓库的归档结构一致只是目录前缀不同。下文命令请以仓库实际路径为准。1.1 前端技术栈概览查看 package.json 可以确认前端的完整技术栈与构建方式类别依赖作用框架vue ^3.4.27、vue-router、vuex、vue-i18nVue 3 单页应用骨架与国际化UI 组件ant-design-vue、element-plus页面组件库图表apexcharts、vue3-apexcharts运行指标可视化网络axios、axios-extensions、websocket与后端 REST / WebSocket 通信文档pdfobject、vue-pdf、marked模型卡片 PDF 渲染与 Markdown 展示构建vue/cli-service ~5.0.0、webpack ^5.91.0、typescript ~4.5.5开发服务与生产构建package.json中定义的 npm scripts 也直接印证了文档中的两条命令scripts: { serve: vue-cli-service serve, build: vue-cli-service build, test:unit: vue-cli-service test:unit, lint: vue-cli-service lint }即npm run build实际执行的是vue-cli-service build产物输出到默认的dist/目录——这正是后端服务读取静态资源的目录见第三节。二、环境准备Node.js 版本要求与安装2.1 版本要求文档明确要求编译 Web 代码之前必须安装Node.js 18.3 或更高版本。这一点很重要因为前端工程使用了 Vue 3 Webpack 5 TypeScript 4.5 工具链对 Node 版本的最低要求高于许多发行版软件源提供的旧版本。针对 Ubuntu / Debian 用户的注意事项见英文版文档 doc/en/api/server/website.md 的补充说明Ubuntu / Debian 软件仓库中的 Node.js 版本过低会导致编译报错。官方建议先卸载旧版本再通过 Nodesource 官方源安装# 卸载系统自带的旧版本 nodejs / npm sudo apt-get remove nodejs npm -y sudo apt-get autoremove -y sudo apt-get update -y sudo apt-get install -y apt-transport-https ca-certificates curl gnupg curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg sudo chmod 644 /usr/share/keyrings/nodesource.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_23.x nodistro main | sudo tee /etc/apt/sources.list.d/nodesource.list sudo apt-get update -y sudo apt-get install nodejs -y注意上述脚本会安装 node_23.x 大版本的 Node.js满足 18.3 的要求。如果你已通过 nvm 等工具管理 Node 版本只需确保node -v输出不低于 v18.3 即可跳过此步骤。2.2 安装依赖并安装 Vue CLI进入 Web 前端目录旧版布局为ktransformers/website当前仓库归档路径为archive/ktransformers/websitecd ktransformers/website安装 Vue CLInpm install vue/cli这里需要留意一个细节vue/cli ^5.0.8本身就声明在 package.json 的dependencies中因此执行npm install安装项目依赖时也会一并引入 CLI文档中单独执行npm install vue/cli是为了确保vue-cli-service命令可用作为兜底操作没有副作用。三、编译前端并打包进 ktransformers3.1 执行生产构建依赖就绪后执行构建npm run buildvue-cli-service build会由 Webpack 5 完成 TypeScript / Vue SFC 编译、资源打包与压缩产出位于website/dist/目录。构建产物的入口是 index.html其第 7 行引入了一个关键的运行时配置脚本script src./config.js/script该 config.js 位于website/public/下会在构建时被原样拷贝进dist/。前端启动时读取其中的localhost:端口形式地址作为访问后端 API 的基址——这与下一节后端的自动改写逻辑直接呼应。3.2 将前端产物随 ktransformers 一起安装文档给出的最后一步是回到仓库根目录执行完整安装cd ../../ pip install .这一步的意义在于pip install .会把 Python 包含 server 与 website/dist 静态资源一起装入 site-packages之后启动 server 时即可直接访问/web页面而无需额外的静态服务器。若前端未编译服务启动会直接失败原因见下一节的源码分析。四、源码深潜/web 静态挂载与端口自动对齐4.1 mount_index_routes静态资源挂载与失败兜底Web 前端的“上线”逻辑集中在 archive/ktransformers/server/main.py 的mount_index_routes函数中def mount_index_routes(app: FastAPI): project_dir os.path.dirname(os.path.dirname(__file__)) web_dir os.path.join(project_dir, website/dist) web_config_file os.path.join(web_dir, config.js) update_web_port(web_config_file) if os.path.exists(web_dir): app.mount(/web, StaticFiles(directoryweb_dir), namestatic) else: err_str fNo website resources in {web_dir}, please complile the website by npm first logger.error(err_str) print(err_str) exit(1)从源码可以确认三个关键事实静态目录定位服务以 server 包上一级目录为基准查找website/dist。因此npm run build必须在 website 目录内执行、且 dist 必须最终随 pip 包分发/web路由才能生效失败即退出若dist/不存在服务打印please complile the website by npm first并exit(1)。这就是文档坚持“先编译、后pip install .”这一顺序的根本原因——Web 前端不是可选组件而是服务启动的硬依赖挂载路径FastAPI 通过app.mount(/web, StaticFiles(...))将整个 dist 目录挂载到/web因此浏览器访问形如http://host:port/web/的地址即可加载前端页面。4.2 update_web_port前端地址与后端端口的自动对齐紧接着 main.py 中的update_web_port函数在每次挂载前会执行一次运行时配置改写def update_web_port(config_file: str): ip_port_pattern ( r(localhost|((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)):[0-9]{1,5} ) with open(config_file, r, encodingutf-8) as f_cfg: web_config f_cfg.read() ip_port localhost: str(Config().server_port) new_web_config re.sub(ip_port_pattern, ip_port, web_config) with open(config_file, w, encodingutf-8) as f_cfg: f_cfg.write(new_web_config)其工作原理是用正则匹配config.js中所有IP:端口形式的地址支持 localhost 与任意 IPv4将它们统一替换为localhost:server_port其中server_port取自服务端配置见 config.pyself.server_port self.server.get(port, 9016)即服务端口由配置文件server段的port字段决定缺省为9016。这套机制解决了前端工程化中的一个经典难题静态页面的 API 基址在构建期是写死的而部署期的服务端口可能变化。KTransformers 选择在每次启动时动态改写 dist 内的 config.js保证无论用户把服务跑在哪个端口前端页面的请求地址始终与后端一致无需重新编译。4.3 端到端流程小结把文档命令与源码行为串起来完整的调用链是npm install vue/cli/npm install安装 package.json 声明的 Vue 3 依赖npm run build执行vue-cli-service build产出website/dist/含index.html与运行时config.jspip install .将 Python 包连同 dist 一并分发启动 server 时mount_index_routes检查website/dist存在性缺失则报错退出存在则调用update_web_port将前端配置对齐到Config().server_port默认 9016再通过app.mount(/web, StaticFiles(...))对外暴露浏览器访问http://localhost:server_port/web/即可进入 Web 界面页面经config.js中的地址回连后端的 Chat Completion / Assistant / Web API。五、常见问题与验证要点服务启动即退出并提示 “No website resources ... please complile the website by npm first”website/dist不存在或未随 pip 包分发。回到 website 目录执行npm run build后重新安装即可对应 main.py 的兜底分支。编译报错且 Node 版本低于 18.3按第二节方法从 Nodesource 源升级 Node.js不要使用发行版软件源中的旧版。页面能打开但请求失败检查浏览器实际访问端口与server配置中的port是否一致正常情况下update_web_port已保证 config.js 与后端端口对齐若手动修改过 dist 内的 config.js 需注意保持localhost:port格式。验证编译产物构建完成后确认website/dist/中存在index.html与config.js即可按文档流程继续pip install .。参考路径本文主体文档doc/zh/api/server/website.md英文版补充说明doc/en/api/server/website.md前端工程配置package.json、public/index.html、public/config.js静态挂载与端口改写实现server/main.py服务端口默认值server/config/config.py【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考