企业官网建设流程全解析

这次我们来看一个和“技术实现”关系不大、但和技术团队关系极大的话题。一个省级竞赛项目，最终只拿到全省第三。项目本身功能完整、链路闭环、答辩演示也很顺利，评委评分出来之后，团队第一反应是遗憾，第二反应才是复盘。复盘之后发现，真正拉开差距的并不是模型效果，也不是功能数量，而是工程化的细节，稳定性、异常处理、部署方式、演示预案，这些平时觉得“差不多就行”的东西，在比赛现场会被十倍放大。

这篇文章不准备讲“怎么拿一等奖”，而是结合这次竞赛项目，复盘为什么一个功能齐全的知识库问答系统只拿到第三名。如果你正在准备类似的省级或国家级竞赛项目，或者在做本地部署、API 服务、批量任务这类偏工程化的技术项目，这篇文章值得直接收藏。我们先把项目背景、技术选型、现场问题、赛后压测、改进方案和排查清单都过一遍。

1. 竞赛项目复盘：核心信息速览

上面这张表先给结论。项目本身不是没做完，而是做得“太像一个演示项目”，不够像一个“可交付的系统”。省级竞赛的评委往往不会只盯着功能亮点，他们更在意系统在真实环境里能不能稳定跑，出了问题能不能快速恢复，操作流程是否足够清晰。第三名的差距，基本都落在这几个点上。

2. 项目复盘：第三名到底输在哪里

先说项目本身做了什么。这是一个典型的知识库问答系统，用户可以上传 PDF、Word、图片等文档，系统先做解析和文本切片，再生成向量存入向量库。用户提问时，系统从向量库召回相关片段，交给大模型生成回答。最终界面是一个 WebUI，支持上传文档、提问、查看引用来源。整个链路从技术角度看是完整的，也符合当前 RAG 应用的主流架构。

但赛后复盘时，团队列了一个问题清单，发现所有问题都可以归到四个方向。

第一个方向是功能覆盖不错，但边界处理不够。文档解析只适配了常规 PDF 和纯文本，遇到扫描版 PDF、图文混排、复杂表格、超长文档时，解析速度明显变慢，偶尔还会出现内容丢失。评委现场测试时，上传了一个含扫描图片的文档，解析耗时长，而且部分段落没有进入知识库，导致后续检索结果不完整。这就是边界场景没有预先测试的结果。

第二个方向是演示场景太顺利，缺少异常流程预演。答辩当天网络状况较好，模型推理速度也正常，整个演示流程是一次通过的。但评委问了一个问题：如果现场没有网络，系统还能不能跑？这个问题直接暴露了本地部署和外部 API 的设计缺陷。项目中部分环节依赖在线模型接口，断网后无法提供回答。演示顺利是好事，但顺利的演示容易掩盖系统对运行环境的强依赖。

第三个方向是批量处理和长文档场景被低估。比赛准备阶段，团队主要测试的是单文档、短文本问答，没有充分测试批量上传、批量解析和多轮对话场景。现场评委要求连续上传多份文档并连续提问时，系统响应逐渐变慢，甚至出现一次请求超时。这说明系统没有做好批处理队列、并发控制和超时处理。

第四个方向是接口和部署层面缺少工程化设计。项目启动依赖手工执行多条命令，依赖版本没有锁定，模型文件路径写死，没有统一的配置文件，也没有一键部署脚本。虽然没有在现场出现严重故障，但这些细节在评委眼中代表项目的可交付程度。一个只能在自己的电脑上跑的项目，和一个可以复制到别的机器上快速启动的项目，评分差距是很明显的。

这四个方向，单独看都不是致命问题，但它们叠加起来，就让项目从“优秀”滑到了“良好”。第三名不一定代表技术上限低，更多是工程化成熟度不够。

3. 项目架构与关键技术点

为了保证复盘内容可落地，这里把项目架构完整拆开。这个架构不复杂，但能覆盖知识库问答系统的主要技术栈。如果你也要做类似项目，可以直接参考这个链路。

3.1 整体链路

3.2 技术选型逻辑

这类项目最容易犯的错误是一开始就追求高端组件。我们当时的做法是先选择了整体架构，再根据本机硬件调整具体组件。

