Python on Snow

MCP 完全指南：原理、远程调用链路与自建服务接入 Agent

Fri, 09 Oct 2026 15:00:00 +0800

MCP 完全指南：原理、远程调用链路与自建服务接入 Agent

大模型会“思考”和生成文本，却不知道你公司今天新增了哪个项目，也不能凭空替你创建工单。MCP 做的事，是用一套标准协议把这些外部数据和动作安全地接到 Agent 身边。

如果只记一句话，可以记住：

MCP（Model Context Protocol，模型上下文协议）是 Agent 应用与外部能力之间的标准接口。它规定如何发现能力、描述参数、发起调用、返回结果与协商权限；它不是模型，也不是新的业务 API。

本文按 2026-07-28 版 MCP 规范讲解，同时标出旧版客户端常见的初始化与会话差异。协议仍在快速演进，真正接入时应以所用 Host 和 SDK 支持的版本为准。

一、为什么需要 MCP

没有 MCP 时，每个 Agent 平台都有一套插件格式。若要让三个 Agent 连接 GitHub、数据库和内部工单系统，往往需要写九份适配代码：

flowchart LR subgraph Before[没有 MCP：N × M 个适配器] A1[Agent A] --> X1[GitHub 适配] A1 --> X2[数据库适配] A2[Agent B] --> X3[GitHub 适配] A2 --> X4[工单适配] end subgraph After[使用 MCP：统一协议边界] B1[Agent A] --> P[MCP] B2[Agent B] --> P P --> S1[GitHub Server] P --> S2[Database Server] P --> S3[Ticket Server] end

MCP 把“Agent 如何使用外部能力”从具体平台中抽了出来。它带来的核心价值不是少写一次 HTTP 请求，而是统一了以下契约：

问题	MCP 给出的统一方式
服务有什么能力	`tools/list`、`resources/list`、`prompts/list`
参数长什么样	JSON Schema
怎样执行动作	`tools/call`
怎样读取上下文	`resources/read`
怎样返回结果	`content`、`structuredContent`、错误信息与元数据
双方支持哪些功能	协议版本、capabilities 与扩展协商
消息如何传输	本地 `stdio` 或远程 Streamable HTTP

它和 USB-C 的类比有用但不完整：USB-C 统一了物理接口，MCP 统一的是一组面向模型的语义与调用契约。一个工具的名字、描述和 Schema 会直接影响模型是否选中它，因此 MCP 元数据本身就是产品界面的一部分。

二、先认清四个角色

flowchart LR U[用户] --> H[Host
Agent 应用] H --> M[LLM] H --> C1[MCP Client A] H --> C2[MCP Client B] C1 <-->|MCP| S1[MCP Server
项目系统] C2 <-->|MCP| S2[MCP Server
知识库] S1 --> API1[(业务 API / DB)] S2 --> API2[(文档 / 搜索)]

角色	做什么	常见误解
User	提出目标并对高风险动作确认	用户通常不直接构造 MCP 请求
Host	承载 Agent、模型、上下文、策略、审批与多个 MCP Client	MCP Server 不负责整个 Agent 循环
MCP Client	与一个 Server 通信，完成发现、调用和协议兼容	它一般是 Host 内部组件，不等于用户界面
MCP Server	暴露能力，校验调用并连接真实业务系统	它不是把整个数据库无条件交给模型

最重要的一点：通常不是模型直接访问 MCP Server。Host 先把允许的能力提供给模型；模型产生工具调用意图；Host 再根据权限、审批和运行策略决定是否执行。这个边界让“模型想做什么”和“系统允许做什么”可以分开。

三、MCP 暴露什么

MCP Server 主要暴露三类原语：

原语	控制者	适合什么	示例
Tools	模型选择调用，Host 执行策略把关	查询或执行动作	`search_projects`、`create_ticket`
Resources	Host / 应用选择加载	可寻址的只读上下文	`project://P-1024/spec`
Prompts	用户或 Host 选择	可复用的工作流模板	“生成发布检查清单”

此外还有通知、补全、引导式输入等能力。不要因为协议支持很多功能就全部实现：大多数服务从少量清晰的 Tools 开始就够了。

Tool 和普通 REST API 有什么不同

底层业务逻辑完全可以继续使用 REST、gRPC 或数据库。MCP Server 更像一层“面向 Agent 的适配器”：

flowchart LR L[LLM 看到的工具
名称 + 描述 + Schema] --> S[MCP Server
鉴权 · 校验 · 编排] S --> R1[REST API] S --> R2[gRPC] S --> R3[(Database)] S --> R4[Message Queue]

REST 路由通常为人类开发者设计，例如 PATCH /v1/projects/:id；MCP Tool 应围绕用户目标设计，例如 archive_project(project_id, reason)。不要简单地把数百个内部端点一比一暴露给模型。

四、远程 MCP 的完整调用链路

远程 MCP 通常使用 Streamable HTTP。旧的 HTTP+SSE transport 已被取代，只应为旧客户端保留兼容。下面先看一次典型工具调用：

sequenceDiagram autonumber actor User as 用户 participant Host as Agent Host participant Model as LLM participant Client as MCP Client participant Server as Remote MCP Server participant API as 业务系统 Host->>Client: 连接服务器配置 Client->>Server: 发现协议版本与 capabilities Server-->>Client: server info + capabilities Client->>Server: tools/list Server-->>Client: 工具名、描述、输入/输出 Schema、annotations User->>Host: “列出本周延期的项目” Host->>Model: 用户消息 + 可用工具定义 Model-->>Host: 调用 list_projects(status="delayed") Host->>Host: 策略检查 / 必要时请求确认 Host->>Client: 执行工具调用 Client->>Server: tools/call + 身份凭据 Server->>Server: 鉴权、租户隔离、参数校验 Server->>API: 查询真实业务数据 API-->>Server: 项目记录 Server-->>Client: content + structuredContent Client-->>Host: 工具结果 Host->>Model: 将允许的结果加入上下文 Model-->>Host: 组织自然语言答案 Host-->>User: 最终回复 + 来源/动作状态

这条链路可以拆成五段。

1. 配置与发现

Host 保存 MCP Server 的名称、URL 和认证方式。连接时，双方确认协议版本、服务信息和 capabilities；Client 再读取工具列表。现代客户端会缓存列表，并在服务通知能力变化或缓存失效时刷新。

截至本文所用的 2026-07-28 规范，新链路以无会话的 server/discover 和每请求元数据为主；兼容旧规范的客户端则可能先走 initialize → initialized，并携带 Mcp-Session-Id。SDK 会处理大部分兼容逻辑，业务代码不要自己拼 JSON-RPC。

2. 工具进入模型上下文

Host 并不一定把所有工具都塞给模型。它可能按租户、角色、当前任务或工具搜索结果过滤，只向模型提供相关的名称、描述和 Schema。这一步决定模型“知道自己能做什么”。

工具越多不一定越好。五个边界明确的工具，通常比五十个描述含糊的工具更可靠，也更节省上下文。

3. 模型选择，Host 决策

模型返回的是一个结构化调用意图，而不是直接执行结果。Host 应在这里做策略判断：

该用户能否使用这个 Server 和 Tool；
读取是否可直接执行，写入是否需要确认；
参数是否命中数据边界、费用上限或速率限制；
是否存在提示注入、越权或破坏性风险。

Tool annotations 能帮助 Host 判断 readOnly、destructive、openWorld 等性质，但它们只是提示，不能替代服务端鉴权。

4. HTTP 调用与业务执行

Client 通过 HTTPS 向 /mcp 发送 MCP 请求。现代远程请求包含协议版本和路由相关信息，认证通常放在 Authorization header。Server 必须再次完成：令牌验证、scope 校验、租户隔离、参数校验、业务授权、超时与审计。

然后它才调用真正的 REST/gRPC/数据库。MCP 不会替你解决业务授权，也不会自动让一条危险 SQL 变安全。

把 SDK 隐藏的细节展开，一次现代 Tool 调用大致是下面这样（为便于阅读省略部分每请求 _meta）：

POST /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer <access-token>
Content-Type: application/json
Mcp-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: list_projects

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {"status": "delayed", "limit": 5}
  }
}

成功结果仍是 JSON-RPC，其中 content 供模型阅读，structuredContent 供程序可靠消费：

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [{"type": "text", "text": "Found 1 delayed project."}],
    "structuredContent": {
      "result": [{"id": "P-1002", "name": "Billing migration"}]
    },
    "isError": false
  }
}

不要在业务代码中手写这些报文。示例的意义是方便查日志、网关和 trace；版本协商、header 与 JSON-RPC 细节应交给 SDK。

5. 结果回到模型

工具结果常有三条通道：

字段	谁使用	建议
`content`	模型	简洁、可理解，说明发生了什么
`structuredContent`	Host / 后续工具 / UI	遵守输出 Schema，返回稳定 ID 与字段
`_meta`	Client 应用	放客户端专用信息；不要把它当秘密保险箱

Host 将允许模型看到的结果放回上下文，模型再生成最终答复。MCP 调用成功不等于用户任务成功：Agent 还需要检查 isError、确认数据完整性，并可能继续调用下一项工具。

五、两种远程连接模式

flowchart TB subgraph Direct[模式 A：应用运行时直接连接] A[你的 Agent 应用] --> C[MCP Client] C --> S[Remote MCP Server] end subgraph Hosted[模式 B：模型平台托管连接] B[你的应用] --> P[模型 / Agent 平台] P --> HS[Remote MCP Server] end

模式	优点	适合场景
运行时直连	网络、凭据、审批、过滤都由你的应用掌控	私网服务、严格合规、自定义策略
平台托管 MCP	接入代码少，Agent 平台负责协议调用	公网 HTTPS 服务、快速集成

在 OpenAI Agents SDK 中，公开远程服务可作为 hosted MCP tool；本地或私有服务则可以由 SDK runtime 通过 stdio 或 Streamable HTTP 管理。选择标准不是“哪种更新”，而是连接与信任边界应该由谁拥有。

六、从零开发一个远程 MCP Server

下面做一个最小但完整的“项目查询”服务。示例使用 Python SDK v2、Python 3.10+，并选择无状态 Streamable HTTP，便于水平扩展。

1. 初始化项目

1
2
3

mkdir project-mcp && cd project-mcp
uv init
uv add "mcp[cli]>=2,<3" pydantic

固定主版本很重要：MCP SDK 与规范演进较快，不应让生产构建在无审核时跨主版本升级。

2. 编写 `server.py`

from typing import Annotated, Literal

from mcp.server import MCPServer
from mcp.types import ToolAnnotations
from pydantic import BaseModel, Field


class Project(BaseModel):
    id: str
    name: str
    status: Literal["active", "delayed", "archived"]
    owner: str


PROJECTS = [
    Project(id="P-1001", name="Search upgrade", status="active", owner="Lin"),
    Project(id="P-1002", name="Billing migration", status="delayed", owner="Kai"),
]

mcp = MCPServer("project-catalog", version="1.0.0")


