软工实践第一次作业

第一次个人作业：从 GitHub 个人主页到 Hugging Face Flux API 实践

这个作业属于哪个课程 H202601软件工程与软件工程实践
这个作业要求在哪里 软件工程课程第一次个人作业
这个作业的目标 完成个人技术主页建设，梳理当前能力与发展规划，学习调用 Hugging Face API，并通过 Flask 与前端页面实现真实感图像的交互生成
学号 102401221

一、准备工作

这次作业真正开始后，我才发现“准备工作”不只是注册两个账号：GitHub 主页要认真整理，博客园也要完成开通、实名、关注和加入班级等步骤。正式提交前，我还需要逐项确认：

二、GitHub 个人主页建设

我的 GitHub ID 是 coderbrain404，个人资料仓库为：

https://github.com/coderbrain404/404coderbrain

我采用 GitHub Profile README 的方式建设个人主页，把个人介绍、技能、项目实践、自我评估和未来三年规划集中放在 README 中。以前 GitHub 对我来说更像是存代码的地方，这次才开始认真把它当作自己的技术名片来整理。

GitHub个人主页截图

2.1 个人介绍

我是一名福州大学计算机科学与技术专业的学生，目前正在学习程序设计、数据分析及相关专业知识。我对数据分析、人工智能、机器学习、软件开发和计算机视觉比较感兴趣。现在还谈不上精通这些方向，但我愿意边学边做，也希望通过 GitHub 留下真实的学习过程，而不只是展示最后的结果。

2.2 当前成果与实践经历

我参加过数学建模相关学习与实践，接触过问题分析、数据处理、数学模型建立、Python 求解、数据可视化和模型评价等环节，也了解了回归分析、时间序列预测、规划模型、聚类模型和启发式优化算法。

在编程实践方面，我完成过 C++ 程序设计、Python 数据处理、Web 前端和 API 调用等课程实验与小型项目。本次 Flux 项目让我第一次比较完整地接触“前端交互—后端接口—第三方模型服务—结果展示”这一整条链路。过程中出了几次意料之外的问题，但也正因为要亲手排查，我对这套流程的印象比单纯照着示例运行深得多。

2.3 未来三年规划

  1. 第一阶段：夯实基础。 系统学习数据结构与算法、数据库、操作系统和计算机网络，提高 Python、C++、Git 和 Linux 的熟练度，并积极参加课程项目和学科竞赛。
  2. 第二阶段：提升项目能力。 选择人工智能、机器学习或数据科学方向深入学习，完成若干具有完整功能、文档和测试的个人项目。
  3. 第三阶段：明确发展方向。 根据学习成果和个人兴趣，在考研与就业之间作出适合自己的选择。无论最终选择哪条道路，我都希望形成完整的计算机专业知识体系，并具备独立分析和解决实际问题的能力。

三、Hugging Face API 调用实践

3.1 项目目标与技术方案

本项目调用 Hugging Face 上的 XLabs-AI/flux-RealismLora 模型生成真实感图片。

  • 后端：Python、Flask、huggingface_hub
  • 前端：HTML、CSS、JavaScript
  • 模型服务：Hugging Face Inference Providers、Fal AI
  • 安全配置：使用 .env 保存 Token，Token 不会发送到浏览器或提交到 GitHub

调用流程如下：

浏览器输入提示词
      ↓
Flask 后端校验参数
      ↓
免费检查网络、Token 和模型可用性
      ↓
调用 Hugging Face / Fal AI 图像生成服务
      ↓
保存 PNG，并将图片返回前端显示

由于免费额度很有限，我不敢让程序遇到网络错误后反复重试，于是增加了 TEST CONNECTION 免费预检。只有预检通过后，真实生成按钮才会启用；真正的图像请求只发送一次，遇到网络错误也不会擅自重试。这个功能看起来不起眼，却让我用额度时安心了不少。

