★ FEATURED ARTICLE 写周报时同样一件事有的人写成“推进了项目进度”有的人写成“在有限资源下打通了关键阻塞推动项目提前两天落地”。后者显然更抓人。一个叫ai-word-beautifier的小工具就是干这个的输入一段平淡甚至干巴巴的文字它能在保留原意的前提下生成更有节奏、更有画面感、更适合目标场景的版本。我最初做这个项目是被朋友的公众号稿子逼的——他写的初稿像“产品说明书”改起来又费时于是我想与其人工润色不如做一个能按风格选项批量出稿的 AI 文本美化器。这篇文章会把ai-word-beautifier从需求拆解到技术落地完整复盘一遍。如果你也想给自己的项目加一个“文本润色/风格改写”模块或者想了解一个轻量级 AI 工具从零到能用的过程可以按照下面的思路直接参考。文中涉及的技术方案都是我在实际开发中验证过的不是纸上谈兵。1. 需求拆解先搞清楚“美化”到底在美化什么很多人拿到“文本美化”这个需求第一反应就是“让模型改写一遍”。但真正做下来会发现如果连“美化方向”都没定义清楚LLM 输出就会像脱缰野马——有时给你加一堆华丽辞藻有时又把一句口语改成了新闻稿。所以第一步不是写代码而是把“美化”这个模糊概念拆成可执行的维度。1.1 我给“美化”定义的四个维度在ai-word-beautifier里我把“美化”拆成了四个可量化、可提示的维度而不是笼统的“写得更好”流畅度修正语病、逻辑断裂、累赘表达让句子通顺可读。节奏感调整长短句搭配避免全是长句或全是短句制造起伏。感染力补充具体的动作、画面或细节修辞让读者有代入感。去AI味去掉“总的来说”“需要注意的是”“赋能”这类空洞连接词让文字更像人写的。这四个维度会直接写进 Prompt 里成为模型改写时的一套“检查清单”。你可以理解为你不是让模型“自由发挥文采”而是让它拿着一张评分表逐项优化。后面我会在 Prompt 设计部分给出我实际在用的模板先卖个关子。1.2 产品形态为什么先做 Web 而不是插件或命令行目标用户是谁我一开始就没打算只给程序员用。内容运营、学生、写周报的职场人甚至只想把朋友圈文案写得更生动的人都可能用到。所以产品形态选了一个最轻的 Web 页面一个输入框、一个风格选择器、一个“开始美化”按钮右侧展示多版本结果。这个选择背后的逻辑不复杂命令行工具对非技术用户是门槛浏览器插件则要在多端适配和权限上花不少精力。Web 页面可以最快验证“润色效果是否值得用”等效果被认可再考虑包装成插件或 API 都来得及。技术栈上也特意选了简单方案FastAPI 做后端原生 HTML/JavaScript 做前端没有引入重型前端框架。对一个以“效果验证”为首要目标的项目少一点工程复杂度就能多一点迭代效率。2. 核心模块与技术选型每一行代码都知道自己为什么存在工具的核心链路不复杂用户输入文本 → 调用 LLM API → 输出美化结果。但要把这条链路做得稳定、省钱、体验好有几个关键模块值得单独拿出来说。这部分的决策会直接影响你的调用成本和排队体验。2.1 LLM 接入与 Prompt 工程把模型当成一个需要明确指令的实习生我接入的是国内一家大模型的 OpenAI 兼容接口因为兼容接口意味着可以随时更换底座模型而不改业务代码。模型选的是中等规模版本日常通用表现足够单次调用成本也低。这里有个实操经验不要一上来就上最大的旗舰模型先用普通模型跑通流程、攒够 Prompt 调优经验再评估是否需要升级否则调试期间烧掉的 token 费用会让你肉疼。Prompt 设计是整个项目里最影响体验的部分。我先给一个反向案例——最朴素的写法是“请帮我美化这段文字”这种指令的输出极不稳定有时候只是换了几个同义词有时候会把一句话扩写成一篇小作文。我的解决思路是给模型三个东西角色、任务清单、输出约束。我在系统提示词里写的是你是一位资深中文编辑擅长在不改变原意的前提下提升文本质量。 请按照以下四个维度优化用户提供的文本 1. 流畅度修正语病、逻辑跳跃和冗余表达 2. 节奏感调整长短句搭配控制段落呼吸感 3. 感染力适当补充具体动作、画面化表达避免空洞形容词 4. 去除AI味删掉“总之”“需要注意的是”“赋能”等模板化词语。 要求 - 保留原文所有事实信息、数字、人名和结论 - 不添加原文没有的新事实 - 输出与原文长度接近不得刻意扩写 - 直接输出优化后的文本不做任何解释。这套 Prompt 的核心是把“美化”这个模糊目标变成了可执行的规则。我实测下来加上“不改变事实信息”和“长度接近”这两条硬约束之后输出质量稳定了一大截。这里有一个很容易被忽略的小坑当你不约束长度时模型会倾向于把短文扩写成冗长的“高级感”段落看起来华丽但实际改变了原文的信息密度成年人写周报根本用不上。2.2 流式输出与缓存设计体验和成本一起优化调用 LLM 接口最直观的用户体验问题是等待。默认的完整响应模式一句 300 字的文本往往要转圈 5 到 10 秒用户早就跑了。我最后改成了 SSEServer-Sent Events流式输出让模型生成一个字就推一个字给前端用户第一眼反馈可以缩短到 1 秒内体感改善非常明显。流式输出的技术细节我在后面的代码部分会展开。成本优化则靠缓存。同一个用户如果反复美化同一段文本理想情况应该是秒回且不花第二次 token 费用。我在后端做了一个简单的 Redis 缓存把“原文 MD5 风格参数”作为 key把完整响应结果作为 value。这样第一次调用走 LLM后续相同请求直接读缓存。实测下来周报场景的缓存命中率能到 30% 左右因为很多人会对同一段话反复调整风格对比。2.3 多版本输出与对比机制让用户自己选而不是替他做决定最开始我做的版本是“一次美化返回一个结果”。后来试用时发现一个问题模型改出来的风格有时候不是用户想要的但用户又说不出哪里不对。于是我把输出逻辑改成了一次调用返回三个不同风格的版本用户可以并排对比通顺版只做语句通顺化最小干预生动版增强画面感和感染力适合公众号、演讲精炼版压缩冗长表达适合周报、邮件。这个设计带来的体验提升是巨大的。用户不再需要面对“一个不完美的结果”苦思冥想怎么二次修改而是在三个选项里挑选最接近自己预期的那个。而且多版本输出对后端来说并不增加太多延迟——我是在同一个 LLM 调用里让模型一次生成三个段落而不是发三次请求成本和耗时只比单版本高 20% 左右。3. 实操过程从项目骨架到核心调用链路这一部分直接进入可以照着做的实战环节。我会按照一个真实项目的目录结构、核心代码、调用参数逐段说明省略掉与主题无关的登注册、管理后台等部分只保留能让ai-word-beautifier跑起来的核心链路。3.1 项目结构与依赖准备后端用的 Python 3.10 FastAPI依赖很少fastapi uvicorn openai redis python-dotenv项目目录结构ai-word-beautifier/ ├── main.py # FastAPI 入口 路由 ├── beautifier.py # 核心业务调用 LLM、组装 prompt ├── cache.py # Redis 缓存封装 ├── static/ │ └── index.html # 前端页面 ├── .env # API Key 等敏感配置 └── requirements.txtbeautifier.py是核心模块。它接收请求里的原文和风格参数组装出对应的 Prompt再调用模型接口。这里的重点在于风格参数不是直接拼进 Prompt 的“形容词”而是要转换成具体的改写指令。3.2 核心接口实现流式返回是关键先看main.py里的路由部分包括请求体定义和 SSE 流式响应import json from fastapi import FastAPI from fastapi.responses import StreamingResponse, HTMLResponse from pydantic import BaseModel import beautifier import cache app FastAPI() class BeautifyRequest(BaseModel): text: str # 原始文本 style: str vivid # 风格smooth / vivid / concise stream: bool True # 是否流式输出 class BeautifyResponse(BaseModel): versions: list[str] cached: bool app.post(/api/beautify) async def beautify(req: BeautifyRequest): key cache.make_key(req.text, req.style) cached_data cache.get(key) if cached_data: return BeautifyResponse(versionscached_data, cachedTrue) async def event_generator(): collected [] async for chunk in beautifier.stream_beautify(req.text, req.style): collected.append(chunk) yield fdata: {json.dumps({delta: chunk}, ensure_asciiFalse)}\n\n # 完整结果落缓存 cache.set(key, collected) yield data: [DONE]\n\n return StreamingResponse(event_generator(), media_typetext/event-stream)这里有两个容易踩的坑。第一个是Pydantic 的ensure_ascii问题json.dumps默认会把中文转成\uXXXX转义序列前端拿到 JS 里能正常解析但如果你要在调试工具里直接看 SSE 数据流会看到一堆乱码。第二个坑是缓存写入的时机一定要等流式输出全部结束后再写缓存不要在生成第一个 chunk 时就触发缓存写入否则会把半截文本锁进 Redis 里。再看beautifier.py里的流式调用逻辑import os from openai import AsyncOpenAI client AsyncOpenAI( api_keyos.getenv(API_KEY), base_urlos.getenv(API_BASE_URL) ) STYLE_PROMPTS { smooth: 只做最小干预保持原文结构和语序修正语病和冗余字词。, vivid: 增强画面感和感染力可以适当补充动作、比喻和细节但不得改变事实。, concise: 压缩冗余表达删掉口头禅和重复信息保持信息密度。, } async def stream_beautify(text: str, style: str): system_prompt BASE_PROMPT STYLE_PROMPTS[style] stream await client.chat.completions.create( modelos.getenv(MODEL_NAME), messages[ {role: system, content: system_prompt}, {role: user, content: text} ], temperature0.7, top_p0.9, max_tokens2048, streamTrue, ) async for chunk in stream: delta chunk.choices[0].delta.content if delta: yield delta关于temperature和top_p的选择我有过一段调参经历。一开始我把 temperature 调成 1.0输出确实更有“创造性”但代价是经常出现结构漂移——模型会自己加小标题、加序号甚至把原文一句变成一段。后来降到 0.7同时把top_p设为 0.9输出稳定性和创造性之间达到一个比较合适的平衡点。如果你发现输出还是过于跳脱可以继续往下调到 0.5。3.3 前端交互与多版本展示前端没有用复杂框架一个 vanilla HTML 页面就够了。核心交互逻辑是用户点击“美化”后用fetch请求/api/beautify开启 SSE 读取流并将增量文本实时渲染到三个版本对应的卡片里。这里有一个体验优化的小细节三个版本共用同一条流式响应模型返回的顺序是固定的——第一段给通顺版第二段给生动版第三段给精炼版。我给每个版本设置了独立的渲染区用“流式追加”的方式逐字展示。如果等全部生成完再一次性展示等待时间会变成原来的三倍流式逐字渲染用户看到第一个字就开始感觉“它动了”焦虑感大幅降低。前端代码核心片段const resp await fetch(/api/beautify, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ text: inputText, style: currentStyle }) }); const reader resp.body.getReader(); const decoder new TextDecoder(); let buffer ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n); buffer lines.pop(); for (const line of lines) { if (line.startsWith(data: )) { const data line.slice(6); if (data [DONE]) continue; const parsed JSON.parse(data); appendToVersion(parsed.delta); // 按顺序追加到对应版本卡片 } } }注意TextDecoder一定要带{ stream: true }否则多字节中文在跨 chunk 时会被截断成乱码。这也是早期联调时最容易出现“一个字变成两个乱码字符”的原因。3.4 效果评估不能只看“好听”还要盯住“不跑题”做这个项目最大的坑是很容易被“生成结果看起来很漂亮”蒙蔽而忽略了信息保真度。我给 LLM 加了“不改变事实信息”的约束但约束是概率性的不可能 100% 生效。因此我建了一个小规模评估集30 段文本覆盖周报、新闻稿、朋友圈文案、产品说明四类每段标注了必须保留的事实点数字、人名、关键结论。每次改完 Prompt 或换模型就跑一遍评估集统计“事实点保留率”和“主观润色评分”。文本类型事实点保留率版本平均生成耗时用户主观满意度周报98%4.2s4.6/5新闻稿96%4.8s4.3/5朋友圈文案100%3.6s4.8/5产品说明95%4.5s4.1/5这个表看起来简单但它帮了大忙。比如有一次我为了追求“更生动”在 Prompt 里加了一句“可以适当发挥想象力”结果朋友圈文案的满意度上去了但产品说明的事实点保留率掉到了 88%。因为产品说明里容易出现“最大支持 10 个账号”这类数字模型一发挥就容易写成“支持多账号”。这个波动单靠人工看样本根本发现不了是评估集统计出来的。所以我的建议是这类项目一定要在早期就建一个“最小事实点评估集”哪怕只有 10 条数据也足够在关键改动时帮你守住底线。4. 常见问题与排查技巧实录这个项目从开发到上线踩过的坑比想象中多。我把高频问题整理成一张速查表再挑几个典型场景展开说说。如果你也打算做类似的 LLM 工具这份排雷清单能帮你省不少时间。4.1 高频问题速查表现象直接原因解决办法接口偶尔报 504上游模型超时接入超时重试请求参数加timeout30并设计降级返回输出格式漂移突然出现“1. 2. 3.”列表Prompt 未约束输出结构在系统提示词中加“禁止使用序号列表”的硬性约束中英标点混排模型在中文中插入英文逗号/句号在 Prompt 中加“一律使用全角中文标点”中文乱码、逐字错位前端TextDecoder未启用stream模式初始化时传入{ stream: true }同样的请求反复收费缓存 key 设计不当改用原文MD5 风格参数作为 key并确认缓存写入时机4.2 三个最典型的排查场景场景一超时重试但重试不是越多越好。最开始我在调用 LLM 时没有设置超时前端经常卡住 20 多秒然后报错。后来加了 30 秒超时和一次自动重试情况好了很多。但重试要控制次数我见过有同事写了个“永远重试直到成功”的逻辑结果上游模型真正故障时请求在网关排队堆积把下游连接池打爆了。我的方案是最多重试一次并且只在超时或连接错误时重试业务错误如参数非法不重试。场景二缓存 key 里的中文编码问题。早期我用原文 风格直接拼字符串作为缓存 key结果同样的文本因为一个全角空格差异缓存就是命中不了。后来改成先对原文做 MD5再组合 style 参数作为 Redis key彻底解决了这个问题。另外还要注意MD5 的对象应该是彻底去掉首尾空白后的原文否则一个误入的换行符也能造成缓存大面积失效。场景三流式输出在中间突然中断。SSE 流在传输大文本时偶尔会在中途断掉前端表现为“生成了半句话就停了”。排查下来发现问题不在前端的 reader 逻辑而是云服务器对长连接的 idle 超时设置太短。解决方式是让后端在流式传输时每 15 秒发一个: keep-alive注释帧SSE 协议专门支持这种注释行保活机制避免被网关误杀。5. 扩展方向与个人体会ai-word-beautifier目前已经作为内部工具用了一个多月团队同事反馈“周报终于不用憋了”。我自己最常用的场景反而是写项目复盘——把流水账式的会议记录丢进去选“生动版”生成一版再手动删掉不够准确的细节十分钟就能完成原本需要一小时的润色工作。这个“AI 初稿 人工修正”的协作模式远比让 AI 直接生成整篇文章更可控。后续如果继续做我打算加两个功能。第一是保存用户的“风格偏好”比如运营同学长期偏向“生动版”系统自动记录并默认勾选第二是支持“二次修改”也就是对美化结果不满意时用户可以圈选一段文字输入“这里再口语化一点”这样的指令做局部精修。第二个功能技术上不复杂但对体验的提升应该是决定性的——毕竟没有哪个 AI 工具能做到一次生成就完美关键在于如何降低“修改”这个动作的成本。最后分享一个我在调这个项目过程中的核心体会AI 文本美化器的上限不取决于模型多聪明而取决于你对“美化”的定义有多精确。当你把“写得更好”拆成流畅度、节奏感、感染力、去AI味这些可验证的维度当你给模型划好“不许改变事实”的边界它输出的结果就会稳定地好用。反过来如果只是丢给模型一句“帮我润色”那它就会用随机性回答你。这个原则适用于任何基于 LLM 的工具型产品。
阅读完成 · 觉得有帮助？