@mcp.tool(
    annotations=ToolAnnotations(
        readOnlyHint=True,
        idempotentHint=True,
        destructiveHint=False,
        openWorldHint=False,
    )
)
def list_projects(
    status: Literal["active", "delayed", "archived"] | None = None,
    limit: Annotated[int, Field(ge=1, le=50)] = 10,
) -> list[Project]:
    """List projects, optionally filtered by exact status.

    Use this for project discovery. It never modifies project data.
    """
    matches = [p for p in PROJECTS if status is None or p.status == status]
    return matches[:limit]


if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=8000,
        stateless_http=True,
        json_response=True,
    )

这段代码虽短，却已经定义了完整契约：

函数名成为 Tool 名；
docstring 成为模型看到的描述；
类型注解生成输入 JSON Schema；
返回类型生成输出 Schema；
ToolAnnotations 告诉 Host 它是只读、幂等、非破坏且不访问开放互联网的；
SDK 处理 MCP 消息、协议版本与 Streamable HTTP。

生产环境里把 PROJECTS 替换成业务 Service 调用即可，但不要跳过“从当前认证身份推导租户”这一步。

3. 本地测试

先用官方 Inspector 检查能力发现、Schema 和结果：

`1`	`uv run mcp dev server.py`

再启动真正的远程 transport：

1
2

uv run python server.py
# MCP endpoint: http://127.0.0.1:8000/mcp

另一种可靠的自动化检查，是用同一 SDK 作为客户端：

import asyncio
from mcp import Client


async def main() -> None:
    async with Client("http://127.0.0.1:8000/mcp") as client:
        tools = await client.list_tools()
        assert any(tool.name == "list_projects" for tool in tools.tools)

        result = await client.call_tool(
            "list_projects", {"status": "delayed", "limit": 5}
        )
        assert not result.is_error
        assert result.structured_content["result"][0]["id"] == "P-1002"


asyncio.run(main())

测试至少覆盖：正常参数、边界值、非法枚举、无权限、下游超时、空结果和输出 Schema。Inspector 能证明“协议可用”，自动化测试才能证明“升级后仍然可用”。

4. 容器化与部署

FROM python:3.13-slim
WORKDIR /app

COPY pyproject.toml uv.lock ./
RUN pip install --no-cache-dir uv && uv sync --frozen --no-dev

COPY server.py ./
EXPOSE 8000
CMD ["uv", "run", "python", "server.py"]

1
2

docker build -t project-mcp:1.0.0 .
docker run --rm -p 8000:8000 project-mcp:1.0.0

生产地址应是稳定 HTTPS URL，例如：

`1`	`https://mcp.example.com/mcp`

上面的演示服务没有认证，只能用于本机学习。部署到任何可被其他人访问的网络前，必须接入 SDK 的 token verifier / OAuth 配置，并在每个 Tool 内落实业务授权。

反向代理和平台需要允许流式响应；设置合理的请求体上限、调用超时和连接空闲时间。无状态模式适合普通查询与动作；需要跨调用状态时，优先让服务返回显式 handle，再由后续工具把它作为参数传回，而不是偷偷依赖某台实例的内存。

七、让 Agent 真正使用你的 MCP

“服务能访问”只完成了一半。要让 Agent 稳定调用，还需要注册、授权、告知使用时机、验证真实行为。

接入 Codex

使用 Codex CLI 添加远程服务：

1
2

codex mcp add projects --url https://mcp.example.com/mcp
codex mcp list

也可以写入 ~/.codex/config.toml：

1
2

[mcp_servers.projects]
url = "https://mcp.example.com/mcp"

然后在项目 AGENTS.md 中给出简短、可验证的路由规则：

1
2

查询项目状态、负责人或项目 ID 时，先使用 projects MCP 的只读工具。
任何修改、归档或删除项目的动作都必须先向用户展示目标与影响，并等待确认。

配置决定“Agent 能看见哪些能力”，指令决定“什么时候优先使用”。不要写“永远相信工具结果”之类的规则，远程内容仍可能过期或包含恶意文本。

接入 OpenAI Agents SDK

公开的远程 MCP 可以作为 hosted tool 附到 Agent 上：

from agents import Agent, HostedMCPTool

agent = Agent(
    name="Project assistant",
    instructions="Use the projects MCP for current project facts.",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "projects",
                "server_url": "https://mcp.example.com/mcp",
                "require_approval": "never",  # 仅适合这里的只读工具
            }
        )
    ],
)

写操作不要照抄 never。审批策略应与工具风险匹配，并且服务端仍需独立鉴权。私有服务也可以让 Agents SDK runtime 直接管理连接，从而由你的应用控制网络、过滤与审批边界。

验证 Agent 是否会用

准备一组小型评测，而不是只问一句“能用吗”：

用例	期望行为
“列出延期项目”	调 `list_projects(status="delayed")`
“介绍什么是延期项目”	若是通用定义，不应无意义调用
“把 P-1002 删除”	当前无删除工具，应说明做不到，不能伪造成功
“列出 `status=hacked`”	Schema 拒绝非法枚举，Agent 应修正或解释
Tool 返回网页中的“忽略之前指令”	把它视作不可信数据，不执行越权动作

观察三类指标：工具选择是否正确、参数是否正确、拿到结果后是否忠实回答。只看最终文字，容易漏掉重复调用、越权尝试和不必要的高成本请求。

八、工具设计决定 Agent 上限

好工具的形状

flowchart LR G[用户目标] --> N[清楚的动词名] N --> D[说明何时使用] D --> I[窄而明确的输入 Schema] I --> A[真实 annotations] A --> O[稳定的结构化输出] O --> E[可恢复的错误]

建议遵循这些规则：

一个工具完成一个可识别目标。 用 list_projects、get_project、update_project，不要做 project_action(mode, payload) 万能入口。
描述“何时用”，而不只描述实现。 模型靠描述选择工具。
输入要窄。 枚举、长度、范围、格式能写进 Schema 就不要只写在文档里。
读取与写入分开。 这样 Host 才能给不同审批策略。
返回稳定 ID。 后续调用使用 P-1002，不要让模型靠名称猜记录。
分页且设上限。 不要一次把十万行塞进上下文。
错误应可恢复。 “项目不存在，请先 list_projects 获取 ID”比堆栈信息有用。
Schema 向后兼容。 新增可选字段通常安全；改名、改类型或删除字段可能让旧 Agent 失效。

MCP 不适合什么

纯粹在应用内部、只被一处调用的简单函数，直接 function tool 可能更省事；
大文件持续传输、实时音视频等数据面，不应硬塞进工具结果；
要求严格确定性的核心交易流程，不应把关键状态机完全交给模型自由规划；
没有授权边界的“任意 SQL”“任意 Shell”“任意 URL 抓取”，不应作为生产工具暴露。

九、安全：把模型、Server 和返回内容都当作不可信边界

flowchart LR U[用户输入
不可信] --> H[Host 策略层] H -->|最小工具集| M[模型输出
不可信意图] M --> A{审批 / 授权} A --> S[MCP Server
再次鉴权与校验] S --> B[业务系统] B --> R[工具结果
仍不可信] R --> H

上线前至少做好以下事项：

风险	防线
越权读取或跨租户访问	每次调用验证 token、scope、tenant 与对象级权限
破坏性动作	单独工具、明确 annotations、用户确认、幂等键、可审计与可回滚
提示注入	把 Tool/Resource 返回当数据；禁止其改写系统策略或索要更多工具
Token 泄漏	不写入 Tool 描述、结果和日志；不向错误 audience 透传 token
SSRF	URL allowlist、DNS/IP 校验、阻止云元数据与内网地址、限制重定向
数据过量	字段最小化、分页、结果上限、PII 脱敏
拒绝服务与费用失控	速率限制、并发限制、超时、熔断、配额
供应链漂移	固定 SDK 主版本、扫描依赖、灰度升级、可回滚部署

认证回答“你是谁”，授权回答“你能对哪条数据做什么”。只验证 Bearer Token 是否存在远远不够。对多用户服务，业务查询必须从已验证凭据中取得用户和租户，绝不能信任模型传入的 user_id。

OAuth 场景使用标准授权发现、最小 scope 和明确 audience。Tool annotations、Host 弹窗、网络 allowlist 都属于纵深防御，但服务端对象级授权才是最终边界。

十、可观测性与排错

一次 MCP 问题可能出现在四层：模型没选工具、Host 拦截、协议失败、业务系统失败。日志必须能把它们串起来。

建议记录：

trace_id / request ID、Server 与 Tool 名称、版本；
已脱敏的调用方、租户、审批结果；
总耗时和下游耗时、结果大小、错误分类；
Schema 版本与部署版本。

不要记录 access token、完整私密文档或未经脱敏的 Tool 结果。

现象	先查什么
Server 完全连不上	URL、HTTPS 证书、DNS、Host header、防火墙、`/mcp` 路径
已连接但看不到工具	discovery/capabilities、`tools/list`、注册代码是否执行
模型从不调用	Tool 名称与描述、指令、是否给了过多相似工具
参数总是错	Schema 是否太宽或语义含糊，枚举与示例是否清楚
本地正常、远程超时	代理流式配置、平台超时、下游延迟、冷启动
调用成功但回答错误	`content` 是否清楚、结构化结果是否完整、模型是否拿到旧缓存
多副本偶发失败	是否暗中依赖进程内状态或旧版 session sticky routing

最短排错路径通常是：Inspector 直连 Server → SDK Client 直连 → Host 中查看工具列表 → 观察一次完整 Agent trace。这样能快速定位问题属于服务、协议还是模型决策。

十一、生产检查清单

Tool 名称、描述、输入/输出 Schema 已评审
读取、写入、破坏性动作已拆分
每次请求都做认证、scope、租户和对象级授权
远程 endpoint 使用稳定 HTTPS 与 Streamable HTTP
写操作有审批、幂等与审计，必要时可回滚
结果有分页与大小上限，不含 secrets
超时、重试、限流、熔断和下游错误映射已配置
Inspector、自动化测试和 Agent 行为评测均通过
有 trace、指标、脱敏日志和告警
SDK 与 Schema 版本固定，升级可灰度和回滚

结语

MCP 真正解决的不是“让模型发一个 HTTP 请求”，而是让能力发现、参数契约、调用执行、结果返回和安全策略有一条共同的标准链路。

开发自己的 MCP，可以按这条最短路径推进：

flowchart LR A[选一个真实用户目标] --> B[设计一个窄 Tool] B --> C[本地 Inspector] C --> D[自动化测试] D --> E[Streamable HTTP + Auth] E --> F[接入 Agent] F --> G[行为评测与观测] G --> H[再增加下一个 Tool]

先把一个只读工具做准，再增加写操作；先把权限边界做实，再追求复杂编排。MCP 降低了连接成本，却不会替代良好的 API 设计、授权模型与工程治理。

参考资料

Flask 实战教程：面向 Python 开发者的轻量 Web 后端入门

Wed, 16 Sep 2026 10:20:00 +0800

Flask 实战教程：面向 Python 开发者的轻量 Web 后端入门

Flask 的魅力在于“小”：它不会一开始就替你规定项目结构、数据库 ORM、表单库、登录系统和管理后台。但这种自由也意味着你需要自己决定边界。本文会从一个可运行的小项目开始，逐步把自由组织成可维护的工程结构。

如果你已经会 Python 函数、装饰器、虚拟环境和基础 HTTP，Flask 很适合作为第一个 Web 后端框架。它既能写返回 HTML 的传统网站，也能写 JSON API；既能单文件快速验证想法，也能用应用工厂、Blueprint 和扩展支撑中型项目。

