软件工程第一次作业

| 这个作业属于哪个课程 | https://edu.cnblogs.com/campus/fzu/202601SofwareEngineering/join?id=CfDJ8Ow5-In01nBEvFwaadRGjqH6-l7-Yw52SEssRis1tSY93RHdhZabekRIapaAe-nHUSzbutbpNMOXK1UlQ_pMSDNnxaWs26E78zpYdLYHcMkbahicAItN4c86rx3brvXBWjFnvQxEZFnjKjR4esFn2GA |
| 这个作业要求在哪里 | https://edu.cnblogs.com/campus/fzu/202601SofwareEngineering/homework/15712 |
| 这个作业的目标 | 调用 Hugging Face API（FLUX 模型）实现文生图，Flask 前后端交互，GitHub 个人主页，博客园随笔 |
| 学号 | 102401111 |

2026秋 软件工程第一次个人作业——Hugging Face API 文生图实践

一、项目概述

本次作业要求调用 Hugging Face Inference API，使用 FLUX 相关模型实现文本生成图像功能，通过 Flask 搭建前后端交互界面，用户可在网页输入提示词并生成图片。

技术栈：

• 后端：Python 3.13 + Flask + huggingface_hub + Pillow
• 前端：HTML + CSS + JavaScript（fetch）
• API：Hugging Face Inference API
• 配置：python-dotenv 管理 Token
• 运行环境：Windows 11，本地 http://127.0.0.1:5000

整体流程：

1. 用户在网页输入提示词和参数
2. 前端通过 fetch 发送 POST 请求到 /api/generate
3. Flask 后端读取 .env 中的 HF Token，调用 InferenceClient.text_to_image()
4. 返回的图片用 Pillow 保存为 generated_output.png
5. 前端通过接口获取并展示图片

---

二、环境搭建与依赖安装

2.1 Python 安装

从 python.org 下载 Python 3.13，安装时勾选 Add python.exe to PATH，验证：
bat
python --version
显示安装成功

2.2 依赖安装

在项目目录打开 cmd，执行：
bat
python -m pip install -U pip
python -m pip install flask python-dotenv huggingface_hub flask-cors Pillow

验证安装：
bat
python -c "import huggingface_hub; print(huggingface_hub.version)"
python -c "import PIL; print(PIL.version)"

---

三、Token 配置

在 Hugging Face 官网（huggingface.co/settings/tokens）创建 Fine-grained Token，权限选 Inference，复制 hf_ 开头的字符串。

在项目根目录创建 .env 文件（文件名就是 .env，不是 .env.txt）：
env
HF_TOKEN=hf_我的token

.gitignore 中加入：
gitignore
.env
generated_output.png
pycache/
*.pyc

四、核心代码

4.1 后端 app.py

python
import os
from flask import Flask, request, jsonify, send_file, Response
from flask_cors import CORS
from dotenv import load_dotenv
from huggingface_hub import InferenceClient
load_dotenv()
HF_TOKEN = os.getenv("HF_TOKEN")
if not HF_TOKEN:
raise ValueError("没找到 HF_TOKEN，检查 .env 文件")
MODEL_ID = os.getenv("HF_MODEL_ID", "black-forest-labs/FLUX.1-dev")
PROVIDER = os.getenv("HF_PROVIDER", "fal-ai")
client = InferenceClient(
provider=PROVIDER,
api_key=HF_TOKEN,
timeout=120,
)
app = Flask(name)
CORS(app)
@app.route("/")
def home():
return send_file("index.html")
@app.route("/api/generate", methods=["POST"])
def generate():
data = request.get_json(silent=True) or {}
prompt = str(data.get("prompt", "")).strip()
width = int(data.get("width", 768))
height = int(data.get("height", 1024))
steps = int(data.get("steps", 28))
seed = data.get("seed")
negative_prompt = str(data.get("negative_prompt", "")).strip()
print(f"收到请求，prompt: {prompt}", flush=True)

if not prompt:
return jsonify({"error": "提示词不能为空"}), 400