3.2 操作步骤

  1. 在 Hugging Face 注册账号并创建自己的 User Access Token。
  2. 在项目 .env 文件中填写 HF_TOKEN，并通过 .gitignore 防止上传。
  3. 使用 Python 虚拟环境安装 Flask、python-dotenv、huggingface-hub 和 Pillow。
  4. 启动 Flask 服务，浏览器访问 http://127.0.0.1:5000 。
  5. 点击 TEST CONNECTION，确认网络、Token、模型与 Provider 均可用。
  6. 输入提示词并设置尺寸、随机种子、推理步数与提示词强度。
  7. 点击 RUN GENERATION 并确认真实调用。
  8. 在网页预览或下载 PNG，后端同时将图片保存至 generated 目录。

3.3 本次提示词与参数

本次真实调用使用的正向提示词为：

a boy playing basketball

反向提示词为：

illustration, CGI, plastic skin, distorted hands, extra fingers, text, watermark, oversaturated colors
参数 数值
图像尺寸 1024 × 1024
随机种子 42
推理步数 28
Guidance Scale 3.5
模型 XLabs-AI/flux-RealismLora
Provider Fal AI

3.4 API 调用成功记录与结果

后端日志记录了预检、请求开始和调用成功三个阶段，且不包含 Token：

PREFLIGHT_SUCCESS | model=XLabs-AI/flux-RealismLora | provider=fal-ai | attempt=1 | expires_in=600s
INFERENCE_REQUEST_STARTED | model=XLabs-AI/flux-RealismLora | provider=fal-ai | size=1024x1024 | seed=42 | steps=28 | guidance=3.5
API_CALL_SUCCESS | model=XLabs-AI/flux-RealismLora | provider=fal-ai | size=1024x1024 | seed=42 | steps=28 | guidance=3.5 | elapsed=10.74s

网页结果节点显示了 API CALL SUCCESS、模型、耗时、尺寸、随机种子、推理步数和日志位置，可以同时证明前端交互和 API 调用成功。

Flux API调用成功与生成结果

看到图片真正出现在页面上时，我还是挺惊喜的。模型正确理解了“男孩”和“打篮球”两个核心语义，生成了室外篮球场中正在运球的男孩。人物主体清晰，篮球、球衣和球场背景也比较完整，景深与光线有一定的真实摄影感。

3.5 提示词设计复盘

当时为了先确认接口能不能跑通，我使用了很简短的提示词 a boy playing basketball。它的优点是目标明确、输入成本低，但生成完成后再看，也暴露出了几个明显问题：

  1. 没有指定年龄范围，因此模型生成了年龄较小的儿童。
  2. 没有指定具体动作，模型自行选择了运球。
  3. 没有指定时间、光线、拍摄角度、镜头和构图。
  4. 没有描述服装、表情和环境细节，大部分内容由模型自动补全。
  5. 反向提示词虽然包含 text，篮球上仍出现了不准确字符，说明反向提示词不能保证完全消除文字。

本来我想马上修改提示词再做一次对比，结果额度很快就用完了，只能先根据现有图片进行复盘，拟定下面这个更详细的改进版本：

A photorealistic courtside sports photograph of a young adult Chinese man playing basketball on an outdoor urban court, captured while dribbling the ball at high speed, full body in frame, focused expression, realistic athletic posture, natural skin texture and visible sweat, a plain yellow basketball jersey without logos and black shorts, late-afternoon golden sunlight, a chain-link fence and softly blurred basketball hoop in the background, photographed with a professional full-frame camera, 70-200mm lens, f/2.8, 1/1000s shutter speed, shallow depth of field, sharp subject, subtle motion blur, true-to-life colors, candid sports photojournalism, highly detailed

改进后的反向提示词为：

illustration, anime, CGI, 3D render, plastic skin, malformed hands, extra fingers, missing fingers, extra limbs, duplicated basketball, deformed body, floating ball, blurry face, cropped body, text, letters, logo, brand name, watermark, oversaturated colors

这个改进版是我根据真实结果分析后写出的提示词。可惜免费额度已经用尽，没能继续验证，多少有点遗憾；因此这里只记录设计思路，不把没有进行的实验写成已经完成。

3.6 问题排查与额度情况