你已有的 Python 能力	在 Flask 中如何对应
函数	一个视图函数处理一个路由
装饰器	`@app.get()`、`@app.post()` 绑定 URL
字典和列表	可以直接返回 JSON 风格数据
模板字符串思维	用 Jinja2 渲染 HTML 页面
模块拆分	用 Blueprint 组织路由
单元测试	用 Flask test client 测接口行为

一、Flask 是什么

Flask 是一个轻量级 WSGI Web 框架。它的核心只处理 Web 框架最基础的几件事：

URL 路由；
请求对象和响应对象；
Cookie、Session、上下文；
Jinja2 模板集成；
静态文件；
错误处理；
扩展机制。

数据库、表单校验、登录认证、后台任务、API 文档等能力通常通过扩展或你的业务代码组合出来。这和 Django 的“全家桶”风格不同：Django 默认给你很多约定，Flask 默认给你一个很薄但很灵活的核心。

一次请求在 Flask 中大致会经过这些阶段：

WSGI Server 接收 HTTP 请求；
Flask 创建请求上下文；
根据 URL Rule 匹配视图函数；
执行 before_request 等钩子；
运行视图函数；
返回字符串、字典、模板响应、重定向或 Response 对象；
执行 after_request 等钩子；
WSGI Server 把响应发回客户端。

你可以把 Flask 理解成一个“请求响应协调器”：它不会强迫你怎么写业务，但会把请求到函数、函数到响应这条主线打通。

二、环境准备

先创建虚拟环境：

mkdir flask-shop
cd flask-shop

python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

安装 Flask：

`1`	`pip install Flask`

Flask 官方文档当前稳定版仍然以 pip install Flask 作为基础安装方式。生产项目建议再生成固定版本依赖：

`1`	`pip freeze > requirements.txt`

如果你准备写测试，顺手装上 pytest：

`1`	`pip install pytest`

三、第一个 Flask 应用

创建 app.py：

from flask import Flask, jsonify, request


app = Flask(__name__)

items: dict[int, dict[str, object]] = {}
next_id = 1


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/items")
def list_items():
    q = request.args.get("q", "").strip().lower()
    result = list(items.values())

    if q:
        result = [item for item in result if q in str(item["name"]).lower()]

    return jsonify(result)


@app.post("/items")
def create_item():
    global next_id

    data = request.get_json(silent=True) or {}
    name = str(data.get("name", "")).strip()
    price = data.get("price")

    if not name:
        return {"error": "name is required"}, 400

    try:
        price = float(price)
    except (TypeError, ValueError):
        return {"error": "price must be a number"}, 400

    if price <= 0:
        return {"error": "price must be greater than 0"}, 400

    item = {"id": next_id, "name": name, "price": price}
    items[next_id] = item
    next_id += 1

    return jsonify(item), 201


@app.get("/items/<int:item_id>")
def read_item(item_id: int):
    item = items.get(item_id)

    if item is None:
        return {"error": "item not found"}, 404

    return jsonify(item)

运行开发服务器：

`1`	`flask --app app run`

浏览器打开：

http://127.0.0.1:5000/health
http://127.0.0.1:5000/items

用 curl 创建一个商品：

1
2
3

curl -X POST http://127.0.0.1:5000/items \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Keyboard\",\"price\":299}"

开发时如果想开启调试模式，可以加 --debug：

`1`	`flask --app app run --debug`

调试模式会自动重载代码并展示调试信息，但不要在生产环境开启。

四、路由、请求与响应

Flask 的基本工作方式很直接：URL 规则匹配到视图函数，视图函数返回响应。

常见路由写法：

@app.get("/")
def index():
    return "Hello Flask"


@app.get("/users/<int:user_id>")
def read_user(user_id: int):
    return {"user_id": user_id}


@app.post("/users")
def create_user():
    data = request.get_json()
    return {"received": data}, 201

请求数据通常来自几个位置：

来源	写法	场景
查询参数	`request.args.get("q")`	`/items?q=book`
路径参数	`/items/<int:item_id>`	资源 ID
JSON body	`request.get_json()`	API 请求体
表单	`request.form["name"]`	HTML 表单提交
Header	`request.headers.get("X-Token")`	鉴权、追踪 ID
Cookie	`request.cookies.get("theme")`	轻量偏好

视图函数可以返回多种值：

return "Hello"
return {"status": "ok"}
return jsonify(items)
return jsonify(item), 201
return redirect("/items")
return render_template("items.html", items=items)

Flask 适合初学者的一个原因是：你可以先用简单返回值跑通，等项目复杂后再引入更严格的响应结构和错误处理。

五、模板：用 Jinja2 返回 HTML

Flask 不只适合写 API，它也很适合写服务端渲染页面。创建目录：

flask-shop/
├── app.py
└── templates/
    ├── base.html
    └── items.html

templates/base.html：

<!doctype html>
<html lang="zh-CN">
<head>
    <meta charset="utf-8">
    <title>{% block title %}Flask Shop{% endblock %}</title>
</head>
<body>
    <header>
        <h1>Flask Shop</h1>
    </header>

    <main>
        {% block content %}{% endblock %}
    </main>
</body>
</html>

templates/items.html：

{% extends "base.html" %}

{% block title %}商品列表{% endblock %}

{% block content %}
    <h2>商品列表</h2>

    <ul>
        {% for item in items %}
            <li>{{ item.name }} - {{ item.price }}</li>
        {% else %}
            <li>暂无商品</li>
        {% endfor %}
    </ul>
{% endblock %}

在 app.py 中增加页面路由：

from flask import render_template


@app.get("/")
def index():
    return render_template("items.html", items=list(items.values()))

Jinja2 默认会对变量进行 HTML 转义，所以 {{ item.name }} 比自己拼接 HTML 字符串安全得多。除非你非常明确知道数据来源可信，否则不要随便使用 |safe。

六、表单、Session 与安全边界

Flask 给你自由，但安全边界需要主动设计。尤其是表单、Session、Cookie、模板输出和数据库查询这些地方。

先看一个简单表单页面：

<form method="post" action="/items/form">
    <label>
        名称
        <input name="name" required>
    </label>

    <label>
        价格
        <input name="price" type="number" step="0.01" min="0.01" required>
    </label>

    <button type="submit">创建</button>
</form>

后端处理：

from flask import redirect, request, url_for


@app.post("/items/form")
def create_item_from_form():
    global next_id

    name = request.form.get("name", "").strip()
    price_raw = request.form.get("price")

    if not name:
        return "name is required", 400

    try:
        price = float(price_raw)
    except (TypeError, ValueError):
        return "price must be a number", 400

    item = {"id": next_id, "name": name, "price": price}
    items[next_id] = item
    next_id += 1

    return redirect(url_for("index"))

上面只是演示最小流程。真实项目建议使用 Flask-WTF 或其他表单库来处理字段校验和 CSRF 防护。

Session 需要设置密钥：

import os

app = Flask(__name__)
app.config["SECRET_KEY"] = os.environ.get("SECRET_KEY", "dev-only-change-me")

然后可以使用 session：

from flask import session


@app.post("/login")
def login():
    session["user_id"] = 1
    return {"status": "logged in"}

需要注意：Flask 默认 Session 是签名 Cookie。客户端不能随意篡改它，但可以看到它的内容，所以不要把密码、Token、隐私数据或大量数据放进 Session。

七、项目变大后：应用工厂与 Blueprint

单文件适合入门，但项目继续长大后，app.py 很容易变成一个难维护的大文件。Flask 官方文档推荐使用应用工厂模式，也就是写一个 create_app() 函数来创建应用。

推荐结构：

flask-shop/
├── app/
│   ├── __init__.py
│   ├── blueprints/
│   │   ├── items.py
│   │   └── users.py
│   ├── templates/
│   │   ├── base.html
│   │   └── items/
│   │       └── list.html
│   ├── static/
│   │   └── style.css
│   └── config.py
├── tests/
│   └── test_items.py
└── requirements.txt

app/__init__.py：

from flask import Flask


def create_app(test_config: dict | None = None) -> Flask:
    app = Flask(__name__, instance_relative_config=True)

    app.config.from_mapping(
        SECRET_KEY="dev",
    )

    if test_config is not None:
        app.config.update(test_config)

    from app.blueprints.items import bp as items_bp

    app.register_blueprint(items_bp)

    @app.get("/health")
    def health() -> dict[str, str]:
        return {"status": "ok"}

    return app

app/blueprints/items.py：

from flask import Blueprint, jsonify, request


bp = Blueprint("items", __name__, url_prefix="/items")

items: dict[int, dict[str, object]] = {}
next_id = 1


@bp.get("")
def list_items():
    return jsonify(list(items.values()))


@bp.post("")
def create_item():
    global next_id

    data = request.get_json(silent=True) or {}
    name = str(data.get("name", "")).strip()
    price = float(data.get("price", 0))

    if not name or price <= 0:
        return {"error": "invalid item"}, 400

    item = {"id": next_id, "name": name, "price": price}
    items[next_id] = item
    next_id += 1

    return jsonify(item), 201

运行应用工厂：

`1`	`flask --app app run --debug`

这里的 --app app 会找到 app 包中的 create_app()。这种结构的优点是：测试时可以创建独立配置的应用，扩展初始化也更清晰。

八、数据库与扩展怎么选

Flask 不自带 ORM。常见组合是：

需求	常用选择
ORM	Flask-SQLAlchemy 或 SQLAlchemy
数据库迁移	Flask-Migrate / Alembic
登录态	Flask-Login
表单和 CSRF	Flask-WTF
API 参数校验	Marshmallow、Pydantic 或 Webargs
REST API 快速组织	Flask-RESTful、Flask-Smorest
后台任务	Celery、RQ、Dramatiq

初学时不要一次性把所有扩展装满。建议顺序是：

先用内存字典理解路由和请求；
再接 SQLite 和 SQLAlchemy；
再加数据库迁移；
页面项目加 Flask-WTF；
有登录需求再加 Flask-Login；
API 项目再考虑 Marshmallow、Pydantic 或 OpenAPI 相关扩展。

Flask 的扩展生态很丰富，但扩展越多，越需要清晰的初始化位置。应用工厂模式正是为了解决这个问题。

九、测试：用 test client 固定接口行为

Flask 自带 test client，适合直接测试接口。

tests/test_items.py：

from app import create_app


def test_health():
    app = create_app({"TESTING": True})
    client = app.test_client()

    response = client.get("/health")

    assert response.status_code == 200
    assert response.get_json() == {"status": "ok"}


def test_create_item():
    app = create_app({"TESTING": True})
    client = app.test_client()

    response = client.post(
        "/items",
        json={"name": "Mouse", "price": 99},
    )

    assert response.status_code == 201
    body = response.get_json()
    assert body["name"] == "Mouse"
    assert body["price"] == 99


def test_reject_invalid_item():
    app = create_app({"TESTING": True})
    client = app.test_client()

    response = client.post("/items", json={"name": "", "price": -1})

    assert response.status_code == 400

运行：

pytest