文档解析环节，常规文本直接用 PDF 解析库处理，扫描版 PDF 走 OCR。这里有一个教训：OCR 不是万能的，复杂表格和公式的识别准确率不稳定，如果项目包含大量这类文档，需要对解析结果做人工抽检。文本切片环节，固定长度切片最容易实现，但容易切断语义。更好的做法是按文档标题结构切片，再叠加固定长度兜底。

向量化环节，Embedding 模型的选择要看检索效果和推理速度的平衡。体积过大的模型在 CPU 环境下推理太慢，会直接影响整体响应时间。向量检索环节，数据量少于百万级别时，使用常见的向量库完全够用。大模型生成环节，本地模型可以降低调用成本，但对显存和内存要求较高；在线 API 速度快但依赖网络。如果比赛现场断网，在线 API 就会成为风险点。稳妥的做法是本地模型做主力，在线 API 做备用，或者在答辩前确认现场网络条件。

3.3 架构的局限

这个架构最大的局限是，每一环都是单点。文档解析挂了，后续全部中断；向量库没启动，检索直接失败；大模型服务超时，WebUI 就卡住。项目在演示时能跑通，是因为所有进程都在本机运行且没有异常。但一旦任何一个环节出问题，缺少降级方案，整个系统就会表现为“白屏”或“长时间无响应”。这也是赛后压测中暴露最明显的问题。

4. 比赛现场最容易崩的三个环节

竞赛评审和普通开发测试有本质区别。普通开发时，我们控制环境、控制数据、控制输入，系统自然稳定。比赛现场是评委随机操作，而且往往不会按照预设流程来。从这次项目经历看，有三个环节最容易出问题。

4.1 现场硬件和网络与开发环境不一致

开发时用的电脑配置较高，本地模型推理速度可以接受。现场设备是主办方提供的，硬件规格未知，甚至可能没有独立显卡。如果项目只考虑了 GPU 推理，到现场才发现 CPU 推理速度过慢，演示效果会大打折扣。更麻烦的是，如果系统依赖在线模型服务，而现场网络不稳定，接口请求会一直转圈。建议的做法是：提前编写一份环境检查脚本，启动时自动检测 CPU、内存、显存、Python 版本、依赖版本，并在界面或日志中明确提示。同时准备一个低配模式，在检测到硬件不足时自动降低推理参数。

4.2 演示流程过度依赖“一步成功”

演示时，最怕的不是功能缺失，而是某个操作没按预期执行。比如文档解析需要 30 秒，评委以为卡住了，又点了一次上传；比如批量处理队列没有进度提示，评委不知道系统还在工作；比如大模型生成长回答时耗时较长，界面没有 loading 状态，看起来像死机。这些都不是功能逻辑问题，而是交互和状态反馈问题。演示系统必须有明确的进度条、日志面板和错误提示，哪怕出错，也要让用户知道错在哪里，而不是直接白屏。

4.3 缺少降级和重试机制

在线 API 超时、OCR 服务未启动、向量库连接失败，这些都是运行时可能出现的异常。没有降级和重试机制，一次偶发错误就会中断整个演示。建议在 API 调用层统一封装超时、重试和熔断逻辑。例如每次请求设置最大等待时间，超时后重试一次，再失败则返回明确错误信息。对于批量任务，还需要支持失败任务的重新入队，避免一个坏文件拖垮整个批次。

5. 赛后压测：用数据找问题

赛后第一件事就是做压测。我们设计了一套通用验证流程，用来复现现场出现的问题。这套流程不依赖具体项目实现，你可以直接套在自己项目上。

5.1 压测目标

• 验证系统在连续请求下是否稳定。
• 验证批量上传和批量解析是否会阻塞其他请求。
• 验证单次请求的最大耗时和超时表现。
• 验证显存、内存、CPU 占用是否在预期范围内。
• 验证失败任务是否会影响整个系统。

5.2 并发请求通用脚本

下面是一个简单的 Python 并发测试脚本模板。它使用 requests 发送请求，用 ThreadPoolExecutor 模拟多个用户同时操作。实际使用时，需要把 URL 和 payload 替换成自己项目的接口地址和参数。

