软件工程第一次个人作业：认识自己，从一次 API 实践开始

这个作业属于哪个课程	H202601软件工程与软件工程实践
这个作业要求在哪里	第一次个人作业
这个作业的目标	建立个人技术展示与学习记录平台；通过 Hugging Face API 和前端页面完成写实图像生成实践；认识自己的能力基础与不足，制定软件工程课程学习目标和未来三年规划。
学号	102402129

软件工程第一次个人作业：认识自己，从一次 API 实践开始

一、Hugging Face API 与写实图像生成实践

1.1 任务理解与实现方案

这一部分的目标，是用代码调用指定模型，并让用户能够在网页中输入提示词、点击按钮获得图像，同时保存调用过程，便于核对和复盘。

我使用 Python 编写程序，通过 huggingface_hub.InferenceClient 调用 XLabs-AI/flux-RealismLora，推理服务提供方设置为 fal-ai；前端采用 Gradio，提供提示词输入框、随机种子输入框、生成按钮、图像展示区和调用记录区。

指定仓库提供的是面向 FLUX.1-dev 的写实 LoRA。此次实践通过云端推理服务完成生成，没有在本机训练模型或部署完整模型权重。模型背景见 Hugging Face 模型说明。

程序的基本流程是：

用户输入提示词和 Seed
        ↓
Gradio 将输入传给 Python 回调函数
        ↓
InferenceClient 调用指定模型的云端推理服务
        ↓
获得图片并保存 PNG，同时记录调用信息到 JSON
        ↓
网页展示图片与调用记录

1.2 核心代码与前端连接

完整实现保存在 app.py 中，现有仓库可从 vic155/vic155 进入查看。

下面是程序中初始化客户端与发起图像生成的关键代码节选：

TOKEN = os.environ.get("HF_TOKEN")
if not TOKEN:
    raise RuntimeError("请先在终端设置 HF_TOKEN 环境变量")

client = InferenceClient(
    provider="fal-ai",
    api_key=TOKEN,
    timeout=180,
)

image = client.text_to_image(
    prompt,
    model="XLabs-AI/flux-RealismLora",
    seed=seed,
    width=1024,
    height=1024,
)

其中，prompt 描述要生成的画面，seed 用来控制生成的随机性，宽高均设置为 1024。InferenceClient 的参数与调用方式可参考 官方接口文档。

前端部分复用同一个生成函数，主要结构如下，完整的控件标签和配置见源码：

def web_generate(prompt, seed):
    try:
        return generate(prompt, seed)
    except ValueError as exc:
        raise gr.Error(str(exc))

demo = gr.Interface(
    fn=web_generate,
    inputs=[
        gr.Textbox(label="提示词", value=DEFAULT_PROMPT, lines=6),
        gr.Number(label="随机种子 Seed", value=42, precision=0),
    ],
    outputs=[
        gr.Image(label="生成结果", type="pil"),
        gr.Textbox(label="本次调用记录", lines=16),
    ],
    title="FLUX 写实图像生成",
    submit_btn="生成",
    clear_btn="清空",
    flagging_mode="never",
)

demo.queue().launch(
    server_name="127.0.0.1",
    inbrowser=True,
    share=False,
)

generate() 会返回图片和日志文本，因此一次点击后，前端可以同时展示生成结果和调用信息。源代码还实现了提示词去除首尾空白、空输入检查、异常记录、耗时统计，以及错误信息中的 Token 替换处理。

1.3 API 调用成功记录

项目保留了三组 JSON 日志和对应图片。按照日志时间排序，结果如下：

时间（UTC+8）	场景	run_id	Seed	实际尺寸	程序记录状态	耗时
2026-09-06 22:33:15	雨天咖啡馆	76aa6de0f6e7	42	1024 × 1024	success	11.36 秒
2026-09-07 16:38:03	红色赛车	55a40b3f9488	42	1024 × 1024	success	23.72 秒
2026-09-07 16:40:02	再次生成雨天咖啡馆	b57fff352328	42	1024 × 1024	success	19.74 秒