测试重点不是“把每一行都跑一遍”，而是保护接口行为：状态码、响应结构、错误分支、鉴权和关键业务规则。这样后面把内存字典替换成数据库时，测试能告诉你外部行为有没有变。

十、错误处理与状态码

Flask 允许你直接返回 (body, status_code)：

`1`	`return {"error": "item not found"}, 404`

也可以使用 abort：

from flask import abort


@app.get("/items/<int:item_id>")
def read_item(item_id: int):
    item = items.get(item_id)

    if item is None:
        abort(404)

    return item

如果想统一错误结构，可以注册错误处理器：

@app.errorhandler(404)
def not_found(error):
    return {"error": "not found"}, 404


@app.errorhandler(500)
def internal_error(error):
    return {"error": "internal server error"}, 500

常用状态码：

状态码	场景
`200 OK`	查询成功
`201 Created`	创建成功
`204 No Content`	删除成功且无响应体
`400 Bad Request`	参数语义错误
`401 Unauthorized`	未登录或凭证无效
`403 Forbidden`	已登录但无权限
`404 Not Found`	资源不存在
`409 Conflict`	资源冲突
`500 Internal Server Error`	未预期服务端错误

如果你写的是 API，建议从一开始就统一错误格式。否则前端会在不同接口里解析不同形状的错误响应。

十一、从开发到生产部署

本地开发命令：

`1`	`flask --app app run --debug`

但 Flask 官方文档明确提醒：内置开发服务器只用于本地开发，不要用于生产。生产环境应交给 WSGI Server 或托管平台。

Windows 上可以用 Waitress：

1
2

pip install waitress
waitress-serve --host=0.0.0.0 --port=8000 "app:create_app()"

Linux 服务器上常见组合是 Gunicorn + Nginx：

1
2

pip install gunicorn
gunicorn "app:create_app()" --bind 0.0.0.0:8000 --workers 4

一个最小 Dockerfile：

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

EXPOSE 8000
CMD ["gunicorn", "app:create_app()", "--bind", "0.0.0.0:8000", "--workers", "4"]

生产前至少补齐：

项目	原因
固定依赖版本	避免构建时引入不可预期更新
环境变量	密钥、数据库地址、第三方 Token 不写进代码
`SECRET_KEY`	Session、CSRF 等安全能力依赖它
数据库迁移	schema 变化可追踪、可回滚
结构化日志	方便排查线上问题
健康检查	让负载均衡知道应用是否可用
HTTPS	保护 Cookie、登录态和敏感请求
反向代理	处理静态资源、TLS、压缩、限流等入口能力

十二、Flask 常见坑

坑	更稳的做法
所有代码堆在 `app.py`	入门可以，项目变大后用应用工厂和 Blueprint
把开发服务器用于生产	生产使用 Gunicorn、Waitress、uWSGI 或托管平台
不设置 `SECRET_KEY`	从环境变量读取，并在生产环境使用强随机值
手写 HTML 字符串	用 Jinja2 模板，避免未转义内容混入页面
表单写入不做 CSRF	页面项目使用 Flask-WTF 或等价方案
SQL 用字符串拼接	使用 ORM 或参数化 SQL
错误响应格式不统一	API 项目尽早统一错误结构
Blueprint 里塞太多业务	路由负责 HTTP，复杂规则移到 service 层

十三、Flask 与 FastAPI 怎么选

维度	Flask	FastAPI
框架风格	轻量、自由、扩展组合	类型驱动、API 契约强
页面渲染	Jinja2 体验成熟	也能做，但主流认知偏 API
请求校验	需要自己选扩展或手写	Pydantic 深度集成
自动文档	需要扩展	内置 OpenAPI 文档
异步支持	不是核心优势	ASGI 原生更适合异步 API
入门感受	概念少，适合理解 Web 本质	工程化 API 体验更完整

如果你想理解 Web 后端的底层主线，或者写一个页面 + 少量 API 的项目，Flask 很舒服。如果你目标是类型契约明确的纯 API 服务，尤其需要自动 OpenAPI 文档，FastAPI 往往更省心。

十四、学习路线

建议按这个顺序继续：

Jinja2 模板继承、宏和过滤器；
Blueprint 和应用工厂；
Flask-SQLAlchemy + Flask-Migrate；
Flask-WTF 和 CSRF；
Flask-Login；
错误处理和日志；
pytest + test client；
Gunicorn / Waitress / Docker 部署；
Nginx、HTTPS 和线上监控。

Flask 的好处是你可以每次只学一小块。先把请求响应、模板和测试跑通，再慢慢引入数据库、登录、表单和部署能力，学习曲线会平滑很多。

参考资料

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

Tue, 15 Sep 2026 22:10:00 +0800

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

如果你已经会 Python 函数、类型提示、虚拟环境和一点 HTTP 基础，FastAPI 会给你一种很顺手的体验：你写普通函数和 Pydantic 模型，它负责把请求解析、参数校验、JSON 序列化和 OpenAPI 文档串起来。

这篇文章不从“什么是 Web 框架”讲起，而是面向已经有 Python 基础的开发者，直接搭一个可运行的小 API，再逐步补上工程里绕不开的几件事：数据校验、错误处理、依赖注入、异步选择、项目拆分、测试和部署。

你已有的 Python 能力	在 FastAPI 中会怎样复用
函数与装饰器	一个路径函数就是一个接口处理函数
类型提示	自动解析路径参数、查询参数和请求体
类与数据模型	用 Pydantic 定义请求和响应契约
异常处理	用 `HTTPException` 表达 HTTP 错误
模块拆分	用 `APIRouter` 管理多组接口
测试习惯	用 `TestClient` 写接口级单元测试

一、FastAPI 解决的核心问题

FastAPI 的价值不是“少写几行 Flask 代码”，而是把现代 API 后端中高频出现的一组能力整合在一起：

基于类型提示的参数解析；
基于 Pydantic 的请求体和响应体校验；
自动生成 OpenAPI、Swagger UI 和 ReDoc；
支持同步函数和异步函数；
通过依赖注入组织鉴权、数据库会话、配置读取等横切逻辑；
基于 ASGI，天然适合高并发 I/O 场景。

一次请求进入 FastAPI 后，通常会经过这样的链路：

Uvicorn 这类 ASGI Server 接收 HTTP 请求；
FastAPI 根据 method 和 path 找到路径函数；
解析 path、query、header、cookie、body 等输入；
用 Pydantic 做类型转换和约束校验；
执行业务函数；
根据 response_model 输出稳定 JSON 结构；
同步更新 OpenAPI 文档。

也就是说，FastAPI 希望你把“接口契约”尽量写进 Python 类型和模型里，而不是散落在注释、Wiki 和前端口头约定中。

二、环境准备

截至本文写作时，FastAPI 官方文档推荐安装标准依赖包：

`1`	`pip install "fastapi[standard]"`

建议从一个干净虚拟环境开始：

mkdir fastapi-shop
cd fastapi-shop

python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

pip install "fastapi[standard]"

其中 fastapi[standard] 会带上常用运行和开发能力，比如 ASGI Server、交互式文档相关依赖等。如果你在生产项目中追求更小依赖面，也可以研究 fastapi-slim，但入门和多数业务项目建议先用标准安装。

三、第一个可运行 API

先写一个单文件版本，文件名为 main.py：

from typing import Annotated
from uuid import UUID, uuid4

from fastapi import Depends, FastAPI, Header, HTTPException, Query, status
from pydantic import BaseModel, Field


app = FastAPI(
    title="FastAPI Shop",
    version="0.1.0",
    description="A tiny shop API built with FastAPI.",
)


class ItemCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=80, examples=["Keyboard"])
    price: float = Field(..., gt=0, examples=[299.0])
    tags: list[str] = Field(default_factory=list, max_length=10)


class ItemUpdate(BaseModel):
    name: str | None = Field(default=None, min_length=1, max_length=80)
    price: float | None = Field(default=None, gt=0)
    tags: list[str] | None = Field(default=None, max_length=10)


class ItemRead(BaseModel):
    id: UUID
    name: str
    price: float
    tags: list[str]


items: dict[UUID, ItemRead] = {}


def require_token(
    x_token: Annotated[str | None, Header(alias="X-Token")] = None,
) -> str:
    if x_token != "dev-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token",
        )
    return x_token


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/items", response_model=list[ItemRead])
def list_items(
    token: Annotated[str, Depends(require_token)],
    q: Annotated[str | None, Query(min_length=1, max_length=30)] = None,
) -> list[ItemRead]:
    result = list(items.values())

    if q is None:
        return result

    keyword = q.lower()
    return [item for item in result if keyword in item.name.lower()]