import json import time import threading import requests from concurrent.futures import ThreadPoolExecutor, as_completed API_URL = "http://127.0.0.1:8000/api/chat" HEADERS = {"Content-Type": "application/json"} def single_request(prompt: str, timeout: int = 30): payload = { "prompt": prompt, "session_id": "test-session", "top_k": 5 } start = time.time() try: response = requests.post(API_URL, json=payload, headers=HEADERS, timeout=timeout) cost = time.time() - start return { "status_code": response.status_code, "cost": round(cost, 2), "size": len(response.content), "error": None } except Exception as exc: cost = time.time() - start return { "status_code": None, "cost": round(cost, 2), "size": 0, "error": str(exc) } def batch_test(prompts, concurrency: int = 4): results = [] with ThreadPoolExecutor(max_workers=concurrency) as executor: future_map = {executor.submit(single_request, p): p for p in prompts} for future in as_completed(future_map): result = future.result() results.append(result) success_count = sum(1 for r in results if r["error"] is None and r["status_code"] == 200) avg_cost = sum(r["cost"] for r in results) / len(results) max_cost = max(r["cost"] for r in results) error_count = len(results) - success_count print(f"总请求数: {len(results)}") print(f"成功数: {success_count}") print(f"失败数: {error_count}") print(f"平均耗时: {avg_cost}s") print(f"最大耗时: {max_cost}s") for r in results: if r["error"]: print("错误详情:", r["error"]) if __name__ == "__main__": test_prompts = [ "什么是知识库问答系统？", "请总结文档中的核心观点。", "这个项目支持哪些格式的文档？" ] * 10 batch_test(test_prompts, concurrency=5)

这个脚本可以验证两个关键指标：成功率是否等于 100%，最大耗时是否超过项目可接受范围。如果并发数从 1 增加到 5，成功率明显下降，说明系统缺少并发控制或资源管理。如果最大耗时远高于平均耗时，说明存在锁竞争、队列堆积或单请求占用大量资源的问题。

5.3 批量任务观察

批量任务需要单独验证。最直接的测试方法，是准备一个包含 20 份混合格式文档的目录，全部提交到系统进行处理，观察以下指标：

批量任务的优先级很高。评委不一定只测单文档问答，他们可能会连续上传多份资料，要求系统全部解析并纳入知识库。如果这个步骤不稳定，问答效果再好也展示不出来。

6. 从“第三”复盘出的十个工程改进

项目只拿到第三名，但也因此换来了一个非常清晰的改进清单。这里总结十项工程化改进，每一项都来自实际踩坑，不涉及具体硬件参数，适用于大多数竞赛类技术项目。

第一，提供一键启动脚本。把所有启动步骤封装成一个脚本，包括环境检查、依赖安装、模型加载、服务启动。评委和团队成员都能一键跑通，减少手工操作。

第二，建立统一的配置入口。数据库地址、模型路径、端口、API Key、超时时间全部写在一个配置文件中，不在代码里硬编码。这样换机器部署时，只改配置即可。

第三，日志必须结构化。统一输出到文件和控制台，包含时间、模块、级别、消息、请求 ID。出现问题时，能快速定位是解析环节、检索环节还是生成环节出错。

第四，设计降级策略。没有 GPU 时切换低配模式；在线 API 不可用时切换到本地模型；向量库不可用时给出明确报错。系统可以功能减弱，但不能直接崩溃。

第五，为重复查询增加缓存。高频问题、相同文档的解析结果，应该走缓存，避免每次重复计算。这能显著降低演示时的响应时间。

第六，批量任务使用队列处理。每次只处理固定数量的任务，避免资源被瞬间占满。队列状态要在界面上可见。

第七，统一封装外部调用。所有请求都设置超时、重试和错误处理，不允许出现无响应的请求。

第八，准备演示环境预演方案。至少准备两个版本：适配离线环境的版本和适配低配硬件的版本。比赛前在目标设备上完整跑一遍。

第九，编写部署和演示文档。文档中包含环境要求、启动步骤、示例数据、常见问题。这是评委评估项目可交付性的重要参考。

第十，合规和授权检查。项目使用了哪些开源模型、哪些数据、哪些外部接口，都要整理清楚。涉及版权素材、人脸、声音、个人数据时，必须确认授权和隐私合规要求。

