基于Gemini API的长文写作系统：工程化拆解与质量控制实践

1. 项目缘起：当“写一篇5000字报告”成为日常

作为一名长期与文字打交道的从业者，我几乎每天都要面对一个灵魂拷问：“如何高效、高质量地产出长篇内容？”无论是技术文档、市场分析报告，还是深度博客文章，从零到一的构思和撰写过程，总是最耗费心力的。传统的写作流程——收集资料、搭建框架、填充内容、反复修改——不仅周期长，而且对写作者的专注度和知识储备要求极高。

近年来，以GPT为代表的大语言模型（LLM）为内容创作带来了革命性的变化。它们能根据简单的指令生成连贯的文本，极大地提升了效率。然而，在实际应用中，尤其是在生成长文时，我遇到了几个核心痛点：

1. 上下文遗忘：模型在生成长文本时，容易“忘记”前文设定，导致逻辑断裂、前后矛盾。
2. 质量不可控：生成内容在事实准确性、逻辑严谨性、风格一致性上波动很大，需要大量人工后期修正，有时甚至不如自己重写。
3. 结构松散：模型倾向于“意识流”式写作，缺乏清晰、有力的文章骨架，难以直接用于正式场合。

因此，一个单纯调用API生成文本的工具是远远不够的。我们需要的是一个系统，它不仅能“写”，更能“写好”，并且整个过程是可控、可复现的。这就是我着手构建“Gemini-Essay-Writer”项目的初衷。它不是一个简单的提示词工程，而是一套基于Google Gemini API，融合了工程化思维的长文写作生成与质量控制的实践方案。

2. 为什么选择Gemini作为核心引擎？

在众多大模型API中，我最终选择了Google的Gemini系列模型作为核心。这个选择并非跟风，而是基于几个关键的技术考量与实际测试对比。

2.1 核心优势：长上下文与推理能力

项目名为“长文写作”，首要解决的就是上下文长度问题。Gemini 1.5 Pro模型原生支持高达1,048,576个tokens的上下文窗口。这个数字意味着什么？以英文计算，大约相当于70万单词或一本中长篇小说的体量。对于中文，由于token化方式不同，实际承载的汉字量会少一些，但处理数万字的文章也绰绰有余。这为我们将长篇写作任务分解、并让模型始终“记住”全文大纲和核心要求提供了物理基础。

更重要的是，Gemini在长上下文推理上表现突出。在官方基准测试和我的实际对比中，当提示词中包含大量前置信息（如文章主题、风格要求、参考材料）时，Gemini能更稳定地提取和运用这些信息，减少“中途跑偏”的情况。相比之下，一些模型虽然也支持长上下文，但在实际生成中后期容易忽略早期的关键指令。

2.2 实际踩坑：API稳定性与错误处理

选择任何第三方API，稳定性都是生命线。在项目初期，我密集测试了多个主流模型API，Gemini的可用性给我留下了深刻印象。但这并不意味着一帆风顺，开发过程中遇到的几个典型错误，恰恰是构建健壮系统必须处理的：

• api error: 400 'type' must be in ["enabled", "disabled", "auto"]这个错误通常出现在设置某些高级参数（如安全设置safety_settings）时，传入的枚举值不在允许范围内。它提醒我们，必须严格遵循官方API文档的字段定义，任何“想当然”的传参都会导致请求失败。在代码中，我为所有枚举类型的参数建立了常量映射，避免手误。

• api error: 400 this model's maximum context length is 1048576 tokens...这是最需要警惕的错误之一。它提示你发送的请求（提示词+生成内容）总tokens数超过了模型上限。虽然上限很高，但在迭代生成长文时，如果不断将已生成的内容作为历史上下文追加，很容易触达这个限制。解决方案是实施主动的上下文窗口管理：只保留最关键的大纲、核心论点和最近几段内容作为上下文，而非全文。

• api error: connection closed mid-response. the response above may be incomplete网络不稳定或服务器端问题可能导致流式响应中断。对于长文生成，这可能是灾难性的——你拿到了一篇残缺的文章。因此，必须实现重试机制和响应完整性校验。我的做法是，对于非流式调用，检查返回的finish_reason字段；对于流式调用，则需拼接所有chunk，并确保收到了结束标记。

• api error: 529 overloaded. this is a server-side issue, usually temporary这是服务器过载的典型错误。在系统设计时，必须考虑API的速率限制和降级策略。例如，实现指数退避重试、设置请求队列、或在连续遇到此类错误时切换到备用模型（如果有的话）。

这些“坑”让我明白，直接裸调API是不可靠的。一个生产级的写作系统，必须包含完善的错误处理、重试逻辑和降级方案。

2.3 成本与效能的平衡

