后端架构

相关源文件

• backend/.pre-commit-config.yaml
• backend/config.py
• backend/llm.py
• backend/main.py
• backend/poetry.lock
• backend/pyproject.toml
• backend/routes/generate_code.py
• backend/routes/home.py
• backend/start.py
• frontend/src/constants.ts
• frontend/src/generateCode.ts

本文档全面概述了 screenshot-to-code 应用程序的后端架构。它涵盖了核心组件、API 端点、LLM 集成以及系统如何处理用户输入以生成代码。有关前端架构的信息，请参阅前端架构。

核心架构概述

screenshot-to-code 的后端使用 FastAPI 构建，这是一个现代、高性能的 Python Web 框架。它充当 React 前端和用于代码生成的各种 AI 模型之间的桥梁。

架构图

来源：backend/main.py1-26 backend/routes/generate_code.py1-39

后端组件

后端由几个关键组件组成，它们协同工作以提供代码生成功能

1. FastAPI 应用：处理 HTTP 和 WebSocket 请求的主应用程序
2. API 路由器：用于不同功能的模块化路由
3. LLM 服务：用于 AI 模型交互的抽象层
4. 图像生成：用于从代码占位符生成图像的服务
5. WebSocket 通信：管理与前端的实时通信

FastAPI 应用程序结构

来源：backend/main.py7-26

API 端点

后端暴露了几个用于不同功能的端点

端点	类型	描述
/generate-code	WebSocket	用于从屏幕截图生成代码的主要端点
/screenshot	HTTP	处理屏幕截图上传
/	HTTP	基本状态端点
/evals/*	HTTP	评估工具的端点

/generate-code WebSocket 端点是后端的核心，负责整个代码生成过程。

来源：backend/main.py22-26 backend/routes/generate_code.py159-438 backend/routes/home.py1-13

WebSocket 通信

后端使用 WebSockets 实时将代码生成结果流式传输回前端。这提供了响应式用户体验，因为代码是增量生成的。

WebSocket 协议

WebSocket 通信遵循结构化协议，具有不同的消息类型

消息类型	目的
chunk	来自 LLM 的增量代码片段
status	前端的状态更新
setCode	后处理完成后的完整代码
error	错误消息

每条消息都包含一个 variantIndex，它允许同时生成和跟踪多个代码变体。

来源：backend/routes/generate_code.py159-438 frontend/src/generateCode.ts1-74

参数处理

当客户端连接到 WebSocket 时，它会发送一个带有控制代码生成过程的参数的 JSON 对象

后端使用 extract_params 函数提取和验证这些参数，确保在继续代码生成之前所需参数存在且有效。

来源：backend/routes/generate_code.py76-141

LLM 集成

后端通过一个处理它们之间差异的抽象层，与多个 AI 模型集成以进行代码生成。

LLM 服务架构

LLM 抽象包括

1. 模型枚举：在 Llm 枚举中定义了可用的 AI 模型
2. 流式函数：用于从不同 AI 模型流式传输响应的函数
3. 错误处理：针对不同 API 错误的强大错误处理
4. 完成类型：标准化的响应格式

来源：backend/llm.py1-309

模型选择逻辑

后端根据可用的 API 密钥和具体的生成任务来选择使用哪个 LLM

来源：backend/routes/generate_code.py254-285

代码生成过程

代码生成过程由 WebSocket 端点处理，涉及多个步骤

代码生成流程

该系统支持使用不同的模型并行生成多个代码变体，为用户提供选项，并允许比较不同 AI 模型的结果。

来源：backend/routes/generate_code.py159-438

图像生成

后端可以使用 OpenAI 的 DALL-E 或 Replicate 的 Flux 模型，为生成的代码中的占位符元素生成图像。

perform_image_generation 函数处理生成的 HTML 以查找图像占位符，并用生成的图像替换它们。

来源：backend/routes/generate_code.py42-73

错误处理

后端包含对各种情况的强大错误处理

1. 身份验证错误：处理无效的 API 密钥
2. 速率限制错误：处理 API 速率限制
3. 找不到模型错误：处理模型不可用的情况
4. 生成失败：处理所有或部分生成失败的情况

错误消息会通过 WebSocket 连接以适当的错误代码发送回客户端。

来源：backend/routes/generate_code.py373-406 frontend/src/constants.ts1-4

配置

后端通过环境变量进行配置，这些变量可以设置在 .env 文件中，或直接在环境中设置

配置	目的
OPENAI_API_KEY	OpenAI 的 API 密钥
ANTHROPIC_API_KEY	Anthropic 的 API 密钥
GEMINI_API_KEY	Google Gemini 的 API 密钥
REPLICATE_API_KEY	Replicate 的 API 密钥（图像生成）
OPENAI_BASE_URL	OpenAI API 的基础 URL（用于自定义端点）
NUM_VARIANTS	要生成的代码变体数量
MOCK	是否模拟 AI 响应（用于测试）
IS_DEBUG_ENABLED	是否启用调试日志记录
IS_PROD	是否在生产环境中运行

后端可以在开发或生产环境中运行，并相应地启用或禁用某些功能。

来源：backend/config.py1-26 backend/pyproject.toml1-33

开发与部署

后端使用 Poetry 进行依赖管理，并可以使用 Uvicorn 运行

后端默认配置为监听端口 7001，并支持开发环境的热重载。

来源：backend/start.py1-5 backend/pyproject.toml1-33

结论

screenshot-to-code 的后端架构提供了一个灵活且可扩展的系统，用于使用各种 AI 模型将屏幕截图转换为代码。其核心优势包括：

1. 模型抽象：易于与不同的 AI 模型集成
2. 实时通信：基于 WebSocket 的流式传输，用于响应式用户体验
3. 并行处理：生成多个代码变体
4. 图像生成：为占位符自动生成图像
5. 错误处理：针对各种失败情况的强大错误处理

模块化设计允许轻松扩展新的 AI 模型和功能，同时与现有前端保持兼容。