以下是与最终前端截图对应的完整日志：

{
  "run_id": "b57fff352328",
  "time": "2026-09-07T16:40:02.646689+08:00",
  "model": "XLabs-AI/flux-RealismLora",
  "provider": "fal-ai",
  "prompt": "\"A documentary photograph of a small neighborhood cafe \"\n    \"on a rainy morning. A white ceramic coffee cup sits on \"\n    \"a worn wooden table beside a window. Soft overcast daylight, \"\n    \"subtle steam, small water droplets on the glass, \"\n    \"natural colors, realistic reflections, eye-level view.\"",
  "seed": 42,
  "requested_width": 1024,
  "requested_height": 1024,
  "status": "success",
  "image_file": "b57fff352328.png",
  "actual_size": [
    1024,
    1024
  ],
  "elapsed_seconds": 19.74
}

这里的 status: "success" 是程序在取得图片并保存成功后写入的本地状态，不是伪装成 HTTP 状态码的字段。原始日志没有保存 HTTP 响应头或服务端请求编号，因此我用模型名称、提示词、时间、运行编号、图片文件名和实际图像共同展示调用结果。

1.4 提示词的设计与实际调整

第一次：用日常静物建立基础场景

第一次生成使用了以下提示词：

A documentary photograph of a small neighborhood cafe on a rainy morning. A white ceramic coffee cup sits on a worn wooden table beside a window. Soft overcast daylight, subtle steam, small water droplets on the glass, natural colors, realistic reflections, eye-level view.

设计时围绕几个具体维度描述画面：

维度	提示词内容	希望达到的效果
主体与位置	白色陶瓷咖啡杯、旧木桌、窗边	让模型明确画面主体和空间关系
时间与天气	雨天早晨、阴天柔光	让整体光线与环境相互吻合
材质细节	玻璃水滴、木桌、真实反射	增加日常生活中的质感
氛围与风格	轻微蒸汽、自然色彩、纪实摄影	避免过度夸张的视觉效果
观察角度	eye-level view	尝试接近日常观察和拍摄视角

第一次生成结果如下：

杯子、木桌和窗户之间的关系比较明确，雨滴与背景虚化形成了接近日常照片的感觉。不过，写了 eye-level view 并不意味着画面一定严格遵守这一视角，实际结果仍能看见杯口内部。

第二次：扩展到更复杂的赛车场景

在完成静物场景后，我把内容改成红色赛车，并增加了车辆编号、驾驶员位置、轮胎接地、材质、拍摄角度和运动模糊等约束。实际提交的提示词如下：

A realistic documentary motorsport photograph of Charles Leclerc
driving a red Ferrari Formula 1 racing car, with the number 16
clearly visible on the nose, taking a corner on a real racing circuit.

Low trackside camera position, front three-quarter view, the entire
car visible in the frame. The driver sits naturally inside the
cockpit wearing a full-face racing helmet, framed by the halo.

Glossy red bodywork with natural reflections, exposed carbon fiber
details, realistic slick tires with subtle surface wear.
The tires maintain contact with the asphalt beside red and white curbs.

Natural afternoon daylight, believable shadows beneath the car,
realistic proportions and restrained colors. A professional panning
photograph: the car body remains sharp while the spinning wheels
and distant grandstands show subtle motion blur.
Authentic sports photojournalism, lightly processed camera image.

这一版生成了红色赛车、16 号号码、头盔和赛道，说明部分主体要求得到了表达。但结果更接近正面视角，没有完全实现提示词要求的“前侧方视角”；车身细小文字也不够可靠。虽然提示词提到了 Charles Leclerc，仅凭戴头盔的生成结果不能确认人物身份，也不能把这张 AI 图像当成真实赛事照片。

这次尝试让我看到：提示词可以表达细节要求，但不能保证所有要求都被准确执行。复杂场景需要对照结果逐项检查，不能只凭“像照片”就判断生成完全成功。

第三次：返回咖啡场景，完成前端展示

