LangChain + Gradio 项目部署到 Hugging Face Spaces 踩坑实录（附完整解决方案）

前言

最近把一个基于：

• LangChain
• LangGraph
• ChromaDB
• Gradio

的智能客服项目部署到了 Hugging Face Spaces。

原本以为部署会很简单，结果从依赖冲突到 Runtime Error，连续踩了不少坑。

这篇文章就把整个部署流程，以及我遇到的问题和解决方案完整记录一下，后面再部署 AI Web 应用时应该还能用得到。

一、什么是 Hugging Face Spaces

Hugging Face Spaces 本质上是一个：

在线 AI 应用托管平台

你可以直接把：

• Gradio
• Streamlit
• Docker
• FastAPI

等项目部署上去。

部署完成后会自动生成一个公网地址。

非常适合：

• AI Demo 展示
• Agent 项目演示
• 毕设展示
• 简历项目
• 开源项目体验页

而且：

• 免费 CPU
• 支持 GPU
• 自动 HTTPS
• 自动构建

对于个人开发者来说非常方便。

二、创建 Space

进入：

https://huggingface.co/spaces

点击：

Create new Space

然后：

创建完成后会得到一个 Git 仓库。

三、上传项目

初始化 Git：

gitinit

关联远程仓库：

gitremoteaddorigin https://huggingface.co/spaces/你的用户名/你的Space名

提交代码：

gitadd.gitcommit-m"init project"gitpush origin main

上传后 Hugging Face 会自动开始构建。

四、项目结构建议

我最终采用的结构：

project/ │ ├── app.py ├── requirements.txt ├── web/ │ └── app.py ├── rag/ ├── agent/ └── data/

其中：

• 根目录 app.py 作为 Spaces 启动入口
• web/app.py 负责 Gradio 页面

五、最关键的 app.py

很多人第一次部署会忽略这一点。

我的启动文件：

""" Hugging Face Spaces 入口文件 """importosimportsys# 添加项目路径sys.path.insert(0,os.path.dirname(os.path.abspath(__file__)))# 导入 Gradio 页面fromweb.appimportdemo# 启动服务if__name__=="__main__":demo.launch(server_name="0.0.0.0",server_port=7860)

这里一定要：

demo.launch()

否则容器会直接退出。

六、第一个坑：依赖冲突

刚开始构建直接报错：

ERROR: Cannotinstallgradio and huggingface_hub<0.25.0

原因：

我 requirements.txt 写的是：

huggingface_hub<0.25.0

但：

gradio==5.0.0

要求：

huggingface_hub>=0.25.1

于是 pip 无法解析依赖。

七、第二个坑：HfFolder 导入失败

修改依赖后又报错：

ImportError:cannotimportname'HfFolder'

原因是：

最新版 huggingface_hub 已经删除了：

HfFolder

但：

gradio==5.0.0

内部还在使用。

八、最终稳定依赖版本

最后测试稳定的 requirements：

gradio==5.0.0 huggingface_hub==0.25.2 langchain-core>=0.3.0 langchain-openai>=0.2.0 langgraph>=0.2.0 chromadb==0.5.5 fastapi uvicorn pypdf loguru python-dotenv openai requests dashscope audioop-lts

重点：

huggingface_hub==0.25.2

这个版本兼容最好。

九、第三个坑：Container 自动退出

日志显示：

Exit code: 0

没有任何报错。

但应用就是打不开。

原因：

程序执行完直接结束了。

因为：

fromweb.appimportdemo

只是导入页面。

并不会真正启动服务。

必须：

demo.launch()

Gradio 服务才会持续运行。

十、最终效果

部署完成后：

• 自动生成公网链接
• 支持 HTTPS
• 可以直接在线访问 Agent
• 可以作为项目演示页

对于：

• AI 应用
• LangChain 项目
• RAG 系统
• Agent Demo

来说非常方便。

总结

这次部署最大的感受：

AI 项目真正难的不是“写功能”，而是“环境兼容”。

尤其：

• Python 版本
• huggingface_hub
• Gradio
• LangChain
• chromadb

这些库更新非常快。

一旦版本组合不对，就会出现各种奇怪问题。

目前我测试下来最稳的组合：

后面如果继续完善，我准备把：

• MCP
• 多 Agent
• 工具调用
• RAG
• 长期记忆

这些功能也逐步整合进去。

毕竟 Hugging Face Spaces 确实很适合做 AI Demo 展示。