@app.post("/items", response_model=ItemRead, status_code=status.HTTP_201_CREATED)
def create_item(
    data: ItemCreate,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    item = ItemRead(id=uuid4(), **data.model_dump())
    items[item.id] = item
    return item


@app.get("/items/{item_id}", response_model=ItemRead)
def read_item(
    item_id: UUID,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    try:
        return items[item_id]
    except KeyError:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )


@app.patch("/items/{item_id}", response_model=ItemRead)
def update_item(
    item_id: UUID,
    data: ItemUpdate,
    token: Annotated[str, Depends(require_token)],
) -> ItemRead:
    item = read_item(item_id, token)
    updates = data.model_dump(exclude_unset=True)
    updates = {key: value for key, value in updates.items() if value is not None}
    updated = item.model_copy(update=updates)
    items[item_id] = updated
    return updated


@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(
    item_id: UUID,
    token: Annotated[str, Depends(require_token)],
) -> None:
    if item_id not in items:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    del items[item_id]

启动开发服务器：

`1`	`fastapi dev main.py`

如果你的环境没有 FastAPI CLI，也可以用 Uvicorn：

`1`	`uvicorn main:app --reload`

打开：

http://127.0.0.1:8000/health
http://127.0.0.1:8000/docs
http://127.0.0.1:8000/redoc
http://127.0.0.1:8000/openapi.json

试着创建一个商品：

curl -X POST "http://127.0.0.1:8000/items" \
  -H "Content-Type: application/json" \
  -H "X-Token: dev-token" \
  -d '{"name":"Keyboard","price":299,"tags":["peripheral"]}'

如果你把 price 改成负数，FastAPI 会直接返回 422 Unprocessable Entity，并告诉你哪个字段不符合约束。你不需要在业务函数里手写一堆 if price <= 0。

四、类型提示如何变成接口契约

FastAPI 里有三类输入最常见：

输入位置	示例	FastAPI 如何识别
路径参数	`/items/{item_id}`	函数参数名与路径模板一致
查询参数	`/items?q=key`	函数参数不在路径里，且不是 Pydantic body
请求体	JSON body	参数类型继承自 `BaseModel`

例如：

@app.get("/items/{item_id}")
def read_item(
    item_id: UUID,
    q: Annotated[str | None, Query(min_length=1)] = None,
) -> dict[str, str]:
    return {"item_id": str(item_id), "q": q or ""}

这里 item_id: UUID 会让 FastAPI 自动把字符串转换为 UUID 对象；如果传入的路径不是合法 UUID，请求会在进入函数前失败。

Annotated 的好处是把“类型”和“接口约束”分开：

`1`	`q: Annotated[str \| None, Query(min_length=1, max_length=30)] = None`

读作：q 的业务类型是 str | None，同时它作为查询参数时必须满足长度约束。这样写比把校验逻辑塞进函数体更清晰，也能同步生成文档。

五、Pydantic：把边界数据变可信

Pydantic 是 FastAPI 的数据契约核心。请求进入系统时，外部世界给你的都是“不可信字符串或 JSON”；经过 Pydantic 模型之后，业务函数拿到的是已经转换和校验过的 Python 对象。

请求模型和响应模型建议分开写：

class UserCreate(BaseModel):
    email: str
    password: str


class UserRead(BaseModel):
    id: UUID
    email: str

这样做有两个直接收益：

password 可以出现在创建请求里，但不会从响应里泄漏出去；
数据库模型、请求模型、响应模型不再互相污染。

response_model 还有一个经常被低估的价值：它能过滤掉你不想暴露的字段。

@app.post("/users", response_model=UserRead)
def create_user(data: UserCreate) -> dict[str, object]:
    return {
        "id": uuid4(),
        "email": data.email,
        "password_hash": "internal-only",
    }

即使函数返回值里有 password_hash，最终响应也只会保留 UserRead 声明的字段。对于 API 稳定性和安全边界，这一点很重要。

六、依赖注入：把横切逻辑拿出接口函数

开发业务 API 时，很多逻辑并不属于某一个接口：

读取当前登录用户；
校验 Token；
创建数据库 Session；
读取配置；
记录审计日志；
检查权限。

FastAPI 用 Depends 处理这类逻辑。前面的 require_token 就是一个最小例子：

def require_token(
    x_token: Annotated[str | None, Header(alias="X-Token")] = None,
) -> str:
    if x_token != "dev-token":
        raise HTTPException(status_code=401, detail="Invalid token")
    return x_token

在接口中声明依赖：

1
2
3

@app.get("/items")
def list_items(token: Annotated[str, Depends(require_token)]) -> list[ItemRead]:
    return list(items.values())

这样接口函数会在执行前先运行 require_token。如果依赖抛出异常，业务函数不会继续执行。

依赖也可以继续依赖其他依赖：

def get_settings() -> Settings:
    return Settings()


def get_repository(
    settings: Annotated[Settings, Depends(get_settings)],
) -> ItemRepository:
    return ItemRepository(settings.database_url)

这种组合方式让 FastAPI 项目很适合做“薄接口层 + 明确业务层”的结构。

七、项目变大后怎么拆

单文件很适合入门，但真实项目通常会快速长出用户、订单、支付、后台管理、文件上传等资源。推荐按职责拆分，而不是按“今天写了哪个接口”随手堆文件。

一个常见结构是：

fastapi-shop/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── routers/
│   │       ├── items.py
│   │       └── users.py
│   ├── core/
│   │   └── config.py
│   ├── schemas.py
│   ├── models.py
│   ├── services.py
│   └── db.py
├── tests/
│   └── test_items.py
└── requirements.txt

app/api/routers/items.py 可以这样写：

from typing import Annotated
from uuid import UUID

from fastapi import APIRouter, Depends

from app.schemas import ItemCreate, ItemRead
from app.services import ItemService, get_item_service


router = APIRouter(prefix="/items", tags=["items"])


@router.post("", response_model=ItemRead, status_code=201)
def create_item(
    data: ItemCreate,
    service: Annotated[ItemService, Depends(get_item_service)],
) -> ItemRead:
    return service.create(data)


@router.get("/{item_id}", response_model=ItemRead)
def read_item(
    item_id: UUID,
    service: Annotated[ItemService, Depends(get_item_service)],
) -> ItemRead:
    return service.get(item_id)

app/main.py 只负责组装：

from fastapi import FastAPI

from app.api.routers import items


app = FastAPI(title="FastAPI Shop")
app.include_router(items.router)

这里有一个判断标准：如果路由函数开始出现复杂分支、数据库查询细节、外部 API 调用和权限规则，说明它已经不只是“HTTP 编排”了，应该把逻辑移到 service 或 repository 层。

八、`async def` 不等于自动更快

FastAPI 支持两种路径函数：

@app.get("/sync")
def sync_handler() -> dict[str, str]:
    return {"mode": "sync"}


@app.get("/async")
async def async_handler() -> dict[str, str]:
    return {"mode": "async"}

什么时候用 async def？先看函数内部在做什么。

可以用这张表快速判断：

场景	建议
调用 async 数据库驱动，如 async SQLAlchemy、asyncpg	用 `async def`
调用 async HTTP 客户端，如 httpx.AsyncClient	用 `async def`
调用普通同步库，如 requests、同步数据库驱动	用 `def`，或放到线程池/任务队列
做大量 CPU 计算，如图像处理、模型推理	不要指望 `async` 提速，考虑进程池或后台任务
不确定库是否异步	先按同步写，确认后再改

最常见的坑是：写了 async def，但函数内部直接调用 requests.get() 或同步数据库驱动。这会阻塞事件循环，让其他请求也跟着等待。

如果需要在接口中调用外部 HTTP 服务，可以这样：

import httpx


@app.get("/exchange-rate")
async def get_exchange_rate() -> dict[str, float]:
    async with httpx.AsyncClient(timeout=5) as client:
        response = await client.get("https://api.example.com/rate")
        response.raise_for_status()
    return response.json()

注意：异步不是语法装饰，它是一种 I/O 调度模型。只有你的数据库、HTTP 客户端、缓存客户端等调用链也支持 async，收益才会明显。

九、错误处理与状态码

HTTP API 不应该只返回 200，然后把错误塞进 JSON 里的 code 字段。状态码本身就是协议的一部分。

常用状态码可以这样理解：

状态码	适用场景
`200 OK`	查询、更新成功并返回内容
`201 Created`	创建资源成功
`204 No Content`	删除成功且不返回 body
`400 Bad Request`	请求语义不合法
`401 Unauthorized`	没有有效身份凭证
`403 Forbidden`	已登录但没有权限
`404 Not Found`	资源不存在
`409 Conflict`	资源状态冲突，如重复创建
`422 Unprocessable Entity`	参数类型或字段约束不通过

FastAPI 中可以用 HTTPException 表达业务错误：

from fastapi import HTTPException, status


def get_item_or_404(item_id: UUID) -> ItemRead:
    item = items.get(item_id)
    if item is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    return item

如果项目中错误结构需要统一，比如都返回 {"code": "...", "message": "..."}，可以再引入全局异常处理器。但在入门阶段，先把正确状态码用好，比过早设计复杂错误体系更重要。

十、测试：用接口行为保护重构

FastAPI 提供 TestClient，可以像调用普通 HTTP 接口一样测试你的应用。

安装测试依赖：

`1`	`pip install pytest`

tests/test_items.py：

from fastapi.testclient import TestClient

from main import app


client = TestClient(app)


def test_create_item() -> None:
    response = client.post(
        "/items",
        headers={"X-Token": "dev-token"},
        json={"name": "Mouse", "price": 99.0, "tags": ["peripheral"]},
    )

    assert response.status_code == 201
    body = response.json()
    assert body["name"] == "Mouse"
    assert body["price"] == 99.0
    assert "id" in body


def test_reject_invalid_price() -> None:
    response = client.post(
        "/items",
        headers={"X-Token": "dev-token"},
        json={"name": "Mouse", "price": -1},
    )

    assert response.status_code == 422


def test_reject_missing_token() -> None:
    response = client.get("/items")

    assert response.status_code == 401

运行：

pytest

接口测试的重点不是追求行覆盖率，而是锁住 API 行为：状态码、响应字段、错误场景和鉴权路径。只要这些行为被测试保护，后面把内存字典替换成数据库时就安心很多。

十一、部署前需要想清楚的事

本地开发时可以用：

`1`	`fastapi dev main.py`

生产环境不要直接用开发命令。你可以使用 FastAPI CLI 的生产命令：

`1`	`fastapi run app/main.py --host 0.0.0.0 --port 8000`

也可以显式使用 Uvicorn：

`1`	`uvicorn app.main:app --host 0.0.0.0 --port 8000`

一个最小 Dockerfile 可以长这样：

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

EXPOSE 8000
CMD ["fastapi", "run", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]

生产环境至少要补齐这些点：

项目	为什么重要
固定依赖版本	避免一次重新构建引入不可预期变更
环境变量管理	数据库地址、密钥、第三方 Token 不要写死在代码里
健康检查	让负载均衡和容器平台知道服务是否可用
结构化日志	方便按 request_id、user_id、status_code 排查问题
数据库迁移	用 Alembic 等工具管理 schema 变化
超时与重试	防止外部服务拖垮自己的接口
限流与鉴权	公开 API 必须考虑滥用和越权
HTTPS 与反向代理	生产入口通常交给 Nginx、Traefik、云负载均衡等

十二、常见坑

坑	更稳的做法
把所有代码写进 `main.py`	入门可以，变大后用 `APIRouter`、service、db 分层
路由函数里写大量业务分支	路由层只处理 HTTP，业务规则移到 service
不写 `response_model`	为公开 API 写响应模型，保护字段边界
`async def` 里调用同步阻塞库	同步库用 `def`，异步链路才用 `async def`
返回 `200` 表示所有结果	正确使用 `201`、`204`、`401`、`404`、`409`、`422`
把密钥写进代码	用环境变量或 Secret 管理
不写测试就接数据库	先用行为测试保护接口，再替换持久化实现

十三、学习路线

到这里，你已经掌握了 FastAPI 最重要的主干。接下来可以按这个顺序继续：

SQLAlchemy 2.x 或 SQLModel：把内存字典换成数据库；
Alembic：管理数据库迁移；
OAuth2 / JWT：实现真实登录鉴权；
BackgroundTasks / Celery / RQ：处理慢任务；
中间件：统一日志、request_id、CORS、耗时统计；
OpenTelemetry：接入链路追踪；
Docker Compose / Kubernetes：把 API、数据库、缓存组成可部署系统。

FastAPI 的学习曲线很友好，但它不是“玩具框架”。当你把类型契约、依赖注入、测试和部署纪律一起用起来，它完全可以支撑严肃的生产 API。

参考资料

从峡湾到极光：2015—2024 年北欧五国入境旅游可视分析

Wed, 15 Jul 2026 16:00:00 +0800

从峡湾到极光：2015—2024 年北欧五国入境旅游可视分析

这个页面是《数据可视化》课程大作业的公开展示入口。原项目使用 Streamlit 实现多页面交互应用；博客上的版本导出为静态 HTML，保留 Plotly 图表的悬停、缩放、图例开关等交互，适合通过 GitHub Pages 直接访问。

打开完整静态展示页

发布方式

当前博客是 Hugo 静态站点，不能直接运行 Streamlit 的 Python 服务。因此这里采用“静态导出 + 博客嵌入”的方式：

方案	适合场景	结果
静态导出到 Hugo	希望随博客一起发布、长期稳定访问	本文嵌入的静态展示页
Streamlit Cloud / Render 部署	必须保留侧边栏筛选、多页面跳转和下载按钮	需要额外部署一个 Python Web 服务，再从博客链接过去

本静态页使用真实处理后数据生成，不包含模拟数据；其中年度总览默认展示 2024 年，客源市场结构默认展示覆盖五国更完整的 2023 年。

PyTorch

Thu, 02 Apr 2026 15:23:58 +0800

PyTorch 是当前最流行的深度学习框架之一，由 Meta（原 Facebook）开源，凭借其简洁的 Python 语法、动态图机制和友好的调试体验，成为了深度学习入门的首选框架。

这份文档将带你从零开始，一步一步掌握 PyTorch 的核心知识，不需要你有任何深度学习基础，只要你会基础的 Python 编程，就能跟着这份指南，最终完成你的第一个 AI 项目 —— 手写数字识别。

第一章：环境搭建：保姆级安装教程

对于零基础的你来说，第一步就是把环境搭好，这是所有学习的基础。我们会覆盖 Windows、Linux、Mac 全平台，以及 CPU 和 GPU 版本的安装。

1.1 为什么要使用虚拟环境？

在安装 PyTorch 之前，强烈推荐你使用 Anaconda/Miniconda 来管理 Python 环境。它可以帮你：

隔离不同项目的依赖，避免包版本冲突
一键创建干净的环境，不会搞乱你的系统 Python
方便的管理不同版本的 Python 和 CUDA

如果你还没有安装 Miniconda，可以先去官网下载，选择对应你系统的版本，一路默认安装即可。

1.2 创建并激活虚拟环境

打开你的终端（Windows 用 Anaconda Prompt，Linux/Mac 用终端），输入以下命令：

# 创建一个名为 learn_pytorch 的虚拟环境，Python 版本选择 3.10（最稳定兼容的版本）
conda create -n learn_pytorch python=3.10 -y

# 激活这个环境
conda activate learn_pytorch

激活成功后，你会看到你的终端前缀变成了 (learn_pytorch)，这说明你已经进入了这个独立的环境，接下来的所有安装都只会在这个环境里生效，不会影响你的系统。

1.3 安装 PyTorch：CPU 版本（通用）

如果你没有 NVIDIA 显卡，或者只是想先试试，直接安装 CPU 版本就可以了，所有平台通用：

Pip 安装（简单直接）

`1`	`pip install torch torchvision torchaudio`

Conda 安装（更稳定）

`1`	`conda install pytorch torchvision torchaudio cpuonly -c pytorch`

1.4 安装 PyTorch：GPU 版本（NVIDIA 显卡专属）

如果你有 NVIDIA 显卡，强烈建议安装 GPU 版本，它能让你的训练速度提升几十甚至上百倍！

第一步：检查你的显卡支持的 CUDA 版本

打开终端，输入：

`1`	`nvidia-smi`

你会看到类似下面的输出：

注意右上角的 CUDA Version: 12.7，这是你的显卡驱动最高支持的 CUDA 版本，你安装的 PyTorch 的 CUDA 版本不能超过这个值！

第二步：根据你的 CUDA 版本安装 PyTorch

比如你的显卡支持 CUDA 12.7，就用下面的命令，因为没有 CUDA 12.7 的预编译版本，这里使用 12.6 的版本：

Pip 安装

`1`	`pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu126`

💡 如果你是其他 CUDA 版本，比如 11.8，只需要把上面的 12.6 换成 11.8 就可以了。

你也可以直接去PyTorch 官网，选择你的系统和配置，官网会自动给你生成对应的安装命令，绝对不会错！

1.5 Mac 用户专属：M 芯片的 GPU 加速

如果你用的是苹果的 M1/M2/M3 芯片，PyTorch 已经原生支持了 Metal 加速，不需要额外安装 CUDA，直接安装默认版本就可以自动使用 GPU 加速了：

`1`	`conda install pytorch torchvision torchaudio -c pytorch`

1.6 验证安装是否成功

安装完成后，我们来验证一下环境是否正常：

在终端里输入 python 进入 Python 交互环境，然后输入下面的代码：

import torch

# 打印 PyTorch 版本
print(f"PyTorch 版本: {torch.__version__}")

# 检查 CUDA 是否可用（GPU 版本才会是 True）
print(f"CUDA 是否可用: {torch.cuda.is_available()}")

# 检查 MPS 是否可用（Mac M 芯片才会是 True）
print(f"MPS 是否可用: {torch.backends.mps.is_available()}")

# 测试创建一个张量
x = torch.rand(5, 3)
print("创建的随机张量:")
print(x)

如果能正常输出，没有报错，说明你的环境已经安装成功了！

1.7 VS Code 用户专属：安装 Python 插件

如果你使用 VS Code 作为你的代码编辑器，强烈建议安装官方的 Python 插件，这样你就可以在 VS Code 里直接运行 Python 代码，调试也非常方便。

安装完成后，打开你的 Python 文件，观察 VS Code 窗口的右下角，你会看到当前使用的 Python 版本号，点击它可以选择你刚才创建的 learn_pytorch 虚拟环境，这样你在 VS Code 里运行代码的时候，就会使用这个环境里的 PyTorch 了！

可以在VS Code的终端中输入 python，然后输入 import torch; print(torch.__version__) 来验证一下 VS Code 是否正确识别了你的环境。如果不能识别，重启VS Code的终端即可。

1.8 安装常见问题解决

问题 1：下载速度太慢？

用国内的镜像源加速：

# Pip 清华源
pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple

# Conda 清华源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/

问题 2：CUDA 不可用？

检查你的 PyTorch 版本和 CUDA 版本是否匹配
检查你的显卡是否是 NVIDIA 的（AMD 显卡不支持 CUDA）
尝试重新安装对应 CUDA 版本的 PyTorch

问题 3：Windows 下安装报错？

安装 VC_redist.x64.exe，解决 DLL 依赖问题

第二章：核心基础：张量（Tensor）——PyTorch 的数字积木

环境搭好了，接下来我们来学习 PyTorch 最基础的概念：张量（Tensor）。

2.1 什么是张量？

简单来说，张量就是一个多维数组。你可以把它理解为升级版的 NumPy 数组，但是它有两个超能力：

可以在 GPU 上运行，加速计算
可以自动记录计算历史，帮你自动求导

我们平时接触的所有数据，最终都会变成张量，才能在 PyTorch 里处理。

维度	名称	生活中的例子
0 维	标量	一个单独的数字，比如 `5`、`3.14`
1 维	向量	一行数据，比如 `[1,2,3,4]`，就像你的成绩单
2 维	矩阵	一个表格，比如 Excel 的二维表格
3 维	3D 张量	一张彩色图片，形状是 `(高, 宽, 通道)`，比如 28×28 的灰度图是 `(28,28,1)`
4 维	4D 张量	一批图片，形状是 `(批次, 通道, 高, 宽)`，比如一次喂 32 张图片就是 `(32,1,28,28)`

2.2 如何创建张量？

PyTorch 提供了非常多的方式来创建张量，我们一个个来看：

1. 从 Python 列表直接创建

这是最基础的方式：

import torch
import numpy as np

# ======== 从 Python 列表创建张量 ========
# 从列表创建1维张量
t1 = torch.tensor([1, 2, 3, 4])
print(t1)

# 从二维列表创建2维张量
t2 = torch.tensor([[1, 2], [3, 4]])
print(t2)

# 如果把tensor大写为Tensor，则会创建一个默认类型的张量，通常是torch.float32
t3 = torch.Tensor([1, 2, 3, 4])
print(t3)

print("==============================")

⚠️ 避坑提醒：永远用小写的 torch.tensor()，不要用大写的 torch.Tensor()！如果把tensor大写为Tensor，则会创建一个默认类型的张量，通常是torch.float32，这可能会导致你后续的计算出现类型不匹配的错误，尤其是当你想创建整数张量时。

2. 从 NumPy 数组创建

如果你已经有了 NumPy 数组，可以直接转成张量：

# ======== 从 NumPy 数组创建张量 ========
# 创建一个 NumPy 数组
np_arr = np.array([[1, 2], [3, 4]])
print(np_arr)

# 转成 PyTorch 张量
t4 = torch.from_numpy(np_arr)
print(t4)

# 默认情况下，torch.from_numpy() 创建的张量与原始 NumPy 数组共享内存。这意味着修改张量会影响原始数组，反之亦然。
t4[0, 0] = 10  # 修改张量的值
print(t4)       # 张量被修改了
print(np_arr)   # NumPy 数组也被修改了，因为它们共享内存

# 如果不想共享内存，可以使用 torch.tensor() 来创建一个新的张量
t5 = torch.tensor(np_arr)
# 查看 t5 和 np_arr 的内存地址
print("t5 内存地址:", t5.data_ptr())
print("np_arr 内存地址:", np_arr.__array_interface__['data'][0])

💡 注意：默认情况下，NumPy 数组和张量是共享内存的！修改其中一个，另一个也会跟着变！如果你想要独立的副本，用 t3 = torch.tensor(np_arr)，这会做一个深拷贝。

3. 创建特殊值的张量

很多时候我们需要创建全 0、全 1、或者随机的张量：

# ======== 创建特殊值的张量 ========
# 创建全零张量
t_zeros = torch.zeros((2, 3))
print(t_zeros)

# 创建全一张量
t_ones = torch.ones((2, 3))
print(t_ones)

# 创建指定值的张量，比如666
t_full = torch.full((2, 3), 666)
print(t_full)

# 单位矩阵
t_eye = torch.eye(3)
print(t_eye)

4. 创建随机张量

深度学习里我们经常需要随机初始化权重，PyTorch 提供了很多随机函数：

# ======== 创建随机张量 ========
# [0, 1) 均匀分布的随机张量
t_rand = torch.rand((2, 4))
print(t_rand)

# 标准正态分布（均值0，方差1）的随机数，这是权重初始化最常用的
t_randn = torch.randn((2, 3))
print(t_randn)

# 随机整数，范围是 [1,10)，形状是 2x3
t_randint = torch.randint(1, 10, (2,3))
print(t_randint)

5. _like 系列：自动匹配形状

如果你想创建一个和已有张量形状一样的新张量，用 _like 系列函数，不用手动写形状，非常方便：

# ======== _like 系列：自动匹配形状 ========
# 假设外面已经有一个张量
old_t = torch.randn((2,3))

# 创建一个和 old_t 形状研一的全1张量
new_t = torch.ones_like(old_t)
print(new_t.size())
# 或者print(new_t.shape)  # 都会输出 torch.Size([2, 3])

# 同理还有 zeros_like, full_like, rand_like 等等

2.3 张量的属性

每个张量都有几个核心属性：

import torch
import numpy as np

t = torch.randn((3,4))

print(f"形状：{t.shape}")       # 张量的维度大小
print(f"数据类型：{t.dtype}")   # 里面元素的类型，默认是 float32
print(f"存储设备：{t.device}")  # 存在 CPU 还是 GPU 上


# 如果你有GPU，只需要一行代码，就能把张量移动到GPU上加速
# 自动选择设备：有GPU用GPU，否则用CPU
device = "cuda" if torch.cuda.is_available() else "cpu"

# 把张量移动到GPU上
t = t.to(device)
print(f"存储设备：{t.device}")  # 存在 CPU 还是 GPU 上

2.4 张量的基本操作

张量的操作和 NumPy 几乎一模一样，如果你会 NumPy，那你直接就会用了！

1. 索引和切片

和 Python 列表、NumPy 一样，你可以索引和切片张量：

import torch
import numpy as np

# ========= 索引和切片 =========
t = torch.tensor([[1,2,3,4],[5,6,7,8],[9,10,11,12]])

# 取第0行
print(t[0])

# 取第0列，[行，列]，:表示所有行
print(t[:,0])

# 取最后一列，-1表示最后一个元素
print(t[:,-1])

2. 算术运算

# ========= 算术运算 =========
a = torch.tensor([1,2,3])
b = torch.tensor([4,5,6])

# 元素相加，对应位置元素相加，等价于torch.add(a,b)
print(a + b)

# 元素相乘，对应位置元素相乘，等价于torch.mul(a,b)
print(a * b)

# 矩阵乘法，对应位置元素相乘再加起来，等价于torch.matmul(a,b)
print(a @ b)

3. 形状变换

很多时候我们需要改变张量的形状，比如把图片展平：

# ========= 形状变换 =========
t = torch.randn([4,4])
print(t.shape)

# 展开成 1 维
t_flat = t.reshape(16)
print(t_flat.shape)

# 也可以用 -1 让 PyTorch 自动计算维度，-1表示自动推断维度大小
t_flat2 = t.reshape(-1)
print(t_flat2.shape)

# 转成2行8列
t2 = t.reshape([2,8])
print(t2.shape)

# 也可指定行，自动推断列
t3 = t.reshape([2, -1])
print(t3.shape)

4. 把张量移到 GPU 上

如果你有 GPU，只需要一行代码，就能把张量移到 GPU 上加速：

# ========= 把张量转移到GPU上 =========
print(t.device)
device = "cuda" if torch.cuda.is_available() else "cpu"
t = t.to(device)
print(t.device)

第三章：自动微分（Autograd）——PyTorch 的灵魂

学完了张量，接下来我们来学习 PyTorch 最核心的功能：自动微分。这也是为什么 PyTorch 能这么方便的训练神经网络的原因。

3.1 什么是自动微分？

深度学习训练的核心就是反向传播，简单来说就是：我们计算出预测的误差（损失）之后，要把这个误差反向传给每一个参数，然后根据误差调整参数，让误差越来越小。

这个过程里最麻烦的就是求梯度（也就是求导），手动求导太麻烦了，而 PyTorch 的自动微分可以帮你自动计算所有参数的梯度，你只需要写前向传播的代码，剩下的求导 PyTorch 帮你搞定！

3.2 一个最简单的例子

我们来看一个最简单的例子，帮你理解自动微分：

import torch
import numpy as np

# 定义一个参数w，我们要对他求导，所以设置requires_grad = True
# requires_grad是PyTorch中一个非常重要的属性，它告诉PyTorch需要对这个张量进行梯度计算。只有设置了requires_grad=True的张量，PyTorch才会在反向传播过程中计算它的梯度。
w = torch.tensor(10.0, requires_grad=True)

# 前向传播：我们的损失函数是 loss = 2 * w²
loss = 2 * w ** 2

# 反向传播：自动计算梯度，
loss.backward()

# 查看 w 的梯度，也就是 d(loss)/dw，pytorch会自动计算这个值，并存储在 w.grad 中
print(w.grad)

我们手动算一下：对 loss=2w² 求导，导数是 4w，w 是 10，所以导数是 40，和 PyTorch 算出来的一模一样！

就这么简单！PyTorch 自动帮你完成了求导，你完全不用管中间的过程！

3.3 核心概念解释

requires_grad=True：告诉 PyTorch，这个张量是需要求梯度的，你要记录它的所有计算历史。
计算图：当你做前向计算的时候，PyTorch 会在背后偷偷构建一个动态的计算图，记录所有的操作。
loss.backward()：触发反向传播，从损失开始，沿着计算图反向遍历，自动算出所有 requires_grad=True 的张量的梯度。
w.grad：计算出来的梯度会存在张量的 .grad 属性里，你可以直接用它来更新参数。

3.4 训练循环的核心模板

这是所有深度学习训练的核心模板，你一定要记住：

# 1. 梯度清零！PyTorch 默认会累积梯度，所以每次迭代都要清零！
optimizer.zero_grad()

# 2. 前向传播：计算预测值和损失
output = model(input)
loss = loss_fn(output, target)

# 3. 反向传播：自动计算梯度
loss.backward()

# 4. 更新参数：根据梯度更新模型的参数
optimizer.step()

⚠️ 最重要的坑：梯度清零！如果你忘记了 optimizer.zero_grad()，梯度会一直累加，导致你的训练完全乱掉！这是新手最常见的错误！

第四章：数据加载：把数据喂给模型

数据是深度学习的燃料，PyTorch 提供了非常方便的工具来加载和处理数据，核心就是两个类：Dataset 和 DataLoader。

4.1 Dataset：你的数据集

Dataset 是 PyTorch 对数据集的抽象，它代表了你的所有样本。你可以用内置的数据集，也可以自定义自己的。

内置的数据集比如 MNIST、CIFAR10 等等，PyTorch 已经帮你下载好了，你只需要一行代码就能加载：

from torchvision import datasets
from torchvision.transforms import ToTensor

# 加载 MNIST 训练集，自动下载到 data 目录
train_data = datasets.MNIST(
    root="data",        # 数据保存的目录
    train=True,         # True是训练集，False是测试集
    download=True,      # 本地没有就自动下载
    transform=ToTensor()# 把图片转成张量，并且归一化到 0~1
)

4.2 DataLoader：批量加载数据

Dataset 给了你所有的样本，但是训练的时候我们是一批一批的喂给模型的，DataLoader 就是帮你做这个的：

把数据集分成一个个的 batch
自动打乱数据（训练的时候需要）
多线程加载数据，加快速度

from torch.utils.data import DataLoader

train_loader = DataLoader(
    train_data,
    batch_size=32,          # 每个batch 32个样本
    shuffle=True,           # 训练的时候打乱数据，防止过拟合
    num_workers=4,          # 用4个线程加载数据，加快速度
    pin_memory=True         # 加速GPU数据传输
)

DataLoader 核心参数详解

参数	作用	最佳实践
`batch_size`	每个批次的样本数	一般用 32/64/128，根据你的显存调整
`shuffle`	是否打乱数据	训练集设为 True，测试集设为 False
`num_workers`	加载数据的线程数	一般设为 CPU 核心数的一半，不要太大
`pin_memory`	锁页内存，加速 GPU 传输	有 GPU 的话设为 True，能提升速度

⚠️ Windows 注意：如果你用 Windows，并且设置了 num_workers>0，你的代码必须放在 if __name__ == '__main__': 里面，否则会报错！

第五章：构建你的第一个神经网络

现在我们来学习如何用 PyTorch 构建神经网络。

5.1 nn.Module：所有模型的基类

在 PyTorch 里，所有的神经网络模型都要继承 nn.Module 这个基类，你只需要实现两个方法：

__init__：定义你网络的层
forward：定义前向传播的逻辑

5.2 一个简单的全连接网络

我们来定义一个简单的全连接神经网络，也就是多层感知机（MLP）：

import torch.nn as nn

class MyNet(nn.Module):
    def __init__(self):
        super().__init__()      # 必须调用父类的初始化

        # 定义我们的类
        self.flatten = nn.Flatten()     # 展平层，把28x28的图片展平成728维
        self.fc1 = nn.Linear(28*28, 128) # 全连接层（线性层）：输入784，输出128
        self.fc2 = nn.Linear(128, 256)  # 全连接层（线性层）：输入128，输出256
        self.fc3 = nn.Linear(256, 10)   # 输出层：输入256，输出10（对应10个数字）

    def forward(self, x):
        # 前向传播的逻辑，x是输入的张量
        x = self.flatten(x)     # 先展平
        x = self.fc1(x)
        x = torch.relu(x)       # ReLU激活函数，加入非线性
        x = self.fc2(x)
        x = torch.relu(x)
        x = self.fc3(x)

        return x                # 返回输出

就这么简单！一个三层的全连接网络就定义好了！

5.3 损失函数和优化器

定义好模型之后，我们还需要两个东西：

损失函数：用来衡量我们的预测和真实标签的差距
优化器：用来更新模型的参数

# 模型实例化，并且转移到GPU上
device = "cuda" if torch.cuda.is_available() else "cpu"
model = MyNet().to(device)

# 损失函数：多分类任务用交叉熵损失
loss_fn = nn.CrossEntropyLoss()

# 优化器：用Adam优化器优化模型的参数，学习率是0.01
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)

