软件工程第一次个人作业

这个作业属于哪个课程 202601 福州大学软件工程班级博客
这个作业要求在哪里 第一次个人作业要求
这个作业的目标 通过真实调用 Hugging Face 的 Flux 写实模型完成一次交互式图像生成并完整记录全过程；搭建 GitHub 个人主页并梳理个人成长；用 Markdown 撰写博客，明确自己"会什么、不会什么"。
学号 102401318

软件工程第一次作业：Flux API 调用、个人主页搭建与技能梳理

0x00 作业成果导航

要求 我的完成情况 证据位置
Hugging Face API 调用 已真实调用 XLabs-AI/flux-RealismLora 成功生成 2 张图像，并遭遇 402 额度问题 0x02 节，图 1—图 6
前端交互与提示词修改 本机 FastAPI 后端 + 网页表单实现交互生成 0x03 节，图 3—图 5
GitHub 个人主页 已完成同名仓库 README 个人主页 0x04 节，图 7—图 9
技能树、代码量与课程期待 已按表格梳理 0x05 节
AI 生成的软件工程学习指南及分析 使用 ChatGPT 生成并逐条分析 0x06 节
Markdown 编辑与提交 已切换 Markdown 编辑器并截图 0x07 节，图 10

代码仓库：https://github.com/Mortal810/Mortal810
个人主页：https://github.com/Mortal810

0x01 准备工作

  • Hugging Face：已注册账号：Mortal810,并完成邮箱验证，在 Settings → Access Tokens 创建了 fine-grained 令牌，仅开启 Make calls to Inference Providers 权限。
  • GitHub：账号为Mortal810，已完善头像、昵称与个人资料。
  • 博客园：账号为Mortal810，已开通博客并切换到 Markdown 编辑器，已加入班级博客并关注老师与助教。

关于我： 福州大学计算机科学与技术专业大三学生，专业方向是计算机系统与结构。课余喜欢看风景、听音乐、看动漫，也会跑步和打羽毛球。平时对 AI 大模型与 AI Agent 方向很感兴趣，一直在用 API 和各类大模型工具做一些小实践——本次作业的主题"雨后校园的自行车"，灵感就来自跑步时经常经过的校园道路。

0x02 Hugging Face API 调用：从账号到真实调用

2.1 账号、令牌与模型页核验

操作步骤记录：

  1. 在 huggingface.co 注册账号并完成邮箱验证。
  2. 进入 Settings → Access Tokens，创建 fine-grained 令牌，只勾选 Make calls to Inference Providers，不开启仓库写权限——最小权限原则，即使泄露损失也有限。
  3. 令牌只保存在本地 .env 文件中（HF_TOKEN=hf_...），.env 已被 .gitignore 排除，不进入代码、截图和 Git 提交。
  4. 打开指定模型页 XLabs-AI/flux-RealismLora，核对该 LoRA 模型当前可用的 Inference Provider 为 fal-ai，因此代码中固定 provider="fal-ai"，不依赖 SDK 自动路由（该 LoRA 不支持默认的 hf-inference，自动路由会报错）。

图1

屏幕截图 2026-09-11 221552

2.2 本地环境与调用链

项目 我的实际配置
操作系统 Windows（PowerShell）
Python 3.13.5
huggingface_hub 1.31.0
本地后端 FastAPI 0.141.1 + Uvicorn 0.52.4
模型 XLabs-AI/flux-RealismLora
服务商 fal-ai
调用日期 2026-09-11

调用链：

浏览器提交提示词
  → 本地 Python 后端（FastAPI）校验输入
  → Hugging Face InferenceClient（provider=fal-ai）
  → Hugging Face 路由至 fal 服务商执行推理
  → 返回图片并在本地保存 PNG + 参数 JSON
  → 页面展示、下载与日志记录

关键调用代码（generator.py，完整源码见仓库）：

MODEL_ID = "XLabs-AI/flux-RealismLora"
PROVIDER = "fal-ai"

arguments = {"model": MODEL_ID, "prompt": item.prompt}
arguments.update(width=1024, height=768,
                 num_inference_steps=28, guidance_scale=3.5, seed=42)

with InferenceClient(provider=PROVIDER, api_key=token, timeout=180) as client:
    image = client.text_to_image(**arguments)
