智能体开发技术（Python+FastAPI版） 课件 第二章 FastAPI开发框架

FastAPI开发框架content目录01FastAPI快速使用02Jinja2模板引擎03SQLModel数据处理04FastAPI对接大模型FastAPI快速使用01快速入门FastAPI概述FastAPI是一个用于构建API的现代、快速且高性能的Web框架，使用Python开发，并基于标准的Python类型进行提示。FastAPI目前被大量企业采用，具有以下重要特性。（1）快速且高性能：具有可与Node.js和Go并肩的极高性能，是最快的PythonWeb框架之一。（2）高效编码：提高功能开发速度200％～300％。（3）更少的漏洞：减少约40％的人为（开发者）导致的错误。（4）智能：极佳的编辑器支持，处处皆可自动补全，减少调试时间。（5）简单：易于使用和学习，阅读文档的时间更短。（6）简短：使代码重复最小化，通过不同的参数声明实现丰富功能，且漏洞更少。（7）健壮：生产可用级别的代码，以及自动生成交互式文档。（8）标准化：基于（并完全兼容）API的相关开放标准OpenAPI和JSONSchema。快速入门安装FastAPI直接运行“pipinstallfastapi”命令即可安装FastAPI。另外，为了保证后续针对数据库和模板引擎的操作正确无误，建议同时安装Uvicorn服务运行环境Jinja2模板引擎和SQLModel数据库框架，安装命令如下。快速入门快速实现接口与响应FastAPI可以定义Get、Post等各种类型的HTTP接口，并支持以多种方式获取前端界面传递过来的参数，也可以向前端传送响应的各种类型的内容，默认情况下响应JSON数据。以下代码定义了两个接口并实现了简单的逻辑，可以快速完成一个后台接口的开发。快速入门快速实现接口与响应在PyCharm中运行上述代码，FastAPI服务会正常启动，此时若能够通过浏览器访问:8000/，并在浏览器中看到“HelloWorld”，则说明请求发送成功。FastAPI默认设置中提供了接口文档和调试功能（SwaggerUI），访问:8000/docs即可看到当前项目的所有接口，方便地对Post请求接口进行调试，如图2-1所示。快速入门快速实现接口与响应FastAPI除了提供SwaggerUI用于查阅接口文档和调试接口，还额外提供ReDoc文档用于以更加简洁的界面展示接口规范，访问:8000/redoc即可查看接口规范，如图2-2所示。快速入门快速实现接口与响应事实上，对于开发过程中的接口调试，除了使用SwaggerUI，还推荐使用Apifox等工具来进行调试和管理。相较于SwaggerUI，Apifox的功能更加强大，不仅支持调试，还可以对接口进行测试，并支持WebSocket协议。最关键的是，Apifox可以保存每次的请求数据，以供下次使用。图2-3展示了如何在Apifox中发送登录请求。URL及参数无论是Get还是Post等请求，均需要一个唯一的URL，而在URL中也可以定义参数。参数一般分为两类，分别是路径参数与查询参数。FastAPI的URL和地址栏参数及相关定义主要用于解决以下4个问题。（1）定义服务器接口的URL，从根目录/开始。（2）定义接收前端数据的请求类型，如Get、Post、Put或Delete等。（3）获取请求地址中的查询参数或路径参数。（4）通过将@app.get/post等装饰器与被装饰的函数绑定，对请求进行后台处理。URL及参数上述代码中由于均为Get请求，因此既可以直接在浏览器地址栏中访问，又可以在SwaggerUI中进行访问和调试。当访问:8000/user/123时，输出为{"user_id":"123"}格式的JSON数据，这是完全正确的。RESTful接口描述性状态迁移（RepresentationalStateTransfer，REST）的设计目的是希望在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适合通信的架构。因此REST指的是一组架构约束条件和原则。如果一个架构符合REST的约束条件和原则，则称它为RESTful架构，这个架构同样具有RESTful风格。对于Web开发者来说，是否完全掌握RESTful的定义并不关键，但熟悉其核心的几个要素十分必要，如定义HTTP请求类型和服务器URL接口规范的标准。例如，对一个用户的操作，其资源对象是用户，而请求类型和接口定义应该遵循表2-1所示的基本标准进行。JSON请求体在当前的互联网通信过程中，JSON数据格式在前后端通信中的使用更加广泛，除了后端可以向前端响应JSON数据，前端还可以向后端提交JSON数据。在FastAPI中，这类接口和请求的定义与获取也较为方便，下述代码展示了这一过程。JSON请求体除了常规的将整个Post请求体正文作为JSON数据提交，在FastAPI中，还可以借用Pydantic（一个数据验证库）的能力对JSON数据进行更加细致的处理和验证。以下代码展示了如何将一个数据模型映射为JSON请求字段，并进行数据类型的验证。会话管理HTTP本身是无状态协议，即客户端与服务器在交互过程中无记忆能力，服务器并不能区分是哪个客户端或浏览器发送的请求。为了保持HTTP的状态，通常选择使用Session和Cookie来进行管理（目前也大量使用Token来进行会话管理和鉴权）。在FastAPI中，可以通过SessionMiddleware中间件来管理Session，通过Cookie对象来读取前端发送的Cookie，或通过Response对象来向前端发送Cookie变量。会话管理下述代码演示了自定义Cookie变量的过程。会话管理事实上，会话管理和用户鉴权是Web系统中非常重要的技术，但是HTTP的Session和Cookie机制相对而言是比较落后的技术，其机制决定了这些技术不太适用于大型或分布式系统。在分布式系统中，要确保Session机制正常工作，需要在每一个系统节点中同步Session数据，这不仅开销巨大，实现过程也比较麻烦。因此，目前通常有以下两种解决方案。（1）Session的维护不再保存于Web服务器中，而是保存于一台统一的服务器（如Redis数据库）中。每次需要读取Session变量时，都直接从Redis服务器中获取，通过SessionID进行关联查找。这样，无论有多少个服务器节点，多少个应用系统，均统一与Redis服务器进行通信。这相当于让Redis对SessionID和Session变量进行统一管理。（2）使用Token机制进行鉴权，Token机制完全脱离了Session，由开发者自行实现，或使用主流的JWT/OAuth等标准进行处理，可以非常灵活并自主地处理鉴权过程。上述两种方案在FastAPI中均提供了支持，但是本书的核心目标是AI应用程序和智能体的开发，而非使用Web应用系统开发各种关键技术，所以不赘述Web应用开发的内容。后续项目使用到这部分内容时，会对其进行单独讲解。文件上传在FastAPI中，对文件上传提供了很好的封装，利用UploadFile对象即可方便地读取前端上传的二进制文件并进行保存。以下代码展示了如何获取上传的文件。。上述代码使用原始文件名称将上传的文件保存到当前目录下，在实际项目环境下，还需要考虑文件名的重命名，或者对文件类型、后缀名、文件大小等进行限制，后续在项目使用中再进行拓展。文件上传ase64编码的核心逻辑是使用64个字符（即6个二进制位的组合）来表示各种数据，而常规数据是由8个二进制位（即1个字节）表示的，所以这里存在一个转换关系。例如，针对常规字符Red，其在ASCII中对应82、101、100，对应的二进制为010100100110010101100100，一共24个二进制位；而在Base64编码中，每6个二进制位表示一个字符，如表2-2所示，所以Base64编码后的二进制变为010100100110010101100100，根据Base64编码索引，对应字符为UmVk。。数据验证在FastAPI中，对前端参数值进行验证变得非常方便。以下代码分别对路径参数和表单数据进行了验证。异步编程什么是异步编程异步编程使程序可以在等待某种操作（如网络请求或文件读取）时运行其他操作，而不是单纯地阻塞，从而提高了程序的响应速度和资源利用率。在Python中，异步编程通常通过以下3个基本构件来实现。（1）async：通常放置在函数定义之前，用于定义异步函数。（2）await：等待异步操作完成。（3）asyncio：提供对任务调度和事件循环的支持异步编程为了清晰展示异步编程和同步编程的区别，以下代码模拟了一个常规的任务操作，每个任务完成的时间不同。异步代码演示异步编程以下代码展示了如何在Python中实现异步编程。异步代码演示异步编程FastAPI默认提供了对异步编程的支持，定义接口时在函数前面添加关键字async即可，无须做额外操作。例如，定义一个文件上传的接口的代码如下。在FastAPI中使用异步编程Jinja2模板引擎02模板引擎的作用在互联网应用开发的早期，整个Web系统开发的生态远没有现在这样完善，服务器框架通常只能处理简单的HTTP请求。早期的Web服务器框架通常在服务器中直接写出HTML代码并响应给前端，类似如下方式。模板引擎的作用模板引擎的引入主要用于解决以下3个问题。（1）把Python代码和前端HTML代码分离，不再采用混编的方式来编写代码，在提高代码可维护性的同时提升代码的开发效率。（2）在渲染模板界面的同时，可以向模板界面传递变量和值，这些变量和值将在模板界面中被引用，从而直接在HTML界面中填充动态内容。（3）通过模板引擎特定的语法规则，可以在HTML中非常清楚地标识模板变量，同时服务器在渲染模板界面时，也能够更加高效地进行处理，提升服务器响应性能。模板引擎的作用就是将后端的数据动态填充到HTML界面中。在当今的开发过程中，除了使用模板引擎进行动态填充，还可以将数据以JSON格式响应给前端，交由前端的JavaScript或前端框架进行动态填充。目前，这两种方式同时存在，且无优劣之分，开发者可以根据业务需求或产品的形态及架构选择其中一种方式。Jinja2快速使用首先，定义一个HTML静态界面，并在界面中内嵌模板引擎标识符，用于获取变量的值。Jinja2快速使用其次，将上述模板界面保存到当前目录的templates目录下，并将其命名为basic.html，在后端编写以下代码，注意代码中的规范性要求。Jinja2核心语法Jinja2模板引擎定义了以下3种基本引用标识符。（1）{%...%}：用于循环或判断语句。（2）{{...}}：用于表达式的值的引用。（3）{#...#}：用于模板引擎的注释。如果注释中存在模板引擎的语法，那么使用<!---->将不被模板引擎认为是注释，注释中的语句将被运行，此时应使用{#...#}进行注释。假设FastAPI在调用TemplateResponse时为模板界面传递了一个变量count，值为100，即参数context={"count":100}，那么以下代码基本完整演示了模板引擎的用法。Jinja2核心语法除此以外，在模板界面中还可以直接调用Python的自定义函数，不过需要先将此函数注册到Jinja2模板引擎中。定义与调用函数的代码如下。在模板界面中，可以通过以下方式读取get_user()函数返回的数据。过滤器代码“loop|int”，这便是Jinja2中过滤器的用法。过滤器本质上是一个函数，它将变量作为函数的参数传递进去，处理后再返回新的值到调用处。例如，loop|int可以理解为loop=int(loop)。表2-3列出了Jinja2中常用的过滤器及其用法。应用示例在FastAPI中定义图书信息，代码如下。SQLModel数据处理03利用PyMySQL操作数据库由于任何一个应用系统基本上都会在后台使用数据库来永久保存数据，因此利用Python操作数据库是开发Web应用系统的一个必经过程。要使用Python操作数据库，必须先创建数据库和表。下面以MySQL为例，创建一张用户表，表名为users，包含userid、username、password、phone、role、createtime等数据，用户表中的数据如图2-10所示。利用PyMySQL操作数据库以下代码演示了如何利用PyMySQL连接MySQL数据库并查询users表的前3条信息。利用PyMySQL操作数据库默认情况下，游标返回的二维元组没有字段名，只能使用元组的下标来获取数据，并不是特别方便。尤其是列比较多的时候，使用下标很容易出错，且如果表的字段有所调整，则所有代码都必须进行调整，否则会显示错误的数据。为了解决这个问题，可以在实例化游标对象时使用字典类型的游标对象，返回列表+字典的数据结构。修改上述代码如下。另外，在PyMySQL中，针对数据库的插入、更新、删除等操作，只需要编写好对应的SQL语句，调用cursor.execute(sql)便可正常完成，使用连接对象mit()即可完成提交。SQLModel核心操作SQLModel基于SQLAlchemy，是Python中各类Web开发框架的首选数据库框架，可以很好地与FastAPI等框架集成，且具备ORM能力，从而使操作数据表变得更加方便。那么，什么是ORM？ORM的作用是在关系数据库和对象之间进行映射。这样，用户在对数据表进行具体操作的时候，无须编写SQL语句，像平时操作Python的类和对象一样操作数据库即可。为什么需要使用ORM对数据库操作进行封装呢？在在一个大型系统中，由于表和列非常多，如果全部使用原生SQL语句来实现数据库操作，那么一旦表结构发生变化，就需要重写很多SQL语句，为代码的维护和开发效率带来了极大的困扰。使用ORM对数据库进行封装后，就可以将业务处理和数据库操作完全分离开来，这样开发者只需要关心业务逻辑实现，而不用关注数据库是如何实现读写的。同时，对数据库的增删改查完全不用编写SQL语句，而是通过操作一个类和类中的方法或属性来实现。这就是所谓的对象与关系之间的映射。SQLModel核心操作以下代码演示了利用SQLModel操作用户表的增删改查操作。首先，创建一个users.py模块，用于连接数据库并定义映射关系（也称为模型类）。SQLModel核心操作其次，在FastAPI的接口中对用户表进行增删改查操作，代码如下。SQLModel核心操作上述代码可以在SwaggerUI中进行请求的发送和确认，且上述代码遵循了RESTful接口规范，读者可以通过实验进行感受。在SQLModel中，不用再编写原生的SQL语句，全部通过方法进行操作就可以达到目的，还可以使代码的可读性和可维护性变得更强。SQLModel复杂查询SQL的查询条件非常多，如多条件查询、分组查询、聚合函数统计、多表连接查询等，是SQL语句中很复杂的操作。但是SQLModel提供了对此类操作的支持，通常使用select()函数来构造查询语句。同时，针对一些复杂查询，如果使用SQLModel函数难以构建查询语句，则可以使用原生SQL语句来实现。以下代码演示了一些常用的复杂查询操作，以供读者参考。如果后续项目中使用到新的操作，则会对其单独进行讲解。SQLModel复杂查询为了调试方便，上述代码并没有被放到FastAPI的接口中，但是操作方式是完全一致的。其运行结果如下。FastAPI对接大模型04基于OpenAI库对接与DeepSeek的非流式响应的对话过程第1章已经讲解了如何在Python中使用OpenAI或基于HTTP接口来对接AI大模型，在FastAPI中，大模型的对接与之基本上没有本质上的区别，只是将对接过程封装在接口当中，并与前端进行交互。处理流式响应在FastAPI中向前端进行流式输出时主要涉及两种关键技术，分别是yield生成器和StreamingResponse对象。其中，yield生成器用于将大模型的流式输出转换为生成器输出而非标准的返回值；StreamingResponse对象用于向前端输出流式响应结果。流式响应结果在HTTP中将以Content-type:text/event-stream的形式反馈给前端，具体代码如下。处理流式响应开启上述服务后，可以在Python中编写以下代码进行测试，确认流式输出是否正常。前端JavaScript对接1．fetch()函数的用法fetch()函数提供了一个获取资源的接口（包括跨域请求），用于取代传统的XMLHttpRequest来发送异步JavaScript和XML（AsynchronousJavaScriptandXML，AJAX）请求，同时支持发送Get、Post请求等操作。为了了解fetch()函数的用法，先在服务器中编写以下代码，用于定义接口和渲染模板界面。前端JavaScript对接1．fetch()函数的用法编写模板界面文件fetch.html中的代码，该代码实现了使用fetch()函数发送一个Get请求并输出响应正文的功能。前端JavaScript对接2．在fetch()函数中处理