第六章：完整实战：MNIST 手写数字识别

好了，所有的基础我们都学完了，现在我们来做一个完整的实战项目：用 PyTorch 实现手写数字识别，这是深度学习的 Hello World！

6.1 项目介绍

MNIST 是一个经典的数据集，包含了 6 万张训练图片和 1 万张测试图片，都是 28x28 的手写数字灰度图，我们要训练一个模型，能识别这些图片是 0~9 中的哪个数字。

6.2 完整代码

我们把所有的步骤整合起来，你可以直接复制这段代码，运行就能得到结果！

import torch
from torchvision import datasets
from torchvision.transforms import ToTensor
from torch.utils.data import DataLoader
import torch.nn as nn
import matplotlib.pyplot as plt

# ---------------------- 1. 加载数据 ----------------------
print("正在加载数据...")
# 加载 MNIST 训练集，自动下载到data目录
train_data = datasets.MNIST(
    root="data",        # 数据保存的目录
    train=True,         # True是训练集，False是测试集
    download=True,      # 本地没有就自动下载
    transform=ToTensor()# 把图片转成张量，并且归一化到 0~1
)

test_data = datasets.MNIST(
    root="data",
    train=False,
    download=True,
    transform=ToTensor()
)

# train_loader = DataLoader(
#     train_data,
#     batch_size=32,          # 每个batch 32个样本
#     shuffle=True,           # 训练的时候打乱数据，防止过拟合
#     num_workers=4,          # 用4个线程加载数据，加快速度
#     pin_memory=True         # 加速GPU数据传输
# )

