记一次在Windows下部署FastAPI+LangGraph项目的踩坑实录

最新推荐文章于 2026-08-14 16:14:24 发布
原创 最新推荐文章于 2026-08-14 16:14:24 发布 · 155 阅读 · 3 ·
本内容遵循CC 4.0 BY-SA版权协议
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
GEO检测

记一次在Windows下部署FastAPI+LangGraph项目的踩坑实录

作者：技术小白
发布时间：2026-08-06
关键词：Windows、Python虚拟环境、uv、make、Docker、FastAPI、LangGraph

📌 写在前面

最近在GitHub上找到一个非常赞的项目 —— fastapi-langgraph-agent-production-ready-template，这是一个基于FastAPI和LangGraph的Agent生产级模板，集成了PostgreSQL、Redis、监控等全套基础设施。项目文档很全，但当我克隆下来准备在本地Windows环境运行调试时，却遭遇了一连串的“水土不服”。本文完整记录了我从零开始成功跑起该项目的全过程，希望给同样在Windows下折腾开源项目的你一些帮助。

🚧 环境说明

  • 操作系统：Windows 11

  • 终端工具：PowerShell（后来切换为CMD）

  • Python版本：3.12

  • Docker Desktop：已安装但未启动

  • 项目地址：fastapi-langgraph-agent-production-ready-template

💥 第一劫：source 命令无效

错误现场

powershell

PS D:\project> source .venv/bin/activate
source : 无法将“source”项识别为 cmdlet、函数、脚本文件...

原因分析

source 是Unix/Linux的shell内置命令，用于在当前shell中执行脚本（常用来激活虚拟环境）。Windows下的PowerShell和CMD均不支持该命令。

解决方案

  • 在PowerShell中，应使用：

    powershell

    .\.venv\Scripts\Activate.ps1

    如果遇到执行策略报错，先执行：

    powershell

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

  • 在CMD中，使用：

    cmd

    .venv\Scripts\activate.bat

💡 小贴士：激活成功后，命令行提示符前会出现 (.venv)，表明已在虚拟环境中。

💥 第二劫：make 命令不存在

错误现场

powershell

make install
make : 无法将“make”项识别为 cmdlet、函数、脚本文件...

原因分析

项目使用Makefile来管理构建任务（如安装依赖、启动服务等），但Windows默认没有make命令。

解决方案

  • 备选方案一：直接执行Makefile中的实质命令。通常make install对应的是pip install -r requirements.txt或pip install -e .，可以手动运行：

    cmd

    pip install -r requirements.txt

    或

    cmd

    pip install -e .

  • 备选方案二：安装Windows版make（通过Scoop或Chocolatey），然后即可直接使用make。但建议新手先采用方案一，避免额外工具依赖。

💥 第三劫：uv 命令无法识别

错误现场

powershell

uv sync
uv : 无法将“uv”项识别为 cmdlet、函数、脚本文件...

原因分析

该项目的依赖管理使用uv（一个极快的Python包管理器），但系统并未安装uv，或者虽然已通过pip install uv安装在用户目录，但可执行文件未加入系统PATH，导致终端找不到uv命令。

解决方案

我选择了最稳妥的方式：在虚拟环境中安装uv，并利用Python模块方式运行。

cmd

pip install uv
python -m uv sync

python -m uv 会直接执行uv模块，无需uv命令在PATH中。执行后看到：

text

Resolved 172 packages in 3ms
Checked 153 packages in 713ms

表明依赖安装成功。

💡 如果希望今后直接使用uv命令，可在虚拟环境内重新安装（确保python -m pip install uv），此时uv.exe会出现在.venv\Scripts下，即可直接用uv sync。

💥 第四劫：Docker Compose 环境变量未设置 & 镜像拉取失败

错误现场

cmd

docker-compose up -d
time="..." level=warning msg="The \"POSTGRES_DB\" variable is not set. Defaulting to a blank string."
...
Error response from daemon: failed to resolve reference "gcr.io/cadvisor/cadvisor:latest": ...