7. 如果重新做一次：实施路线

复盘之后，我们重新梳理了一份竞赛项目的实施路线。如果你要参加类似比赛，可以直接参考这个节奏，把工作分成三个阶段，避免前期埋头写代码、后期被迫应付突发情况。

7.1 第一阶段：原型验证与资源评估

第一周不要急着写完整功能，先跑通最小链路。选一份测试文档，完成上传、解析、切片、向量化、检索、生成、展示的完整流程。这个阶段重点记录几类数据：单文档解析耗时、向量化耗时、检索耗时、大模型生成耗时、内存和显存占用。这些数据决定了后续所有优化方向。如果最小链路都无法在本机稳定运行，说明技术选型需要替换，或者本机硬件不满足要求。

7.2 第二阶段：功能补全与边界处理

第二周开始补齐真实使用场景：多格式文档、批量上传、长文档、多轮对话、引用来源展示。这个阶段的核心不是“能跑”，而是“怎么跑都不崩”。每个功能都要配套异常场景测试：文件格式不支持、文件损坏、空文档、超大文档、重复上传、并发提问。批量任务必须有进度显示和失败重试。

7.3 第三阶段：环境演练与系统加固

第三周重点做演示预演。在比赛指定设备或模拟的低配设备上，完整跑通演示流程至少三次。每次演练都记录问题，形成问题清单。最后一次演练要模拟断网、断电重启、系统卡死等异常情况，确认系统至少有办法恢复。此外，准备一份简明的演示脚本，列出固定演示顺序和每个步骤的预期耗时，避免现场自由发挥。

8. 常见问题排查自查清单

下面这张排查清单来自赛后整理，基本覆盖竞赛类项目在部署、演示、压测时最常见的问题。你可以把它当作项目交付前的自检表。

这张表不能覆盖所有问题，但能帮你建立一个初步的排查框架。关键是，所有问题都要能在日志里找到线索，而不是靠猜。

9. 竞赛项目通用最佳实践

除了技术修复，还有一些通用实践值得沉淀下来。这些经验不只适用于竞赛项目，也适用于任何需要本地部署、接口交付或批量任务处理的技术项目。

建议准备一份依赖清单，记录项目使用的所有第三方库、开源模型、外部服务的版本号和许可证类型。项目交付时，这份清单既是文档资产，也是合规依据。特别是在商用或对外发布前，一定要确认使用的模型和数据是否允许再分发、是否要求标注来源。

建议把项目拆成独立的服务模块：解析服务、检索服务、生成服务。每个服务可以单独启动、单独测试、单独重启。这样在一个模块出现问题时，不会拖垮整个系统。如果比赛现场只有一台电脑，可以通过进程管理工具统一管理这些服务，并提供服务状态面板。

建议对系统做一次“冷启动测试”。冷启动指的是从关机状态启动电脑，再从零开始启动项目的全部服务。很多项目在开发状态下表现良好，但重启之后因为没有按顺序启动服务、路径不对、模型文件未挂载等原因直接启动失败。竞赛前必须完成至少两次冷启动测试。

建议为演示准备“兜底方案”。如果系统出现完全无法修复的问题，需要有一个极简的替代演示方式，比如提前录制好的视频，或者离线运行的最小子集。这不是投机取巧，而是工程上的风险控制。

10. 总结与下一步

这次第三名的经历，最值得留下的不是证书，而是复盘出来的工程实践清单。技术能力可以支撑一个项目从零到一跑通，但工程化能力决定它能不能交付给别人使用。对竞赛项目来说，这两者同样重要。

如果你正在准备类似项目，建议先做三件事：第一，跑通最小链路并记录资源占用；第二，坚持做批量任务和异常场景测试，不要只测理想情况；第三，至少完整演练两次演示流程，把系统当成一个要交付的产品，而不是只给自己看的代码。

下一步可以沿着几个方向继续改进：把批量任务处理改为更可靠的消息队列，加入自动化测试和持续集成，增加模型缓存和推理加速，或者把系统封装成 Docker 镜像，做到真正一键部署。第三名的复盘，远比第一名的奖状更值钱。希望这份复盘能帮你少踩几个坑。