Gemini API的定价模型相对清晰，按输入输出tokens计费。对于长文写作，成本是需要严肃考虑的因素。Gemini 1.5 Flash模型在保持不错性能的前提下，成本远低于Pro版本，对于许多内容生成任务来说性价比极高。我的策略是：用Flash模型进行头脑风暴、生成初稿和执行一些简单的改写任务；用Pro模型进行最终的质量把关、逻辑润色和复杂推理。这种混合调度策略，能在控制成本的同时保障关键环节的质量。

3. 系统工程：拆解“写作”这个复杂任务

直接让模型“写一篇关于XX的5000字文章”，得到的结果大概率是泛泛而谈、结构松散的。我们必须将写作这个宏观任务，拆解成模型擅长处理的微观步骤。这就是“Gemini-Essay-Writer”的核心架构思想。

3.1 核心工作流：四阶段管道

我将长文生成流程设计为一个四阶段管道，每个阶段都是一个独立的、可评估的LLM调用任务。

第一阶段：深度研究与提纲生成输入：用户主题、目标字数、目标读者、风格要求。 过程：

1. 模型首先进行“思维链”推理，提出关于这个主题需要研究的几个关键子问题。
2. 然后，模拟检索信息（或结合真实的RAG系统，接入知识库），形成对每个子问题的要点总结。
3. 最后，基于研究结果，生成一个详细到三级标题（如1.1.1）的完整文章大纲，并为每个小节标注核心论点和预计字数。 输出：一份结构严谨、内容充实的文章大纲。

• 技巧：在此阶段，我会要求模型以“学术论文”或“专业报告”的严谨性来构思大纲，这为后续内容奠定了坚实的逻辑基础。

第二阶段：分节内容生成输入：第一阶段生成的大纲，当前需要撰写的小节标题及其核心论点。 过程：系统遍历大纲中的每个末端小节（即没有子标题的小节），将其作为独立任务提交给模型。提示词中会包含：全文主题、上级标题、当前小节要求、以及前一小节的内容摘要（用于衔接）。 输出：每个小节的完整段落。

• 技巧：采用“自底向上”的生成方式。先写最末端的细节段落，再基于这些段落去生成它们的上级“小结”段落。这样能确保细节扎实，总结有据。

第三阶段：连贯性与逻辑润色输入：所有已生成的章节内容拼接而成的初稿。 过程：此阶段专门解决“上下文遗忘”导致的问题。模型的任务是通读全文，找出：

1. 逻辑断层：前后观点矛盾、论据不支持论点的地方。
2. 衔接生硬：段落或章节之间缺乏过渡句。
3. 重复与冗余：在不同部分重复表述相同内容。
4. 指代不清：代词（它、这个、上述）指代不明。 模型会输出一个修改列表，并直接生成修正后的文本。

• 技巧：这个阶段可以迭代进行2-3轮。第一轮解决宏观结构和逻辑问题，第二轮解决段落衔接和语言流畅度问题。

第四阶段：风格统一与最终校对输入：经过润色的稿件。 过程：模型扮演最终编辑的角色，确保：

1. 术语一致：全文对同一概念使用相同的术语。
2. 风格一致：保持学术、口语、报告等指定风格的统一。
3. 格式规范：检查标题层级、列表、引用等格式是否正确。
4. 基础错误：明显的语法错误、错别字（虽然LLM对此不一定完全可靠，可作为补充）。 输出：最终定稿。

• 技巧：可以准备一份“风格指南”作为系统提示词的一部分，例如“避免使用被动语态”、“主要论点句需置于段落开头”等。

3.2 提示词工程：从“指令”到“对话”

每个阶段的成功，都依赖于精心设计的提示词。我的提示词模板通常包含以下部分：

1. 角色设定：你是一位经验丰富的[领域]作家/分析师，正在为[某平台]撰写一篇深度文章。
2. 核心任务：清晰、无歧义地描述本阶段需要完成的具体工作。
3. 输入上下文：明确给出模型所需的全部信息，如主题、大纲、前文等。
4. 输出格式：严格规定输出格式，例如请以JSON格式输出：{"revised_section": "修改后的文本", "change_reason": "修改原因"}。这极大方便了后续的程序化处理。
5. 约束条件：列出负面清单，如不要使用比喻、避免主观臆断、必须引用前文提到的数据等。
6. 示例（Few-shot Learning）：对于复杂任务，提供1-2个高质量的输入输出示例，能显著提升模型输出的稳定性和质量。

例如，在“分节内容生成”阶段，一个提示词可能长这样：