第三次又使用了咖啡馆场景，并保存了前端截图。核对日志时发现，这次输入还包含从 Python 多行字符串中复制出来的双引号、换行和缩进。也就是说，虽然场景内容与第一次相近，实际传给模型的文本并不完全相同。

这三次调用的 Seed 都是 42，但第一次和第三次不能被当作“只改变一个细节”的严格对照实验。现有材料也不足以证明多余引号导致了哪一种视觉变化。

1.5 最终页面与图像

我将第三次咖啡场景作为最终展示图。其主体关系比较清楚，杯子与桌面的接触、窗玻璃上的水滴、背景街景和光线具有较好的整体一致性。

上图为实际前端截图，可以看到提示词输入、Seed、生成按钮及生成结果。截图没有覆盖下方完整调用记录区，因此调用信息在前文以对应的原始 JSON 单独展示。

这张图也有值得继续改进的地方：蒸汽较明显，桌面的水迹较多，画面带有一定的布景感。如果目标是更普通、自然的生活照片，可以进一步约束蒸汽强度、桌面干湿状态和景深。

下面是根据结果提出的下一版提示词，尚未调用验证，不属于已有实验记录：

A candid documentary photograph inside a small neighborhood cafe on an overcast rainy morning. One plain white ceramic cup of coffee rests on a dry, slightly worn wooden table beside a closed window. Fine rain droplets are on the window glass. Barely visible steam rises from the coffee. Soft natural window light, physically plausible shadows and reflections, restrained colors, moderate depth of field, an ordinary unretouched camera photograph.

后续验证时，我会先去掉输入中的代码引号和缩进，再固定 Seed 和尺寸，每次只修改一类描述，例如先只改变蒸汽强度，以便更清楚地分析提示词与结果之间的关系。

1.6 遇到的问题与使用心得

环境变量必须在启动程序的终端中正确设置。 已有终端截图记录过“请先在终端设置 HF_TOKEN 环境变量”的异常。截图中第一次把 Token 本身写进了 Read-Host 的提示文字，而不是作为随后读取的输入。后面改成普通提示文字、隐藏输入 Token，再设置环境变量，程序才正常启动。这说明调用问题不一定来自模型，也可能发生在本地配置阶段。

运行成功与效果满意是两个不同的检查点。 三次调用都保存了图片，但赛车图没有完全遵守构图要求。完成 API 请求之后，还要检查生成图是否满足需求。

日志让问题更容易追踪。 同一个运行编号对应一张图片和一份 JSON，便于找回提示词、尺寸、时间及耗时。三次耗时为 11.36～23.72 秒，仅代表本次记录，不能据此推断服务的稳定性能。

前端交互让代码更容易使用。 用户不需要修改源代码就能切换提示词和 Seed，程序也能把结果直接反馈到页面。这让我开始理解“实现一个函数”和“提供一个可使用的小工具”之间的差别。

分享材料也需要检查。 原始终端截图中出现了明文 Token，因此本文不使用含密钥的截图；公开展示调用过程应使用无密钥的日志和截图。后续还应补充输入边界处理、依赖记录和更清晰的失败提示，让程序更容易维护。

二、GitHub 个人主页建设

我选择了“个人资料 README”方案，建立了与 GitHub ID 同名的公开仓库 vic155/vic155，在根目录维护 README.md，使个人介绍显示在主页中。该方案的要求可参考 GitHub 官方说明。

• 个人主页：https://github.com/vic155
• 个人资料与代码仓库：https://github.com/vic155/vic155

现有主页展示了学校与专业、Python/C/Pandas/MySQL 基础、考研目标以及羽毛球和跑步等兴趣。此次 FLUX 应用也是一项可以展示的实践成果：它把 API 调用、交互界面、文件保存和日志记录串联起来。

我计划继续在主页补充项目说明和阶段成果，让个人介绍随着实践经历一起更新。

三、当前技能树、技术偏好与自我评估

3.1 已具备的知识与能力