测试过程中曾出现以下 SSL 错误：

SSL: UNEXPECTED_EOF_WHILE_READING

一开始看到这个错误时，我还担心额度是不是在失败中被扣掉了。检查日志后确认，它发生在读取公开模型信息的阶段，还没有进入图像推理。之后我增加了免费连接预检、十分钟缓存和禁止生成请求自动重试等保护，尽量避免在网络不稳定时浪费额度。

日志中共有两次成功请求，耗时约为 10.74 秒和 10.39 秒，我最终选择其中一张作为作业展示。正当我准备继续调整提示词时，后续请求却返回：

402 Payment Required

这说明当前免费额度已经用完。我刚得到一张适合展示的结果，还没来得及按改进后的提示词继续对比，额度就见底了，确实有些意外和无奈。为了避免无意义地重复请求，我立即停止调用并保留已有结果。这也提醒我：额度有限时，最好先在纸面上把提示词和实验顺序设计好，再进行真实生成。

3.7 API 调用体验与心得

这次实践给我最直接的感受是：让接口“偶尔跑通”并不算太难，但要让它用起来稳定、安心，就没有想象中那么简单。除了请求代码，还要考虑 Token 安全、参数校验、网络异常、调用记录、额度控制、前后端状态同步和用户误操作。

最初我只盯着“能不能把图片生成出来”。遇到 SSL 错误时，我一度不知道请求到底走到了哪一步；后来通过日志定位失败阶段，并区分“免费连接检查”和“可能计费的生成请求”，才慢慢把问题理清楚。以前觉得日志和异常处理只是辅助功能，这次才体会到，它们真的能减少误操作和不必要的损失。

生成结果也让我发现，提示词越短，模型自由发挥的空间就越大。a boy playing basketball 虽然能出图，但年龄、动作和画面风格都不够可控。想获得更稳定的结果，就需要把主体、动作、场景、构图、光线和摄影风格说明白，并根据上一张图有针对性地修改，而不是只靠反复抽取结果碰运气。

四、当前技能树与自我评估

4.1 已具备的能力

  1. Python 与 C++ 基础： 能完成基础程序设计、数据处理和算法实现。
  2. 数据结构与算法基础： 掌握常见数据结构和基础算法思想。
  3. 数据分析与可视化： 能使用 Python 进行数据处理、建模计算与可视化。
  4. 数学建模： 接触过回归、时间序列、规划、聚类和启发式优化。
  5. 开发工具： 能使用 Git、GitHub、Linux、VS Code、Jupyter Notebook 和 LaTeX。
  6. Web 与 API 基础： 能阅读和修改 HTML、CSS、JavaScript，理解前端请求 Flask 后端并调用第三方 API 的流程。

4.2 技术偏好

我目前更感兴趣的方向是人工智能、机器学习、数据科学和计算机视觉。相比只学习一个个孤立的算法，我更想知道它们怎样真正落到应用里，例如做出同时包含数据处理、模型调用、交互界面和结果展示的项目。本次 Flux 实践虽然规模不大，但正好让我看到了这种结合方式。

4.3 仍欠缺的能力

  1. 大型项目的模块划分、架构设计和长期维护经验不足。
  2. 数据结构与算法的综合应用能力仍需提高。
  3. 对软件测试、持续集成、需求分析和团队协作流程了解不够深入。
  4. 对部署、监控、性能优化和安全设计缺少系统实践。
  5. 人工智能方面目前以基础学习和工具调用为主，对模型原理、训练与部署仍需深入学习。

五、当前代码量与课程目标

截至目前，我在程序设计课程实验、算法练习、Python 数据处理、数学建模和个人项目中累计编写了约 8000 行代码。这些代码主要使用 Python 和 C++，也包括部分 HTML、CSS 与 JavaScript。8000 行听起来不少，但它们比较分散，而且很多是以“完成题目、实现功能”为目标。通过这些练习，我已经能够完成基础程序设计和小型项目，不过在代码结构、测试覆盖和多人协作方面仍有明显不足。