你是一位科技专栏作家，正在撰写一篇关于“大模型上下文窗口技术演进”的文章。 当前任务：撰写第2.3小节“KV Cache压缩技术”的内容。 上级标题：2. 扩展上下文窗口的核心技术 全文主题：探讨大模型如何处理超长文本。 本节核心论点：介绍KV Cache的原理、它为何成为内存瓶颈，以及主流的压缩方法（如H2O, StreamingLLM）。 前一小节（2.2）摘要：介绍了“注意力计算优化”中的FlashAttention技术。 要求：写出约500字的内容，需技术准确、解释通俗。开头需与2.2小节自然衔接。 输出格式：直接输出该小节的完整段落文本。

4. 质量控制：让生成内容变得可靠

生成内容只是第一步，确保其质量符合标准才是项目成败的关键。我建立了三层质量控制机制。

4.1 静态规则校验

这是在文本生成后首先进行的自动化检查，速度快，规则明确。

• 长度控制：检查生成段落是否过于简短（偷懒）或冗长（跑题）。不符合字数区间的段落会被标记，触发重写或裁剪。
• 关键词覆盖：检查要求必须出现的术语、概念是否在文中被提及。
• 禁止词检查：过滤掉不符合风格或存在风险的词汇。
• 格式验证：确保Markdown标题、列表等格式符号配对正确。

4.2 基于LLM的动态评估

这是质量控制的灵魂。我们利用LLM（通常使用一个更小、更快的模型如Gemini Flash）来评估另一个LLM生成的内容。评估维度包括：

• 相关性：内容是否紧扣小节标题和核心论点？
• 事实一致性：内容内部及与上下文是否存在事实矛盾？（注：对于事实准确性，严重依赖外部知识库的RAG系统更可靠，此处主要检查逻辑一致性）。
• 连贯性：与上下文的衔接是否自然？
• 语言质量：语句是否通顺、专业？

评估提示词会让模型对每个维度打分（1-5分），并给出简要理由。任何维度低于阈值（如3分），该段落就会进入“修订队列”，由第三阶段或人工进行处理。

4.3 人工在环（Human-in-the-Loop）节点

完全自动化在创意写作中是不现实的。我在流程中设置了几个关键的人工介入点：

1. 大纲确认点：生成大纲后，必须由人工审核并批准。方向错了，后面全错。
2. 核心段落审核点：对于文章的核心论点段落、数据解读段落，系统会高亮标出，建议人工复核。
3. 最终发布前通读：这是最后的防线。

系统会提供一个良好的协作界面，让人工可以方便地“采纳建议修订”、“手动编辑”或“打回重生成”。所有人工反馈又会被记录，用于优化提示词和评估标准。

5. 工程实现与性能优化

将上述设计落地，需要扎实的工程实现。我采用Python作为后端语言，核心架构如下：

5.1 异步处理与任务队列

长文生成是耗时操作。同步请求会阻塞整个流程。我使用asyncio和aiohttp库实现异步调用Gemini API。更重要的是，将每个小节的内容生成任务放入任务队列（如Redis或RabbitMQ），由工作进程并发处理，极大缩短了整体生成时间。

import asyncio from google import genai import aiohttp async def generate_section_async(client, prompt, section_id): """异步生成单个小节内容""" try: response = await client.aio.models.generate_content( model="gemini-1.5-pro-latest", contents=prompt ) text = response.text # 处理响应，存储到数据库，key为section_id return {"section_id": section_id, "content": text, "status": "success"} except Exception as e: # 实现指数退避重试逻辑 return {"section_id": section_id, "content": "", "status": "failed", "error": str(e)} async def generate_all_sections(outline): """并发生成所有小节""" client = genai.Client(api_key="YOUR_API_KEY") tasks = [] for section in outline['sections']: prompt = build_section_prompt(section, outline) task = generate_section_async(client, prompt, section['id']) tasks.append(task) # 限制并发数，避免触发API速率限制 semaphore = asyncio.Semaphore(10) async def sem_task(task): async with semaphore: return await task results = await asyncio.gather(*[sem_task(t) for t in tasks], return_exceptions=True) # 处理results，整合文章

5.2 上下文管理与向量缓存

为了应对长上下文和避免重复计算，我引入了向量数据库（如Chroma或Weaviate）。

• 大纲与主题嵌入：将文章大纲和主题转化为向量存储。在生成每个小节时，可以检索最相关的背景信息，作为上下文注入，而不是每次都传入全文大纲。
• 已生成段落缓存：将已写好的段落也存入向量库。在润色和衔接阶段，系统可以快速检索到需要强相关的上下文段落，提高连贯性处理的准确度。
• 避免重复生成：对于相似的小节请求（比如用户微调主题后重新生成），可以先在向量库中查找是否有语义相近的现存内容，直接复用或在其基础上修改，节省成本和时间。