原因分析

  • Docker Compose依赖.env文件中的变量（如数据库账号密码），但项目提供的示例文件是.env.example，并未自动创建.env。

  • 另外，镜像gcr.io/cadvisor/cadvisor在国内无法直接拉取（网络问题），且Docker守护进程未启动也会导致连接失败。

解决方案（按顺序）

1. 启动Docker Desktop

确保Docker Desktop已启动，任务栏右下角鲸鱼图标稳定。验证：docker version。

2. 创建.env文件

将示例文件复制为.env（CMD下）：

cmd

copy .env.example .env

并检查其中是否包含必要的数据库配置，如：

text

POSTGRES_DB=myapp
POSTGRES_USER=admin
POSTGRES_PASSWORD=123456
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
3. 绕过不可拉的镜像（临时方案）

docker-compose.yml中包含了cadvisor、Prometheus、Grafana等监控组件，但这些镜像可能被墙。如果只想启动核心服务（PostgreSQL和Redis/Valkey），可以只启动这两个服务：

先查看docker-compose.yml中的服务名（通常为postgres和valkey或redis），然后执行：

cmd

docker-compose up -d postgres valkey

如果确实需要全量启动，可修改docker-compose.yml，注释掉cadvisor、prometheus、grafana块，再执行docker-compose up -d。

4. 验证运行

cmd

docker ps

看到数据库和缓存容器正常Up，即大功告成。

✅ 最终成功启动应用

完成以上步骤后，虚拟环境已就绪，依赖已安装，数据库容器已启动。最后一步：运行FastAPI应用。

cmd

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

如果项目使用Alembic等迁移工具，还需在启动前执行：

cmd

python -m alembic upgrade head

浏览器访问 http://localhost:8000/docs，看到自动生成的API文档，说明部署成功！🎉

📝 经验总结与避坑指南

  1. Unix命令不等于Windows命令：source、make等在Windows下需寻找替代或手动执行等价操作。

  2. 虚拟环境激活脚本因终端而异：PowerShell用.ps1，CMD用.bat，Git Bash可用source。

  3. Python工具链兼容性：uv虽好，但需确保其可执行文件在PATH中，或使用python -m uv方式调用。

  4. Docker Compose与.env：务必在项目根目录创建.env文件，否则Compose无法注入环境变量。

  5. 镜像拉取问题：国内用户可配置Docker镜像加速器，或暂时跳过非必需服务。

  6. 多看Makefile和README：项目作者通常会在Makefile中写明所有命令，我们只需读懂并手动翻译为Windows可执行的命令即可。

🔗 相关资源

希望这篇博客能帮助到同样在Windows下挣扎的小伙伴。如果你也有其他踩坑经历，欢迎在评论区分享交流！😊