完成本学期课程后，我希望新增并认真维护至少 10000 行有效代码。我不想只为了数字堆代码，这里的“有效”应该包括必要的测试、注释、文档和版本记录。我希望至少完成一个结对项目和一个较完整的团队项目，并且能够说清楚自己为什么这样设计，而不只是让程序勉强运行。

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

我最期待学习：

  1. 把模糊想法转化为明确、可验证的需求。
  2. 进行模块划分、接口设计和系统架构设计。
  3. 使用 Git 分支、Issue、Pull Request 和代码评审进行团队协作。
  4. 编写单元测试、接口测试和自动化测试。
  5. 进行项目进度管理、风险控制和迭代复盘。
  6. 把课程项目部署为真正可以访问和使用的软件。

我最想弄明白的一件事是：“会写代码”和“会做软件”之间到底差在哪里。希望课程结束后，我不仅能把功能写出来，还能和团队共同完成一个需求清晰、结构合理、经过测试、有文档并能够持续改进的软件项目。

七、AI 生成的软件工程学习指南

本部分选择的 AI 工具为 ChatGPT。我提出的问题是：

请为计算机专业学生生成一份简要的软件工程课程学习指南，包含理论学习、工程实践、团队协作与复盘方法。

AI 给出的指南如下：

  1. 理解基本概念。 学习软件生命周期、需求分析、系统设计、编码规范、软件测试、维护和项目管理，理解各阶段的联系。
  2. 以项目驱动学习。 将课程概念应用到真实项目，为项目维护需求文档、架构说明、任务看板、测试记录和版本记录。
  3. 规范使用 Git。 使用分支完成独立功能，通过 Issue 记录任务和缺陷，通过 Pull Request 进行合并与代码评审。
  4. 重视测试。 为核心逻辑编写单元测试，为前后端接口编写接口测试，并在重要修改后进行回归测试。
  5. 加强团队沟通。 明确成员分工和完成标准，定期同步进度，及时暴露风险，并记录重要决策。
  6. 进行阶段复盘。 每个迭代结束后总结完成内容、问题、原因和改进措施。
  7. 关注用户价值。 不仅判断程序能否运行，还要考虑功能是否解决真实需求、交互是否清晰、错误是否容易理解。

对 AI 指南的分析

我认为这份指南总体合理，覆盖了需求、设计、编码、测试、协作与复盘，也强调了用项目验证理论。不过第一眼看上去，它也有一点“每句话都对，但比较笼统”的感觉。

其中对我最有帮助的是“规范使用 Git”“重视测试”和“阶段复盘”。我过去更在意功能能不能运行，往往看到结果出来就觉得任务完成了；这次 API 实践却让我发现，异常处理、日志和测试同样重要，有时甚至决定了我敢不敢再点一次生成按钮。

它的局限也很明显：内容比较通用，没有结合本课程的具体作业、团队规模和技术栈，也没有给出每周可执行的量化目标。如果只是读一遍，很可能很快就忘了。因此我给自己补充了三个行动要求：每周至少提交一次可运行代码；重要功能附带测试或验证记录；每次作业结束后记录一个真实问题和解决过程。

八、总结

这次作业的过程比我预想中曲折一些：先整理 GitHub 个人主页，再搭建前后端，接着排查 SSL 错误，最后好不容易生成出可用图片，额度却很快耗尽。虽然有一点无奈，但这些问题反而让我不只是停留在“照着代码调用 API”的层面，而是真正注意到了网络异常、Token 安全和额度控制。

通过这次实践，我也更清楚自己的能力边界：目前可以完成基础编程、数据分析和小型 Web/API 项目，但遇到大型项目设计、测试、部署和团队协作时，仍有很多东西需要补。希望后续课程能让我在不断写代码的同时，也学会把项目做得更可靠、更清楚、更像一个真正的软件作品。

九、博客园后台 Markdown 编辑页面截图

按照作业要求，此处需要放置博客园后台 Markdown 编辑页面截图。

博客园后台Markdown编辑页面

posted @ 2026-09-11 16:11  404coderbrain  阅读(15)  评论(0)    收藏  举报