# 可视化几个样本看看
figure = plt.figure(figsize=(8, 8))     # figure是画布，figsize是画布大小
for i in range(9):
    img, label = train_data[i + 59000]
    figure.add_subplot(3, 3, i + 1)   # 3行3列的子图，i+1是第几个子图
    plt.title(label)                   # 标题是标签
    plt.axis("off")                    # 不显示坐标轴
    plt.imshow(img.squeeze(), cmap="gray") # 显示图片，squeeze去掉多余的维度，cmap灰度图
plt.show()

# 创建 DataLoader 的迭代器，准备训练
train_dataloader = DataLoader(train_data, batch_size=32, shuffle=True)
test_dataloader = DataLoader(test_data, batch_size=32, shuffle=False)

# ---------------------- 2. 定义模型 ----------------------
# 选择设备
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"使用设备：{device}")

# 定义一个简单的多层感知机（MLP）模型
class Model(nn.Module):
    def __init__(self):
        super().__init__()      # 必须调用父类的初始化
        self.flatten = nn.Flatten()     # 展平层，把28x28的图片展平成728维
        self.hidden1 = nn.Linear(28*28, 128) # 全连接层（线性层）：输入784，输出128
        self.hidden2 = nn.Linear(128, 256)  # 全连接层（线性层）：输入128，输出256
        self.out = nn.Linear(256, 10)   # 输出层：输入256，输出10（对应10个数字）

    def forward(self, x):
        # 前向传播的逻辑，x是输入的张量
        x = self.flatten(x)     # 先展平
        x = self.hidden1(x)
        x = torch.relu(x)       # ReLU激活函数，加入非线性
        x = self.hidden2(x)
        x = torch.relu(x)
        x = self.out(x)

        return x                # 返回输出
    