标签
#fastapi #langchain #vllm #docker
spider_xcxc
关注
LangGraph实战：构建可调试、可监控、可演进的AI Agent
weixin_30493401的博客
06-25 623
AI Agent本质上是将人类决策闭环（意图→规划→执行→反思→修正）工程化落地的系统，其核心挑战在于状态管理、流程可控与生产稳定性。LangGraph通过图结构（DAG）和显式State机制，解决了传统提示工程和线性链式调用中的状态丢失、单点故障与不可调试等痛点，提供可中断、可分支、可监控的决策流编排能力。它不依赖复杂多Agent博弈，而是聚焦单Agent的强流程控制，兼顾低学习成本与高部署效率，特别适合金融合规、智能客服、内容审核等需确定性响应与快速迭代的业务场景。
Desktop Agent：基于LangGraph的本地智能体运行时详解
mybwu_com的专栏
06-23 608
智能体（Agent）是AI工程化落地的核心范式，其本质是具备状态管理、工具调用与任务编排能力的自主工作流。LangGraph作为面向有状态Agent的图编排框架，通过可序列化State和检查点机制，解决了传统无状态链式调用无法维持上下文的根本缺陷。结合FastAPI提供的标准化Agent Protocol接口与SQLite实现的零配置、可审计本地持久化，Desktop Agent构建出真正可嵌入开发者日常工作的轻量级本地运行时。它适用于本地知识库问答、自动化脚本集成、隐私敏感型AI应用等场景，是当前少有的开
FastAPI+LangGraph构建可生产AI工作流的工程实践
weixin_30542079的博客
07-12 388
AI工作流已从简单脚本演进为需高可靠性、强类型校验与状态持久化的生产级系统。其核心在于将HTTP协议层与业务执行层解耦：FastAPI提供自动OpenAPI文档、原生异步支持和依赖注入能力，保障接口契约性与跨团队协作效率；LangGraph则通过StateGraph实现基于TypedDict的状态驱动编排，支持条件分支、多实例状态同步与节点级可观测性。这种组合特别适用于需处理结构化中间数据（如订单ID、意图标签）、要求人工审核节点审计、以及多轮对话状态持久化的智能客服、RAG增强问答等场景。
基于FastAPI+Vue3+LangGraph的多Agent论文写作系统实战
weixin_30457551的博客
07-29 396
多Agent系统作为人工智能领域的重要分支，通过多个智能体协同工作解决复杂任务。其核心原理是将复杂问题分解为专业化子任务，各Agent通过状态管理和通信机制实现有序协作。这种架构在自然语言处理、智能写作等场景具有重要技术价值，能够显著提升任务处理的专业性和一致性。在学术论文写作场景中，多Agent系统可以分配研究分析、文献综述、方法论设计等专业化角色，确保论文结构的完整性和逻辑连贯性。本文基于LangGraph多Agent框架，结合FastAPI后端和Vue3前端，构建了一个完整的AI论文写作系统，展示了多
基于FastAPI+Vue3+LangGraph的多Agent AI论文写作系统完整实现
weixin_33713707的博客
07-29 284
多Agent系统是现代人工智能领域的重要技术架构，通过多个专业化智能体的协同工作实现复杂任务处理。其核心原理是将复杂问题分解为多个子任务，由不同Agent分工协作完成。在AI应用开发中，多Agent技术能够显著提升系统的智能水平和处理效率，特别适用于内容生成、数据分析等场景。FastAPI作为高性能Python Web框架，为多Agent系统提供稳定的API服务支持，结合Vue3构建友好的用户交互界面。本文以论文写作系统为例，详细介绍了基于LangGraph的多Agent协同架构设计，包括资料搜集、大纲生成
多Agent系统开发实战：FastAPI+Vue3+LangGraph论文写作平台搭建
weixin_30381317的博客
07-29 356
多Agent系统作为人工智能领域的重要分支，通过多个智能体协作完成复杂任务。其核心原理是将大问题分解为子任务，由不同专业Agent分工处理，通过状态管理和消息传递实现协同工作。这种架构的技术价值在于能够处理单一模型难以胜任的复杂场景，如学术论文写作、数据分析等。在实际应用中，FastAPI提供了高效的异步后端支持，Vue3的Composition API则能优雅管理前端复杂状态。以论文写作平台为例，研究Agent负责文献检索，大纲Agent规划结构，写作Agent生成内容，LangGraph则协调整个工作流
Windows本地AI Agent网络搭建：从LangGraph实战到API集成
cuibinmo3519的博客
06-29 320
AI Agent（智能体）作为人工智能领域的关键技术，其核心原理是通过特定指令或目标驱动的自主实体，能够感知环境、做出决策并执行动作。在工程实践中，多智能体系统通过分工协作，显著提升了复杂任务的处理能力与可靠性。这一技术价值在于将大语言模型的通用能力转化为专业化、可编排的工作流，为自动化与智能化应用提供了新范式。其典型应用场景包括自动化报告生成、智能编码辅助、个性化研究助理等需要多步骤、多数据源处理的领域。本文聚焦于在Windows开发环境中，基于LangGraph框架快速搭建可运行的AI Agent网络，
Langchain+Langgraph+Agent智能体开发实战：从入门到项目集成
最新发布
weixin_33785108的博客
08-14 320
智能体（Agent）作为人工智能领域的关键技术，通过赋予AI规划、决策与工具调用能力，实现了从被动响应到主动执行的跨越。其核心原理在于结合大语言模型的推理能力与外部工具的执行功能，形成感知-思考-行动的闭环。这一技术为构建复杂、自动化的AI应用提供了基础框架，显著提升了任务处理的灵活性与智能化水平。在工程实践中，开发者常利用Langchain框架快速搭建基于大模型的应用程序链，并通过Langgraph实现多智能体协作与有状态工作流的精细编排。这种技术组合尤其适用于需要多步骤决策、长期记忆或团队式任务分解的场
LangChain与LangGraph实战：从零构建多智能体协作系统
weixin_33739541的博客
07-03 456
如果你正在寻找一个能帮你快速上手、从零搭建一个真正可用的 AI 智能体（Agent）的实战指南，那么这篇文章就是为你准备的。我们不会空谈概念，而是直接聚焦于如何利用 LangChain 和 LangGraph 这两个当前最主流的框架，结合 OpenClaw 这样的实战项目，手把手带你构建一个具备协作能力的多智能体系统。无论你是想为个人项目增加自动化能力，还是为公司探索 AI 应用，这篇文章都将提供一条清晰的路径。 本文的核心是“实战”。我们将从最基础的环境搭建开始，逐步深入到智能体的核心概念、不同架构的设计
LangChain与LangGraph实战：从RAG到智能体的企业级AI应用开发
weixin_34375251的博客
07-08 367
在实际 AI 应用开发中，LangChain 已经从一个单纯的“链”式编排框架，演变为一个包含 LangGraph、LangServe、LangSmith 等多个组件的生态系统。对于开发者而言，理解 LangChain 的核心架构、掌握其最新版本（如 0.1.x）的用法，并能够将其与 RAG、智能体（Agent）、微调等技术结合，是构建企业级大模型应用的关键。本文将从一个资深开发者的视角，带你深入 LangChain 的工程实践，涵盖从核心概念、环境搭建、项目实现到生产级优化的完整链路。无论你是想快速入门
FastAPI + LangChain Agent 从零入门学习笔记
fmk1023的博客
04-17 512
pip 不是内部或外部命令→ 系统未正确配置 Python 环境变量→ 调用了LibreOffice 自带阉割版 Python，无开发能力uvicorn 不是命令→ 必须用或→ 缺少通义千问依赖，需执行→ LangChain 版本过新，函数路径变更，改用 LangGraph 极简 Agent 避免报错。
AI Agent开发实战：LangChain与LangGraph框架全解析
weixin_34026276的博客
08-10 351
AI Agent作为连接大语言模型与现实应用的关键技术，通过工具调用、任务规划与状态管理，实现了从被动问答到主动执行的跨越。其核心原理在于将LLM的推理能力与外部工具、数据源相结合，形成可自主完成复杂任务的智能系统。这一架构在自动化流程、智能客服、数据分析等场景展现出巨大价值。本文聚焦于当前主流的LangChain与LangGraph框架，通过实战代码演示如何构建具备工具调用、工作流编排和对话记忆能力的智能体。教程涵盖从环境搭建、核心组件使用到API封装的全流程，为开发者提供了一套完整的工程实践方案。
LangChain应用部署实战：从FastAPI到Docker容器化
weixin_33947521的博客
08-11 381
在AI应用开发领域，服务部署是将本地原型转化为可访问在线服务的关键环节。其核心原理在于将AI模型与业务逻辑封装为标准的Web服务接口，通过异步网关协议处理网络请求。这一过程的技术价值在于实现应用的可扩展性、高并发处理和环境一致性，从而支撑生产环境的稳定运行。常见的应用场景包括智能问答系统、文档分析工具等需要对外提供API服务的AI应用。本文聚焦于LangChain框架构建的AI应用，详细介绍了如何利用FastAPI和Uvicorn构建异步Web服务，并通过Docker容器化技术解决环境依赖和部署一致性问题，
RAG生产实战：从分块调参到LangGraph部署的完整排障指南
weixin_30235225的博客
06-20 296
RAG（检索增强生成）是当前大模型落地的核心技术路径，其本质是通过向量搜索将外部知识注入大型语言模型，以缓解幻觉、提升事实准确性。技术原理上，它依赖数据预处理、向量检索、重排序与可控生成四大环节协同，其中90%的效果瓶颈不在LLM本身，而在PDF解析、语义分块、reranker选型等‘非生成’环节。该技术已广泛应用于智能客服、企业知识库、合规问答等场景，强调低延迟、高召回与可审计性。本文聚焦RAG工程化落地，深入解析Chunking策略、Qdrant性能调优、LangChain与LangGraph链路编排，
从零手写AI Agent：LangGraph状态图与工具调用实战
weixin_30394981的博客
07-12 376
AI Agent本质上是具备自主决策能力的程序化推理系统，其核心在于状态管理、条件路由与安全工具集成。LangGraph通过显式定义节点、边和状态契约（如TypedDict），将非线性推理过程转化为可调试、可测试、可嵌套的有向图结构。相比黑盒AgentExecutor，它提供完全可控的状态读写、确定性路由逻辑和子图复用能力，显著提升生产环境稳定性与可观测性。本文聚焦真实工程场景——基于Wikipedia API实现结构化知识检索、通过沙箱化Python REPL执行安全计算，并结合FastAPI暴露可审计的
B站AI Agent教程实战避坑指南：LangChain到LangGraph工程化落地
weixin_33664951的博客
06-20 293
AI Agent是当前大模型应用的核心范式，其本质是通过LLM驱动工具调用与任务编排实现自主决策。LangChain提供开箱即用的Agent抽象，而LangGraph则以显式状态机（StateGraph）重构执行流程，解决循环调用、错误不可控等工程顽疾。二者协同构成从原型验证到生产交付的关键技术栈，具备强可调试性、可监控性与权限治理能力。在真实开发中，环境兼容性（如pydantic版本冲突）、依赖链脆弱性（如networkx与matplotlib冲突）及状态初始化规范（如messages类型校验）成为高频卡
基于LangGraph、RAG与Agent的大模型应用开发实战指南
weixin_30301449的博客
08-04 505
提示词工程（Prompt Engineering）是优化大语言模型（LLM）输入以获取高质量输出的关键技术，其核心在于通过结构化、清晰的指令引导模型行为。其原理在于将人类意图转化为模型可理解的指令格式，从而提升生成内容的准确性、相关性和可控性。这项技术的价值在于，它极大地降低了大模型的应用门槛，使开发者无需深入模型内部即可有效利用其能力。在应用场景上，它广泛应用于智能对话、内容生成、代码辅助等领域。结合检索增强生成（RAG）技术，可以为模型注入外部知识库，有效缓解“幻觉”问题；而通过智能体（Agent）框架
LangGraph：构建有状态多步骤AI Agent的图结构框架指南
weixin_30376083的博客
07-28 401
AI Agent工作流编排是现代人工智能应用开发的核心技术，通过图结构实现复杂任务的有序执行。其原理是将任务分解为多个节点，通过有向边定义执行路径，支持条件分支和循环控制。这种技术价值在于能够构建具备长期记忆和动态决策能力的智能系统，显著提升AI应用的自主性和适应性。在工程实践中，工作流编排广泛应用于智能客服、数据分析、自动化流程等场景，其中状态管理和工具调用是关键挑战。LangGraph作为专门的多步骤有状态AI Agent框架，通过内置的状态持久化和条件分支机制，为开发者提供了灵活的工作流编排方案。该框
基于LangChain、LangGraph与LangSmith构建医疗问诊AI Agent全流程实战
深未来技术
07-08 356
这次我们来看一个医疗问诊 Agent 的完整构建过程。这个项目不是简单的概念介绍，而是通过一个具体的应用场景，帮你彻底理清 LangChain、LangGraph 和 LangSmith 这三个核心框架在实际开发中各自扮演什么角色、如何协同工作，以及如何从零开始搭建一个能稳定运行的智能体。 如果你正在学习 AI Agent 开发，或者想了解如何将大模型能力整合进业务流程，这篇文章可以直接收藏。我们将重点关注：如何用 LangChain 组织工具链，如何用 LangGraph 编排复杂的决策流程，以及如何用
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值