能力	当前基础与可以完成的事情	需要继续加强的部分
Python 编程	掌握基础语法，能够编写简单程序；本次材料体现了函数调用、环境变量读取、文件保存和 JSON 记录的应用	更复杂的程序组织、输入边界处理、异常分类与自动化测试
C 语言	具备基础编程能力	将语法知识用于更复杂的问题，提升代码阅读和调试能力
数据处理	了解 Pandas 基础操作，能够进行简单的数据清洗与整理	对复杂数据质量问题的判断与处理、完整分析流程的设计
MySQL	掌握基础 SQL，能够进行基本的数据查询与操作	更系统地学习数据库设计、复杂查询和性能问题
API 与界面实践	完成指定模型调用，并通过 Gradio 连接输入、生成结果和日志	对请求与响应机制的深入理解，以及独立前后端开发能力
技术表达	已建立 GitHub 个人资料，通过 Markdown 整理作业	更清楚地说明需求、设计理由、验证过程和结论的局限

我对自己的总体判断是：已经具备编写简单程序和使用工具完成小任务的基础，但还需要通过项目积累，把分散的知识组织成结构清楚、能够验证、方便修改的软件。一次接口调用成功，并不等于已经熟练掌握完整的软件开发过程。

3.2 感兴趣的方向

结合自己的专业和本次实践，我希望继续探索三个方向：

1. 数据处理与分析。 从整理数据进一步走向解释数据，让分析结果能够回答具体问题。
2. AI 应用开发。 学习把模型能力接入实际工具，关注输入设计、结果评估和用户体验。
3. 软件工程实践。 学习需求分析、模块划分、测试和协作，让项目从“能够运行”逐步变成“容易理解和维护”。

3.3 当前欠缺、最希望补足的能力

• 需求分析能力： 把一句任务描述拆成明确功能、限制条件和验收标准。
• 程序设计能力： 合理划分界面、业务逻辑和外部服务调用，降低修改代码时的相互影响。
• 测试与定位问题的能力： 既检查正常结果，也检查空输入、错误参数和服务失败等情况。
• 团队协作能力： 熟悉 Git 分支、合并与代码评审，清楚地表达自己负责的内容。
• 阅读与总结能力： 提高阅读文档和他人代码的效率，把踩过的坑整理成可复用经验。

四、代码量与本学期目标

我希望在本学期期末达到的预期代码量为 3000～5000 行。

我计划通过课程练习和项目实践逐步完成这一目标。统计时以本人编写或实质修改、能够解释的代码为主要口径，尽量排除第三方库、虚拟环境、自动生成文件和重复复制的内容。

除了增加代码量，我更希望提高每段代码的质量：能解释实现思路，能发现并修复错误，能给出运行步骤，并让他人读懂和使用。计划每周保留固定时间进行练习、阅读代码和整理问题记录。

五、对软件工程课程的期待

我最期待学习的是：如何把一个相对模糊的需求，逐步变成可以实现、验证和维护的软件。

首先，希望学习需求分析与设计，知道在写代码之前需要确认哪些问题、怎样判断功能是否完成。其次，希望学习测试与质量保证，不再只用“这次运行没有报错”来评价程序。最后，希望通过团队项目练习任务分工、版本管理和沟通，让不同成员编写的内容能够顺利结合。

本次作业规模不大，但已经涉及输入、云端服务、等待时间、输出文件和页面反馈。这让我意识到，软件工程的方法可以从小项目开始练习，而不必等到大型项目才考虑。

六、AI 生成的软件工程课程学习指南与评价

6.1 使用工具与生成要求

本次选择的 AI 工具为 OpenAI Codex。下面的指南由本次 AI 辅助作业整理过程生成，面向已经有 Python、C 和 SQL 基础，希望提升工程实践能力的学习者；它是通用学习建议，不代表任课教师的教学进度安排。

生成要求：请围绕需求分析、软件设计、编码、测试、团队协作与总结，给出一份简要的软件工程课程学习指南，并说明每个阶段可以留下什么成果。

6.2 AI 生成的学习指南