5.3 成本监控与预算控制

API调用成本必须可视化、可管控。我实现了一个简单的成本计算中间件：

class CostTracker: def __init__(self): self.total_input_tokens = 0 self.total_output_tokens = 0 # Gemini 1.5 Pro 定价示例 (单位：美元/百万tokens) self.input_price_per_million = 3.50 self.output_price_per_million = 10.50 def track(self, response): # 从响应元数据中提取token计数（Gemini API返回usage_metadata） self.total_input_tokens += response.usage_metadata.prompt_token_count self.total_output_tokens += response.usage_metadata.candidates_token_count def get_estimated_cost(self): input_cost = (self.total_input_tokens / 1_000_000) * self.input_price_per_million output_cost = (self.total_output_tokens / 1_000_000) * self.output_price_per_million return input_cost + output_cost

在每个生成阶段开始前，系统会基于历史数据预估本次成本，如果超过单次任务预算，会提醒用户或自动降级到更便宜的模型。

6. 踩坑实录：从“能用”到“好用”的挑战

在实际开发和调优中，我遇到了许多预料之外的问题，它们的解决方案构成了这个项目的宝贵经验。

6.1 提示词幻觉与过度约束

最初，我把提示词写得极其详细，充满了“必须”、“禁止”、“确保”。结果发现，模型有时会产生“提示词幻觉”——它为了满足所有约束，生成的内容僵硬、怪异，甚至逻辑混乱。例如，要求“每段必须有数据支撑”，模型可能会编造一个不存在的数字。

教训与调整：提示词约束要抓大放小。聚焦在任务目标、核心禁忌和输出格式上。对于风格和语言，多用“倾向于”、“建议”等软性约束，并通过Few-shot示例来引导。将“必须准确”改为“请基于以下提供的事实进行阐述”，并附上事实列表，效果更好。

6.2 评估模型的自洽性陷阱

用LLM A评估LLM B生成的内容，可能会陷入“自洽性陷阱”。例如，如果A和B都犯了同样的事实性错误，A可能无法发现B的错误。或者，A可能过于严苛，对一些合理的创造性表达打分过低。

解决方案：

1. 交叉评估：使用不同家族的模型（如Gemini评估GPT生成的内容）进行交叉检查，减少系统性偏差。
2. 多维度聚合：不依赖单一评估分数。结合规则校验（如关键词）、简单启发式方法（如句子长度方差）和LLM评估，综合决策。
3. 人工校准：定期抽样一批内容，进行人工评分，并用这个结果去校准自动评估模型的打分，建立一个简单的线性回归模型来调整自动分数。

6.3 流式生成与中间状态保存

对于超长文章，即使分节生成，每个小节也可能需要数十秒。如果使用同步请求，前端用户体验极差。我改用流式响应（Streaming），让模型边生成，前端边显示。但这带来了新问题：如何保存中间状态？如果用户刷新页面，如何续写？

工程实现：我设计了“段落级”的保存机制。模型每流式生成完一个完整的段落（以句号、问号等为标记），后端就立即将这个段落存入数据库，并更新文章进度。前端则根据段落序列号增量更新界面。这样，即使中断，也能从最后一个完整段落开始继续生成或润色。

6.4 风格迁移的难度

用户可能希望生成一篇模仿某位作家风格的文章。单纯在提示词中说“模仿海明威的风格”效果有限。更有效的方法是提供一段该作家的原文作为“风格锚点”，让模型分析其语言特征（句式、词汇、修辞），然后在生成过程中，定期将当前输出与“风格锚点”进行对比评估，引导模型靠近目标风格。这需要更复杂的多步骤提示链。

7. 实践总结与未来展望

构建“Gemini-Essay-Writer”的过程，是一个将大语言模型从“玩具”变为“生产工具”的典型实践。核心收获在于认识到：LLM不是万能的写手，而是一个强大的、需要精密操控的“思维引擎”。直接提问得到的是概率性的文本，而通过系统工程、任务拆解和质量控制，我们才能将其输出引导至确定、可靠、高质量的方向。

目前这个系统已经能够稳定产出结构清晰、逻辑通顺的初稿，将我从基础写作中解放出来，专注于更高层次的构思和创意。对于技术文档、行业分析、内容营销等标准化程度较高的长文，效率提升尤为明显。

我个人认为，未来的迭代方向会集中在三点：一是更深度的个性化，让系统能学习特定用户的写作习惯和知识体系；二是更强的事实核查能力，与权威知识库和实时搜索引擎深度集成，确保内容的真实性；三是多模态融合，根据文章内容自动建议或生成配图、图表，实现真正的一站式内容生产。这条路还很长，但每一步都让机器与人的协作更加紧密和高效。