image = client.text_to_image(
prompt,
model=MODEL_ID,
negative_prompt=negative_prompt or None,
width=width,
height=height,
num_inference_steps=steps,
seed=seed if seed is not None else None,
)
image.save("generated_output.png", format="PNG")
print("图片保存成功", flush=True)

return Response(send_file("generated_output.png").get_data(), mimetype="image/png")
@app.route("/image")
def image():
return send_file("generated_output.png", mimetype="image/png")
if name == "main":
app.run(debug=True, host="127.0.0.1", port=5000)

4.2 前端 index.html

html

Flux 图像生成

提示词：A realistic photo of a young woman waiting at a rainy bus stop at night, holding a transparent umbrella, wet street, neon lights, cinematic 负提示词： 宽度： 高度： 步数： Seed（留空随机）： 生成图片


---

五、运行与结果

5.1 启动服务

bat
python app.py
终端显示：
text
Serving Flask app 'app'
Debug mode: on
Running on http://127.0.0.1:5000

5.2 浏览器访问

打开 http://127.0.0.1:5000，输入提示词，设置参数，点击「生成图片」。

5.3 生成成功

等待 30 秒~3 分钟后，页面显示生成图片，终端输出：
text
收到请求，prompt: ...
图片保存成功
POST /api/generate HTTP/1.1 200
GET /image HTTP/1.1 200

---

六、提示词设计与修改过程

最终使用的提示词：

A realistic photo of a young woman waiting alone at a bus stop on a rainy night, holding a transparent umbrella and wearing a black coat, wet street reflects neon signs and distant car headlights, bokeh lights, cinematic atmosphere, natural skin texture, photorealistic, 85mm lens, depth of field

负提示词：

cartoon, anime, sketch, painting, oversaturated, plastic skin, extra limbs, deformed hands, blurry face, low quality

设计过程：

版本	提示词	效果	问题
v1	a realistic photo of a woman	能生成人像	过于简单，缺乏细节
v2	加入环境、光线、服装描述	场景更丰富	部分修饰词过强，略显假
v3（最终）	加入负提示词、摄影参数、材质词	光影自然、皮肤真实、照片感强	无

关键要素：

• 主体：年轻女性、透明雨伞、黑色外套
• 环境：雨夜、公交站、湿漉地面、霓虹灯
• 光照：车灯、街灯、反光
• 摄影参数：85mm、景深、电影感
• 负提示词：排除卡通、过饱和、塑料皮肤等问题

---

七、GitHub 个人主页

创建与 GitHub ID 同名的仓库 Kerical/Kerical，在 README.md 中编写个人介绍，包含技能、实践经历、未来规划、项目展示。

---

八、遇到的问题与解决

问题	原因	解决
python 命令不识别	PATH 未添加	重装 Python 勾选 Add to PATH，关闭 WindowsApps 应用执行别名
HF_TOKEN 读取失败	.env 文件名错误	重命名为 .env，确认不是 .env.txt
Please install Pillow	缺少图像库	pip install Pillow
huggingface_hub.version 报错	属性名错误	改为 __version__
PIL.version 报错	属性名错误	改为 PIL.__version__
SSL/连接中断	网络不稳定	改用 huggingface_hub 库自带重试
浏览器 404	未配置 / 路由	添加 @app.route("/") 返回 index.html
前端点击无反应	直接打开 file://	通过 http://127.0.0.1:5000 访问

---

九、实验心得

1. API 调用比本地部署省资源：不需要高端显卡，有 Token 和网络就能生成高质量图像。
2. 环境配置是最大门槛：Python PATH、.env 文件名、依赖版本、属性名拼写等问题占了调试时间的大部分。
3. 提示词工程很重要：同样的模型，提示词质量直接决定效果。加入摄影术语、光线、负提示词能显著提升真实感。
4. 安全意识：Token 不能硬编码、不能提交到公开仓库，用 .env + .gitignore 管理。
5. Flask debug 模式适合开发：自动重载方便，但生产环境不应使用。

以上为完整作业报告，所有代码、步骤、截图均可复现。