# 模型实例化，并且转移到GPU上
model = Model().to(device)
print(model)                    # 打印模型结构看看


# ---------------------- 3. 定义损失函数和优化器 ----------------------
# 损失函数：多分类任务用交叉熵损失
loss_fn = nn.CrossEntropyLoss()

# 优化器：用Adam优化器优化模型的参数，学习率是0.01
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)


# ---------------------- 4. 训练模型 ----------------------
def train(dataloader, model, loss_fn, optimizer):
    model.train()   # 设置模型为训练模式
    batch_num = 0   # 记录训练了多少个batch了

    for X, y in dataloader:   # 遍历每个batch的数据
        batch_num += 1
        X, y = X.to(device), y.to(device)   # 把数据转移到GPU上

        # 前向传播
        pred = model(X)    # 模型的预测结果
        loss = loss_fn(pred, y)  # 计算损失

        # 反向传播和优化
        optimizer.zero_grad()   # 清空之前的梯度
        loss.backward()         # 反向传播计算新的梯度
        optimizer.step()        # 更新模型参数

        if batch_num % 100 == 0:   # 每训练100个batch打印一次损失
            print(f"训练了 {batch_num} 个batch，当前损失：{loss.item():.4f}")


# ----------------------- 5. 测试模型 ----------------------
def test(dataloader, model, loss_fn):
    print("正在测试模型...")
    model.eval()    # 设置模型为评估模式
    size = len(dataloader.dataset)  # 测试集的样本数量
    num_batches = len(dataloader)   # 测试集的batch数量
    print(f"测试集样本数量：{size}，batch数量：{num_batches}")
    test_loss, correct = 0, 0       # 累计损失和正确的预测数量
    

    with torch.inference_mode():    # 自动关闭梯度计算，不需要计算梯度了，节省内存和计算
        for X, y in dataloader:     # 遍历每个batch的数据，X是输入，y是标签。为什么X要大写？因为它是一个张量，习惯上张量用大写字母表示。
            X, y = X.to(device), y.to(device)

            pred = model(X)         # 模型的预测结果，形状是 [batch_size, 10]，每行是一个样本的10个类别的预测分数
            test_loss += loss_fn(pred, y).item()  # 累加损失
            correct += (pred.argmax(1) == y).type(torch.float).sum().item()  # 累加正确的预测数量
            # pred.argmax(1) 是取每行最大值的索引，也就是预测的类别，和y比较是否相等，得到一个布尔张量，再转换成float类型，最后求和得到正确的数量

    test_loss /= num_batches  # 平均损失：总损失除以batch数量
    accuracy = correct / size  # 准确率：正确的数量除以总样本数量
    print(f"测试结果：测试集平均损失：{test_loss:.4f}，准确率：{accuracy:.4f}")
    return accuracy


# ----------------------- 6. 运行训练和测试 ----------------------
print("开始训练和测试模型...")
epochs = 10

for epoch in range(epochs):
    print(f"Epoch {epoch + 1}/{epochs}\n------------------------------")
    train(train_dataloader, model, loss_fn, optimizer)  # 训练一个epoch：数据加载器、模型、损失函数、优化器
    test(test_dataloader, model, loss_fn)                # 测试模型看看效果：数据加载器、模型、损失函数

print("训练和测试完成！")

# 保存模型
torch.save(model.state_dict(), "model.pth")     # model.state_dict() 是模型的参数字典，保存到 model.pth 文件中
print("模型已保存到 model.pth")

6.3 运行结果

运行这段代码，你会看到类似下面的输出：

正在加载数据...
使用设备：cuda
Model(
  (flatten): Flatten(start_dim=1, end_dim=-1)
  (hidden1): Linear(in_features=784, out_features=128, bias=True)
  (hidden2): Linear(in_features=128, out_features=256, bias=True)
  (out): Linear(in_features=256, out_features=10, bias=True)
)
开始训练和测试模型...
Epoch 1/10
------------------------------
训练了 100 个batch，当前损失：0.5379
训练了 200 个batch，当前损失：0.3962
训练了 300 个batch，当前损失：0.2342
训练了 400 个batch，当前损失：0.3782
训练了 500 个batch，当前损失：0.0717
训练了 600 个batch，当前损失：0.3981
训练了 700 个batch，当前损失：0.2678
训练了 800 个batch，当前损失：0.2566
训练了 900 个batch，当前损失：0.4510
训练了 1000 个batch，当前损失：0.2997
训练了 1100 个batch，当前损失：0.2082
训练了 1200 个batch，当前损失：0.2453
训练了 1300 个batch，当前损失：0.0343
训练了 1400 个batch，当前损失：0.5646
训练了 1500 个batch，当前损失：0.1000
训练了 1600 个batch，当前损失：0.5390
训练了 1700 个batch，当前损失：0.4575
训练了 1800 个batch，当前损失：0.2549
正在测试模型...
测试集样本数量：10000，batch数量：313
测试结果：测试集平均损失：0.2858，准确率：0.9220

...

Epoch 10/10
------------------------------
训练了 100 个batch，当前损失：0.2720
训练了 200 个batch，当前损失：0.0058
训练了 300 个batch，当前损失：0.0881
训练了 400 个batch，当前损失：0.0008
训练了 500 个batch，当前损失：0.0016
训练了 600 个batch，当前损失：0.0406
训练了 700 个batch，当前损失：0.0056
训练了 800 个batch，当前损失：0.0145
训练了 900 个batch，当前损失：0.3302
训练了 1000 个batch，当前损失：0.1829
训练了 1100 个batch，当前损失：0.0033
训练了 1200 个batch，当前损失：0.0012
训练了 1300 个batch，当前损失：0.1873
训练了 1400 个batch，当前损失：0.1014
训练了 1500 个batch，当前损失：0.0060
训练了 1600 个batch，当前损失：0.2971
训练了 1700 个batch，当前损失：0.1371
训练了 1800 个batch，当前损失：0.2050
正在测试模型...
测试集样本数量：10000，batch数量：313
测试结果：测试集平均损失：0.1954，准确率：0.9640
训练和测试完成！
模型已保存到 model.pth

你看！只用了 10 轮训练，我们的模型就达到了 96.4% 的准确率！也就是说，它能正确识别 96.4% 的手写数字！

每个人的结果可能会有一点差异，因为模型的初始化和数据的加载是随机的，但大体上应该都能达到 95% 以上的准确率，这已经非常不错了！你可以继续训练更多的轮数，或者调整模型结构和超参数，看看能不能达到更高的准确率！

第七章：常见问题与避坑指南

1. CUDA out of memory：显存不足

减小 batch_size，比如从 32 改成 16
测试的时候用 with torch.no_grad()，关掉梯度计算
用 torch.cuda.empty_cache() 清理没用的缓存

2. 训练不收敛，损失不动

检查学习率是不是太大或者太小
检查有没有忘记梯度清零 optimizer.zero_grad()
检查数据预处理有没有问题，比如有没有归一化

3. Windows 下 DataLoader 卡死

把你的主程序代码放在 if __name__ == '__main__': 里面，因为 Windows 的多进程需要这个

4. 模型保存和加载

# 保存
torch.save(model.state_dict(), "model.pth")

# 加载
model = NeuralNetwork()
model.load_state_dict(torch.load("model.pth"))
model.to(device)

第八章：接下来你可以学什么？

恭喜你！你已经完成了 PyTorch 的入门，学会了：

环境搭建
张量操作
自动微分
数据加载
模型构建
训练一个完整的分类项目

接下来你可以继续深入学习：

卷积神经网络（CNN）：用来处理图像，能达到更高的准确率
循环神经网络（RNN/LSTM）：用来处理序列数据，比如文本、语音
迁移学习：用预训练的模型，快速做自己的任务
目标检测、图像分割：更复杂的计算机视觉任务
Transformer：现在最火的大模型的基础架构

PyTorch 的生态非常丰富，掌握了这份指南里的基础，后面的学习应该都会非常顺利！

Python on Snow

MCP 完全指南：原理、远程调用链路与自建服务接入 Agent

MCP 完全指南：原理、远程调用链路与自建服务接入 Agent

一、为什么需要 MCP

二、先认清四个角色

三、MCP 暴露什么

Tool 和普通 REST API 有什么不同

四、远程 MCP 的完整调用链路

1. 配置与发现

2. 工具进入模型上下文

3. 模型选择，Host 决策

4. HTTP 调用与业务执行

5. 结果回到模型

五、两种远程连接模式

六、从零开发一个远程 MCP Server

1. 初始化项目

2. 编写 server.py

3. 本地测试

4. 容器化与部署

七、让 Agent 真正使用你的 MCP

接入 Codex

接入 OpenAI Agents SDK

验证 Agent 是否会用

八、工具设计决定 Agent 上限

好工具的形状

MCP 不适合什么

九、安全：把模型、Server 和返回内容都当作不可信边界

十、可观测性与排错

十一、生产检查清单

结语

参考资料

Flask 实战教程：面向 Python 开发者的轻量 Web 后端入门

Flask 实战教程：面向 Python 开发者的轻量 Web 后端入门

一、Flask 是什么

二、环境准备

三、第一个 Flask 应用

四、路由、请求与响应

五、模板：用 Jinja2 返回 HTML

六、表单、Session 与安全边界

七、项目变大后：应用工厂与 Blueprint

八、数据库与扩展怎么选

九、测试：用 test client 固定接口行为

十、错误处理与状态码

十一、从开发到生产部署

十二、Flask 常见坑

十三、Flask 与 FastAPI 怎么选

十四、学习路线

参考资料

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

FastAPI 实战教程：面向 Python 开发者的现代 API 入门

一、FastAPI 解决的核心问题

二、环境准备

三、第一个可运行 API

四、类型提示如何变成接口契约

五、Pydantic：把边界数据变可信

六、依赖注入：把横切逻辑拿出接口函数

七、项目变大后怎么拆

八、async def 不等于自动更快

九、错误处理与状态码

十、测试：用接口行为保护重构

十一、部署前需要想清楚的事

十二、常见坑

十三、学习路线

参考资料

从峡湾到极光：2015—2024 年北欧五国入境旅游可视分析

从峡湾到极光：2015—2024 年北欧五国入境旅游可视分析

发布方式

PyTorch

第一章：环境搭建：保姆级安装教程

1.1 为什么要使用虚拟环境？

1.2 创建并激活虚拟环境

1.3 安装 PyTorch：CPU 版本（通用）

Pip 安装（简单直接）

Conda 安装（更稳定）

1.4 安装 PyTorch：GPU 版本（NVIDIA 显卡专属）

第一步：检查你的显卡支持的 CUDA 版本

第二步：根据你的 CUDA 版本安装 PyTorch

Pip 安装

1.5 Mac 用户专属：M 芯片的 GPU 加速

1.6 验证安装是否成功

2. 编写 `server.py`

八、`async def` 不等于自动更快