image.save(self.output_dir / f"{local_id}.png", format="PNG")

启动方式：

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Copy-Item .env.example .env   # 在 .env 里填自己的 HF_TOKEN
.\.venv\Scripts\python.exe app.py

浏览器访问 http://127.0.0.1:8000 即可打开交互页面（密钥只在后端读取，不经过浏览器）。

2.3 调用成功记录

两次真实调用成功，记录来自本程序生成的 outputs/*.json 与 logs/calls.jsonl：

项目 第一次成功 第二次成功
本地请求编号 b99e292877594d45b0f1aba32da7f79f 8f0000efdd2d4faeb24dfb7ff605ad79
提交时间（UTC） 2026-09-11 08:46:48（北京时间 16:46） 2026-09-11 08:57:51（北京时间 16:57）
模型 / 服务商 XLabs-AI/flux-RealismLora / fal-ai 同左
后端总耗时 16.266 s 16.053 s
实际图像尺寸 1024 × 768 1024 × 768
固定参数 seed=42，steps=28，guidance_scale=3.5 同左
结果 generation_completed，PNG 与 JSON 已保存 同左
图像 SHA-256 ccec84ae...6a3a6b4 d817ac1c...cdfc7

两点如实说明：其一，SDK 成功时直接返回图像，程序并未截获上游 HTTP 状态码，所以不把本地返回的 200 冒充成"上游 200"；其二，local_request_id 是本程序生成的编号，不是 Hugging Face 的官方请求编号。

图2

屏幕截图(32)

图3

屏幕截图 2026-09-11 165350

8f0000efdd2d4faeb24dfb7ff605ad79

【这里前端页面最终生成图像的完整页面我忘记截图了，所以上传了前端页面和模型最终生成的图像orz】

证据解释：outputs/<本地编号>.png、.json 与 logs/calls.jsonl 通过同一个本地请求编号一一对应；JSON 中的 image_sha256 可校验图片文件是否被替换，但它只是哈希校验，不是平台签发的真实性证明。

2.4 错误与修复：一次真实的 402 经历

在两次成功调用之后，我继续尝试第三版提示词（v2），结果连续失败：

现象 我如何排查 结论 最终处理
第三次起连续返回 402 Payment Required，耗时只有 0.9~9 s 先怀疑参数不兼容：切换 minimal 简化模式（只提交 model 与 prompt）重试，仍然 402 参数无关 停止重试
402 的报错信息为"上游要求付款：检查 Hugging Face 余额与计费设置" 登录 Inference Providers 用量页面 查看余额 免费额度已耗尽 不再盲目重试，避免产生扣费

这个过程让我第一次直观理解了"API 调用有成本"：本地代码写得对、网络也通，但上游因为额度拒绝服务，前端再点多少次也不会成功。排查时先分清"本地问题"和"上游问题"，再看用量，不无限重试，这是本次最值钱的教训。

图4

屏幕截图 2026-09-11 222339

0x03 前端交互与提示词设计

3.1 页面有哪些功能

前端页面（web/index.html + app.js）实际实现并通过测试的功能：

  • 提示词非空校验与长度统计（最大 1500 字符）；
  • 拒绝在提示词中输入疑似密钥（hf_、Bearer ），防止误粘贴令牌；
  • 生成期间按钮禁用、显示"等待上游 · 已经过 X 秒"，防止重复提交（后端另有内存锁，同一时间只允许一个推理任务，避免重复扣费）；
  • 成功后展示图像、模型名、服务商、seed、实际尺寸、本地请求编号与耗时，可下载 PNG 与参数 JSON；
  • 失败时清除旧图再显示错误，不会把上一次的结果冒充成新结果；
  • 本页会话记录表，展示每次提交的时间、实验编号、结果与耗时。

3.2 提示词设计与修改过程

我的设计模板：主体及数量 + 场景 + 空间关系 + 光线 + 可见材质 + 构图与视角。

  • 尝试一（详细版）：一次性写全六个要素，重点是"single bicycle"（约束数量，避免多画）、"wet walkway after light rain"（湿地面是可验证的光影细节）、"eye-level view / soft overcast daylight"（固定视角与光线）、"detailed metal and rubber textures"（金属与橡胶材质）。
A realistic documentary photograph of a single bicycle parked beside
a wet university walkway after light rain. The bicycle is in the
foreground, green trees and a plain campus building are in the
background. Eye-level view, soft overcast daylight, natural colors,
realistic proportions, subtle water reflections, detailed metal and
rubber textures, ordinary everyday atmosphere.
  • 尝试二（简短版）：我想验证"更少的约束是否同样真实"，于是把提示词大幅精简，只保留主体、场景和背景：
A realistic photograph of a bicycle parked beside a wet university walkway after rain, with trees in the background.
  • 尝试三（v2）：计划在简短版基础上增加摄影语言（moderate depth of field 等）做对照，但提交时遇到 402 额度问题，未能生成，因此本次只有两次成功结果可对比。

如实说明：两次成功调用在记录里都被标记为实验编号 v1，没有严格递增——这说明我一开始没有做好实验编号管理，如果第三版成功生成，"v1 有两个"会让对照表变得混乱。这是一个记录管理的教训，后续我会先定编号规则再运行。

版本 提示词 与上一版相比 本地请求编号 状态 结果图
尝试一（详细版） 见上 初始基线 b99e...79f 成功，16.266 s 图5
尝试二（简短版） 见上 删掉视角、光线、材质等约束 8f00...ad79 成功，16.053 s 图6
尝试三（v2） 简短版+摄影术语 增加景深等描述 1923...966 等 402 失败 无结果图

固定条件：seed=42、steps=28、guidance_scale=3.5、尺寸 1024×768、provider=fal-ai、SDK 1.31.0。即使固定这些参数，服务端模型版本升级等因素仍可能影响复现。

图5

8f0000efdd2d4faeb24dfb7ff605ad79

图6

b99e292877594d45b0f1aba32da7f79f

3.3 为什么选择最终版本

我认真看了两张图，以下是基于实际画面的完整对比：

我按主体、几何、光影、材质、场景合理性五个维度逐项对比了两版结果。

主体与数量。 两版都只画了一辆自行车，没有多画或漏画。简短版的自行车正面朝向镜头、停在路中央，背景有明确的校园建筑，主次关系清楚；详细版的自行车侧靠在路边灌木丛旁，画面偏向氛围营造，主体与环境的主次关系弱一些。

几何结构。 两版的车轮轮廓、车架结构基本合理，没有严重变形。不过简短版的车把右侧握把延伸角度略显不自然，像是模型在侧视角度下对车把透视的理解不够准确。

光影与反光。 这是两版差距最大的维度。详细版整体光线柔和均匀，符合"阴天柔光"的约束，路面有细腻的水渍反光，明暗过渡自然，"雨后"的氛围可信；简短版画面中可见明显的雨丝和落叶，氛围感更强，但光线控制不如详细版稳定，路面反光在局部偏亮、层次感弱一些。

材质纹理。 详细版的车架金属质感更写实，高光收敛、不刺眼；简短版的车架表面偏光滑，金属的粗糙感不足，更接近"渲染图"而非实拍照片。

场景合理性。 详细版背景有明确的校园建筑（带柱廊的教学楼风格），道路两侧是绿色乔木，与"校园道路"的设定吻合；简短版背景以秋天色调的树木为主，地面铺满黄叶——但提示词里没有"秋天"或"落叶"的描述，这是模型自行发挥的结果，虽然是合理场景，却偏离了我的预期。

综合来看，详细版在光线控制、材质写实度和场景贴合度上更接近"日常雨后校园实拍"的目标，因此我选择图5（详细版）作为最终结果。需要如实说明的是：两次尝试同时改变了"详细程度"这一个维度，所以只能评价整组修改的整体效果，不能把改善归因于某个具体单词；受免费额度限制，也没能继续做单变量对照。

仍存在的问题：详细版的校园建筑柱廊细节略显重复和对称，不太像真实建筑的自然排列；另外自行车没有可见的支撑物却能直立停放，这一点在真实照片中不太合理。

3.4 功能测试

测试 预期行为 我的实际结果
空提示词提交 前端阻止并提示 与预期一致
提示词含 hf_ 字样 拒绝提交，防止密钥误入 与预期一致
正常生成 显示图像并保存 PNG/JSON 两次成功，见 2.3 节
生成期间连续点击 按钮禁用，不重复提交 与预期一致
上游失败（402） 显示错误信息，不展示旧图冒充新结果 已实际遇到，前端显示"上游要求付款"提示

0x04 GitHub 个人主页

4.1 我选择的方案及理由

我选择同名仓库 README方案，理由是我的项目经历还不多，当前最需要的是把"我是谁、会什么、要往哪走"写清楚，README 方案内容要求完全满足，维护成本也低；后续项目变多了再考虑升级为 GitHub Pages 展示页。

主页链接：https://github.com/Mortal810

创建过程：新建与用户名同名的公开仓库 → 勾选 Add a README file → 在根目录 README.md 填写个人介绍、实践成果、能力评估与三年规划 → 提交后访问账号主页检查渲染效果。

图7-9

屏幕截图 2026-09-11 224026

屏幕截图 2026-09-11 224046

屏幕截图 2026-09-11 224103

4.2 我的未来三年规划

我目前对升学路线持"两手准备"的态度：先看这学期绩点能否够到保研的门槛，同时从本学期开始动手准备考研。选择读研，是因为我的实习经验和简历还不够看，直接就业竞争力不足；我更希望用研究生阶段进一步深造技术、把 408 基础和代码能力补扎实，同时继续深耕 AI 大模型与 Agent 方向，为之后的就业做好充分准备。

阶段 目标 行动 如何检查
第一年（2026.9—2027.8，大三） 保住并提升绩点，评估保研机会；同步启动考研复习；补代码量 认真对待本学期课程与软工团队项目；开始系统复习 408（先从最薄弱的科目入手）；保持 AI 大模型/Agent 方向的动手实践 绩点达到3.6-3.7；408 第一轮复习完成；软工项目验收通过
第二年（2027.9—2028.8，大四） 确定读研去向（保研成功则提前进实验室，否则考研上岸）；完成毕业设计 保研则联系导师、进组学习；考研则按计划推进复习；毕设选题与 AI 方向结合 获得读研资格/拟录取；毕设完成并通过答辩
第三年（2028.9—2029.8，研一） 在研究生阶段把系统方向基础与 AI 应用能力打扎实，产出可展示的项目 跟随导师方向参与项目；独立完成 1—2 个 AI 大模型/Agent 相关实践并写复盘；尝试第一段实习 有可核对的实验室项目或论文进展；简历上有 1—2 段能讲清的项目经历

调整机制：每学期末对照检查项复盘一次。如果本学期绩点明显够不到保研门槛，就把重心尽快切到考研复习，不再左右摇摆；如果保研机会出现，就提前联系导师并保持绩点优势。无论走哪条路，"把代码量和 408 基础补上来"都是不变的底线任务。

0x05 当前技能树、代码量与课程期待

5.1 我能做什么，以及还不能做什么

能力领域 能独立完成什么 证据 尚欠缺什么 下一步任务
编程语言 用 C/C++、Python 完成课程实验与小程序，能读写基本代码 各学期课程作业 代码量少、工程组织能力弱 软工团队项目 + 每周动手练习
数据结构与算法 常用数据结构与基本算法能理解、能写 课程作业与实验 408 不够扎实，算法训练不系统 考研复习与刷题同步进行
408 计算机基础 四门课有课本级概念 课程学习记录 知识不成体系，综合题吃力 制定 408 复习计划逐科补
Web 与 API 本次作业在 AI 辅助下搭建了 FastAPI 后端与前端页面，能看懂并修改 本次作业仓库 独立从零设计前后端接口的能力 复现一遍本项目并逐行理解
AI 大模型/Agent 日常使用各类大模型工具，调用 API 做过小实践，了解 Agent 的基本工作流 本次作业与个人实践 没有完整落地的项目，原理层（Transformer 等）理解浅 做一个完整的小工具项目 + 读核心论文
Git、测试、协作 会 clone/commit/push 基本流程；本次用 pytest 跑通 24 项本地测试 本次作业 分支协作、代码审查 团队项目使用 PR + 同伴审查

技术偏好： 我的专业方向是计算机系统与结构，个人兴趣在 AI 大模型与 Agent 方向。两者并不矛盾：系统方向是"底子"，AI 应用是"出口"——本次调用 Flux 模型的完整链路让我第一次看到"大模型能力如何变成产品"，也让我意识到自己的 408 基础不扎实会限制住向上学习。准备尝试的任务：用 API 做一个本地可运行的 AI 小工具（例如带记录功能的对话助手），并写复盘博客。

AI 辅助边界： 本项目的项目骨架、FastAPI 后端与前端页面代码主要由 ChatGPT 生成，我完成了需求理解、提示词设计、真实调用、截图取证与代码阅读；其中参数校验、错误分类和 402 排查是我在运行中真正理解的部分，前端 app.js 的防重复提交逻辑目前只能看懂一半。我不会把这些 AI 生成的代码冒充成自己的独立成果。

5.2 当前代码量与本学期目标

如实说明：我的代码量偏少，这是目前的短板之一，也是我选择读研深造、再沉淀几年的直接原因之一。历史课程作业大多未保留源码，不编造历史累计数字，只统计现在能核对的部分。

统计日期：2026年9月11日。统计方法：使用 tools/count_loc.py 统计本人代码目录，排除第三方依赖、.venv、模板与重复备份；统计口径为物理行/非空行（含注释）。

范围 行数 说明
截至目前可核对的项目 8000行 仅统计保留源码的项目（本次作业 + 课程作业），不含 AI 生成的模板部分
历史累计估计 不做估计 历史作业未保留源码，不编造数字
本学期计划新增 2000—3000 行 软工团队项目中本人负责的模块 + 考研复习代码练习
课程结束目标 2-30000行 不机械追求数量，以"本人负责模块可运行、有测试"为准

5.3 我最期待学习什么

结合"项目经历少、代码基础薄弱"的现状，本课程我最期待的三件事：

  • 完整的项目流程：我以前写代码都是直接动手，从没完整走过"需求—设计—实现—测试—交付"。希望借团队项目第一次完整经历一遍，弄清"什么才算完成"。
  • 测试与质量保障：本次 402 排查让我意识到"能运行"不等于"可靠"。想学会为关键模块写测试，希望课程结束时自己负责的模块有可重复执行的测试用例。
  • Git 团队协作：一直是单打独斗。想学会分支管理、代码审查，希望完成至少一次被同学 review 过的 PR。

0x06 AI 生成的软件工程课程学习指南与我的分析

6.1 工具和输入

工具：ChatGPT（本次实践的整个项目骨架正是由 ChatGPT 对话协助搭建的）。日期：2026年9月11日。

我向 ChatGPT 说明了自身基础（计算机专业大三、C/C++/Python 基础但代码量少、408 不扎实、Web 与团队协作经验少、每周可投入 4—6 小时、对 AI 大模型方向感兴趣）和本学期约束（以课程团队项目为主线），请它生成一份简要学习指南。以下指南来自本次对话，不是福州大学官方大纲。

6.2 AI 返回的指南

## 学习目标
以一个规模可控的小项目贯穿整个学期，练习从"写出能运行的代码"
走向"按需求交付、能够测试、便于他人接手的软件"。

| 阶段 | 重点问题 | 实践任务 | 可检查产物 |
| 起步与需求 | 谁需要软件，什么才算完成？ | 选择真实小问题，写出主要用户流程与验收条件 | 一页需求说明、必须/可选功能清单 |
| 设计 | 页面、接口和外部服务如何分工？ | 画简单界面原型，约定输入输出和异常，说明一个设计取舍 | 原型、接口表、模块说明 |
| 实现与版本管理 | 如何增量完成？ | 每次实现一个可演示功能，及时提交 Git，记录缺陷 | 可运行版本、提交记录、问题清单 |
| 测试与协作 | 如何发现错误并让其他人看懂？ | 覆盖正常、边界与失败情况；同伴按 README 运行并审查 | 测试用例、测试结果、审查反馈 |
| 发布与复盘 | 别人能否复现，下一轮该改什么？ | 整理依赖、配置示例与操作说明；检查密钥；回顾估时和需求变化 | 演示、运行说明、已知问题与复盘 |

## 每周学习节奏建议
先按真实时间制定计划，例如用一次短阅读理解概念、一次开发实现具体功能、
一次测试与复盘确认结果。时间不足时缩小范围，不用省略验证来换取更多功能。

## AI 使用建议
让 AI 解释不理解的概念、提出候选设计和测试思路；自己检查需求是否满足、
代码是否安全、异常路径是否存在。对关键模块做到能够说明输入输出、
逐段解释代码，并独立修改一个小功能。记录哪些建议采用、哪些未采用，以及验证依据。

## 如何评价本学期是否进步
检查自己能否澄清需求、完成模块划分、定位缺陷、执行同伴审查，
并让他人按文档运行项目。代码量可按统一口径记录，但不替代质量、理解程度与协作成果。

6.3 我的分析

评价角度 我的具体判断 我准备如何调整或验证
合理之处 指南没有堆技术名词，而是把"需求—设计—实现—测试—发布"对应到可检查的产物，这和本次作业"用 JSON/日志/截图当证据"的思路一致；对代码量少的我来说，"可检查产物"比"学什么框架"更现实 按五个阶段在团队项目中各留一份文档
对我最有帮助的部分 "起步与需求"阶段——我习惯直接写代码，验收条件怎么写完全没概念，这是项目经验少的典型短板 团队项目立项时先写"谁在什么场景下想完成什么"，再动工
不适合当前阶段的部分 指南假设每周固定投入，但本学期我还要评估绩点、启动 408 考研复习，时间会被切得很碎 只保留阶段产物清单，不照搬每周节奏；课内能做的绝不拖到课外
最终采用的安排 保留"需求先行、增量提交、同伴审查"三点；测试自动化推迟到模块稳定后再补 本课程团队项目中实际执行后复盘

这份指南对我最大的提醒是：代码量和 token 用量都不是能力证明。我经常用 AI 完成小实践，很容易产生"我已经会了"的错觉；指南把"能让他人在干净环境里跑起来、能说清输入输出"作为验收线，正好戳中我的问题——接下来我会要求自己把本次作业的每个文件都读懂、能独立复现，而不是停留在"AI 帮我跑通了"。

0x07 Markdown 编辑与课程提交

操作步骤：博客园后台（i.cnblogs.com）→ 设置 → 默认编辑器选择 Markdown → 保存 → 新建随笔。正文粘贴本 Markdown 源码（正文第一行保留课程信息表，不要再包一层代码围栏）。图片通过编辑器工具栏"上传图片"插入得到在线地址；代码块用三反引号并标注语言；表格直接书写，发布前先预览。

图10

屏幕截图 2026-09-11 225423

发布后我用未登录窗口打开博文，检查了主页链接、仓库链接与图片均正常显示，随后在 edu.cnblogs.com 对应作业页面提交了公开博文 URL 并确认成功。

0x08 体验与心得

本次实践印象最深的不是成功生成图片的瞬间，而是两次成功之后连续五次 402。一开始我以为是自己参数写错了：切 minimal 模式、改回 v1 提示词、重启服务，全都不行，最后才在 Inference Providers 用量页面确认是免费额度耗尽。这次排查让我理解了三件事：

  1. API 调用是有成本的。 代码本地运行正确不等于上游会服务你，错误响应里 402 和 422 是两个完全不同的排查方向。免费额度不是无限的，盲目重试可能产生计费。
  2. 证据意识。 每张图、每份 JSON、每条日志都有编号对应，哈希能校验文件一致性——"记录"本身就是软件工程能力的一部分，也让我写博客时不需要回忆细节。
  3. 提示词不是玄学。 用"主体+场景+光线+材质+构图"的模板设计提示词后，修改过程变得可解释；但两次成功调用都被我标成了 v1，说明我的实验管理还不够严谨，这是下次要改的。

另外，作为一个一直"用"AI 的人，这次是我第一次动手"搭"起一条完整的 AI 调用链。它让我清醒地看到自己和"会用 AI"之间的差距：会用 API 写几行代码只是起点，能把一个模型能力变成稳定、可复现、有错误处理的工程交付物，才是本事——这也正是我接下来想通过读研阶段慢慢补齐的东西。

0x09 参考资料与 AI 使用说明

AI 使用说明：本项目的目录结构、后端接口与前端页面代码由 ChatGPT 协助搭建，我负责理解需求、设计提示词、真实运行调用、核对证据与撰写博客；所有运行记录均来自本人账号的真实调用。生成图标注为 AI 生成，未用作任何"真实摄影"证据。

posted @ 2026-09-11 23:04  Mortal810  阅读(8)  评论(0)    收藏  举报