1. 先理解需求，再动手实现。 阅读任务说明，列出目标用户、功能、输入输出和限制条件，为关键功能写出可以检查的完成标准。成果可以是一份简短需求清单。
2. 在编码前进行适度设计。 画出程序的数据流或模块关系，说明界面、业务逻辑和数据存储分别负责什么。先解决当前问题，避免过早设计复杂结构。成果可以是一张模块图和接口说明。
3. 把功能拆成小步骤完成。 优先实现最小可运行版本，再逐步补充功能。使用 Git 保存有意义的修改，写清楚每次修改解决的问题。成果是可运行程序和清晰的提交记录。
4. 用测试检查需求是否满足。 为关键逻辑准备正常、边界和错误场景，记录缺陷与修复结果。成果可以是测试清单、必要的自动化测试和问题记录。
5. 在协作中保持信息一致。 明确分工、接口和时间安排，遇到阻碍及时沟通，提交前检查代码和说明。成果可以是任务看板、接口约定和评审记录。
6. 在交付后复盘。 检查他人能否按照 README 运行项目，对比最初需求与最终成果，总结下一次最值得改进的两三件事。成果可以是使用说明和项目复盘。

6.3 对指南的评价与个人应用

我认为这份指南总体合理，因为它把学习过程与具体成果联系起来，避免只记住“需求分析”“测试”等名词，却不知道怎样实践。它也提醒我，交付内容不仅有代码，还包括运行方法、验证依据和反思。

对我最直接的帮助，是可以用本次图像生成程序练习这些步骤。例如，将“能够生成图像”细化为“输入有效提示词后能显示图像并保存记录”；将“错误处理”细化为“空输入能被识别、缺少 Token 时能得到明确提示”；将“交付”细化为“其他人可以依据依赖文件和说明启动程序”。

这份指南也有局限。它没有结合本课程实际安排、考核重点和我每周可投入的时间，不能直接当成固定课表。团队看板、复杂模块设计等内容也需要与项目规模匹配。我的做法是以教师要求为主，把指南转成当前作业中一两项可执行的改进，并通过实际运行和文档核对 AI 建议，而不是照搬所有内容。

七、未来三年的发展规划

我的长期方向是继续深造，目前的考研目标是华南理工大学。希望通过进一步学习，夯实专业基础，提高阅读、分析代码和解决实际问题的能力。以下是围绕这一目标拟定的三年安排，具体节奏会根据学业进展调整。

阶段	主要目标	具体行动与检查方式
第一年：2026.09—2027.08	夯实基础，形成规律的实践习惯	加强 Python、C、SQL 和专业基础；认真完成软件工程课程实践；练习 Git、测试与文档；保留能运行、能讲清楚的小项目
第二年：2027.09—2028.08	推进升学准备，提高综合实践能力	根据实际升学时间安排系统复习，持续阅读专业资料；做一个较完整的数据分析或 AI 应用项目，记录需求、实现与验证过程
第三年：2028.09—2029.08	根据升学结果深入学习并明确方向	若进入研究生阶段，逐步参与研究或项目；若路径调整，则继续通过项目、实习与基础学习积累能力，定期复盘方向与进展

在这三年中，希望 GitHub 和博客能够持续记录我的学习过程，而不是仅用于交作业。相比一次写出很多计划，我更希望每个阶段都有能够展示、运行和解释的成果。

八、Markdown 编写与后台截图

本文使用 Markdown 编写，包含作业信息表、分级标题、表格、列表、代码块、链接与图片。本次在博客园使用 Markdown 编辑器，并将图片上传至博客园。

九、作业总结

通过本次作业，我完成了指定模型的 API 调用和前端交互实践，并整理了成功记录、提示词变化和图像结果。过程中既有生成成功的收获，也暴露了环境配置、提示词输入规范和结果核对方面的问题。

对我而言，这次作业也是一次学习起点的梳理：明确已有的编程基础，承认在需求、设计、测试和协作方面仍需要积累，再把这些不足变成本学期能够逐步完成的目标。