企业官网建设流程全解析

MiniMaxthon 黑客松今天启动，三个赛道正式拉开帷幕。对很多开发者来说，黑客松不是一场“活动”，而是一套被压缩到极致的工程实践：要在几十个小时内完成从选题、调 API、写代码、做演示到交付的全过程。参加过的人都知道，真正决定胜负的不是创意有多宏大，而是能不能在有限时间内拿出一个可运行、可演示、逻辑自洽的最小产品。这篇文章围绕 AI 赛道黑客松的共性技术主线展开，从环境准备、模型调用、应用搭建到现场演示和排错，提供一套可以直接复用的参赛准备流程。无论最终报名的是应用型、智能体型还是多模态方向，下面这些内容都适用。

1. 先理解黑客松的技术挑战，再决定从哪条赛道切入

1.1 黑客松的本质是“压缩版”产品研发

黑客松（Hackathon）由 Hack 和 Marathon 组合而来，核心是在连续时间窗口内完成一个可演示的项目。MiniMaxthon 把多个赛道放在一起，本质上是在考察同一件事：开发者能否把大模型能力转化为一个明确场景里的真实功能。

在常规软件开发里，一个功能可以经历需求评审、设计、开发、测试、联调、上线的完整周期。黑客松没有这个条件。你需要在几十个小时内完成以下动作：

• 确定一个足够具体、评委能立刻理解的问题。
• 选对模型能力和工程手段，而不是堆砌 API。
• 写出能跑的最小代码，并保证依赖可安装。
• 准备一份讲得清楚、演示不崩的呈现。

这里最容易犯的错误是把问题选得过大。比如“做一个智能办公助手”就太大，评审无法在五分钟里看到价值；“做一个会议纪要转结构化周报的工具”就足够具体。问题越小，工程链路越短，你越能把时间花在打磨体验上。

1.2 三大赛道之外，评审真正看重的是完整链路

三个赛道的具体名称和评分规则以官方说明为准，但从技术交付角度看，绝大多数 AI 应用型赛道都有三条共性要求：

建议在动手前先写一句话定义项目：谁在什么场景下遇到了什么问题，我用模型能力把结果变成了什么。这句话写不顺，项目大概率会在演示时讲不顺。

2. 参赛前把开发环境和模型调用准备成“开箱即用”

2.1 Python 环境、依赖和项目结构推荐做法

AI 黑客松里最常见的开发语言是 Python。原因不是其他语言不行，而是模型 SDK、数据处理库和前端演示框架在 Python 生态里集成成本最低。

进入赛程前，先在本机准备好一个干净的虚拟环境：

python -m venv .venv source .venv/bin/activate # Windows 下执行 .venv\Scripts\activate pip install --upgrade pip

基础依赖建议集中在 requirements 文件里维护，避免现场装库时版本冲突：

openai>=1.0.0 fastapi>=0.110.0 uvicorn[standard]>=0.29.0 gradio>=4.0.0 python-dotenv>=1.0.0 requests>=2.31.0

说明一下：这里使用 openai 库只是因为它提供 OpenAI 兼容的调用方式，很多大模型平台都支持这类协议。具体 base_url、模型名和鉴权方式，要以你在 MiniMaxthon 官方资料里拿到的接口文档为准，不要照搬任何文章里的地址。

项目结构建议保持精简：

minimaxthon-demo/ ├── .env # API Key 等敏感配置，不要提交到仓库 ├── requirements.txt ├── app.py # 主程序或服务入口 ├── llm_client.py # 模型调用封装 ├── prompts.py # 提示词模板 └── data/ # 演示用的输入数据

这里要特别强调 .env 的用途。API Key 属于敏感信息，直接写进代码里不仅不安全，现场换 Key 时还容易漏改。使用 python-dotenv 加载环境变量是通用做法：

pip install python-dotenv

在 .env 文件中写入占位内容：

API_KEY=your_api_key_here BASE_URL=https://api.example.com/v1 MODEL_NAME=your_model_name

运行前加载：

from dotenv import load_dotenv import os load_dotenv() api_key = os.getenv("API_KEY") base_url = os.getenv("BASE_URL") model_name = os.getenv("MODEL_NAME")

2.2 模型参数、限流策略和成本要提前确认

调用大模型时，不是所有参数都保持默认就好。下面几个参数直接影响演示效果：

在黑客松场景中，建议把 temperature 控制在 0.2 到 0.7 之间。如果项目是结构化输出（比如生成 JSON、SQL、周报），用偏低的 0.2；如果项目是创意文案，可以到 0.7 左右。

限流和超时也要提前实验。现场集中调用时，同一账号的并发可能触发限流。建议在自己的代码里设置超时和重试机制：

from openai import OpenAI client = OpenAI( api_key=os.getenv("API_KEY"), base_url=os.getenv("BASE_URL"), timeout=30.0, max_retries=2, ) def chat(messages: list[dict], temperature: float = 0.3) -> str: resp = client.chat.completions.create( model=os.getenv("MODEL_NAME"), messages=messages, temperature=temperature, max_tokens=2000, ) return resp.choices[0].message.content

这里 max_retries 设置为 2，是为了应对瞬时网络抖动；timeout 设置为 30 秒，是为了避免演示时界面永久卡住。

注意：演示前把超时时间调短一些，比调长更安全。宁可失败后快速走回退逻辑，也不要让全场等一个长时间转圈的结果。

2.3 用最小脚本确认“模型调用已经通”

很多团队在现场浪费时间的第一个环节，是直到答辩前才发现 API Key 无效或模型名不对。写业务代码之前，先跑一个最小调用脚本：

from dotenv import load_dotenv import os from openai import OpenAI load_dotenv() client = OpenAI( api_key=os.getenv("API_KEY"), base_url=os.getenv("BASE_URL"), ) resp = client.chat.completions.create( model=os.getenv("MODEL_NAME"), messages=[{"role": "user", "content": "请只回复两个字：成功"}], ) print(resp.choices[0].message.content)

预期输出是“成功”。如果这一步失败，问题通常集中在三个位置：Key 是否多复制了空格、base_url 是否写错、模型名是否有效。修好这些问题再往下写业务，效率会高很多。

3. 用“LLM + 工具调用”快速搭建可演示的 AI 应用

3.1 先设计一个最小的场景闭环

不要一上来就写界面。先确定输入、处理和输出：

• 输入：用户提供一段文本，比如会议记录、商品描述、日志片段。
• 处理：把文本交给大模型，配合提示词或工具调用完成解析、分类、改写。
• 输出：一段结构化结果，比如 JSON、Markdown 表格或推荐列表。

以“会议纪要转周报”为例，数据流是：

用户输入会议文本 ↓ 提示词模板拼接 ↓ 调用对话补全接口 ↓ 解析 JSON 输出 ↓ 界面展示周报草稿

这个链路里，唯一不能省的是“解析输出”这一环。大模型可能输出多余文字，导致结构化字段提取失败或展示异常。稳妥做法是让模型只输出目标格式，然后在代码里做一次容错处理。

3.2 用 FastAPI 封装一个最小后端服务

如果演示需要交互式输入，可以用 FastAPI 提供一个 POST 接口：

from fastapi import FastAPI from pydantic import BaseModel from llm_client import chat app = FastAPI() class MeetingText(BaseModel): content: str class ReportResponse(BaseModel): report: str ok: bool @app.post("/api/report", response_model=ReportResponse) def generate_report(data: MeetingText): prompt = f""" 你是一名研发团队助理。请把下面的会议文本整理成结构化周报。 周报需要包含：本期进展、风险与阻塞、下周计划。 只输出 Markdown，不要输出多余说明。 会议文本： {data.content} """ try: result = chat([{"role": "user", "content": prompt}], temperature=0.3) return ReportResponse(report=result, ok=True) except Exception as exc: return ReportResponse( report=f"调用失败，请检查模型服务：{exc}", ok=False, )

启动方式：

uvicorn app:app --reload --port 8000

这里使用 pydantic 定义请求和响应结构，是为了让接口自描述，便于现场用 Swagger 或 curl 验证。接口层先做异常捕获，返回 ok=False，不会让整个进程崩溃。

3.3 用 Gradio 快速做前端演示界面

黑客松演示阶段，最怕的是浏览器兼容和前后端联调问题。Gradio 或 Streamlit 这类工具可以在一两小时内做出可交互界面，把精力留在核心逻辑上。

Gradio 最小示例：

import gradio as gr import requests def build_report(content: str) -> str: resp = requests.post( "http://127.0.0.1:8000/api/report", json={"content": content}, timeout=60, ) data = resp.json() if data["ok"]: return data["report"] return data["report"] demo = gr.Interface( fn=build_report, inputs=gr.Textbox(lines=8, label="粘贴会议文本"), outputs=gr.Markdown(label="周报草稿"), title="会议纪要转周报 Demo", ) demo.launch(server_name="0.0.0.0", server_port=7860)

运行界面后，把一段真实会议文本贴进去，如果能在几秒内得到结构化周报，就说明一个最小闭环已经成立。

如果项目涉及“让模型调用外部工具”，比如查询天气、查询数据库、执行计算，思路同样是先封装一个普通 Python 函数，再把函数描述传给模型，由模型根据用户意图决定是否调用。不要在界面层直接拼接逻辑，要确保工具函数可以脱离界面单独测试。

4. 从“能跑”到“能讲”：验证、打点与演示技巧

4.1 验证模型输出，不能只看“能启动”

很多团队在答辩前的验证只做了一件事：程序能启动。但评审输入的真实数据和你的测试数据不同，常见问题会在演示现场爆发：

• 用户输入过长，超出上下文限制。
• 输入格式不同，提示词里的占位符没有命中。
• 网络波动导致超时，界面一直转圈。
• 输出是 Markdown，前端却按纯文本显示。

建议在答辩前针对三类数据各测一遍：正常输入、边界输入（超长文本、空文本）、异常输入（特殊字符、乱码）。把结果记录成对照表，既方便自查，也是答辩时展示工程严谨性的素材。

4.2 记录请求日志和耗时，为答辩准备数据

答辩时，评委常问“你的方案面向真实场景还有哪些问题”。如果你能拿出请求耗时、token 消耗、失败率这些数据，说服力会明显上升。

在 llm_client.py 中加一段轻量日志：

import time import logging logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") logger = logging.getLogger("llm") def chat_with_log(messages, temperature=0.3): start = time.time() try: result = chat(messages, temperature=temperature) cost = time.time() - start logger.info("model_call duration=%.2fs input_chars=%d output_chars=%d", cost, len(str(messages)), len(result)) return result except Exception: cost = time.time() - start logger.error("model_call failed duration=%.2fs", cost) raise

这些日志不需要很复杂，能说明“调用耗时多少、输入多大、是否失败”就够了。答辩前跑一遍完整流程，把耗时表格打印出来，比口头说“很快”更有说服力。

4.3 演示时准备好回退方案

现场演示的最大风险不是代码写错，而是模型服务不可用。建议准备至少两层回退：

• 第一层：代码里捕获异常，界面上给出友好错误提示，并显示预设的示例结果。
• 第二层：准备一段录好的演示视频。如果现场网络或服务恢复到不及时，直接播放视频并同步讲解。

演示顺序上，先用一条真实输入走完整流程，再用一条容易出错的输入展示错误处理逻辑。这比只展示“完美路径”更像一个成熟的工程交付。

5. 黑客松常见问题排错链路

5.1 现象：模型调用一直超时或 401

先按这个顺序排查：

1. 检查 API Key 是否正确复制，注意首尾不能有多余空格。
2. 检查 base_url 是否带了正确的路径，很多问题是多写或漏写了版本路径。
3. 检查模型名是否与官方文档一致，模型名输入错误通常会报模型不存在。
4. 检查网络环境是否允许访问模型服务，代理或本机防火墙会干扰连接。
5. 检查调用频率是否触发限流，集中测试时可能返回 429。

5.2 现象：模型输出不稳定，时好时坏

输出不稳定通常有三个原因：

• temperature 过高，导致同一输入产生不同结果。调低到 0.2 左右。
• 提示词里没有给出输出格式约束，模型自由发挥。在提示词中明确“只输出 Markdown”“不要解释”。
• 输入文本前后格式不稳定，结构化解析失败。代码中要做容错，尝试从返回文本里截取目标片段。

建议把提示词抽成 prompts.py 中的模板，并且为每个模板准备一个“最小期望输出”。这样换模型、调参时，可以快速回归。

# prompts.py REPORT_TEMPLATE = """你是一名研发团队助理。请把下面的会议文本整理成结构化周报。 周报需要包含：本期进展、风险与阻塞、下周计划。 只输出 Markdown，不要输出多余说明。 会议文本： {content} """

5.3 现象：界面能打开，但点击后没有反应

可能是前后端分离时跨域问题，也可能是前端调用地址写死在了本机 IP。

排查步骤：

1. 打开浏览器开发者工具，查看 Network 面板里请求是否发出。
2. 看请求状态码，重点看 500 和 CORS 错误。
3. 确认前端请求的地址是否指向后端启动的端口。
4. 在后端接口加访问日志，确认请求是否真的到达。

Gradio 自带的服务通常不需要额外处理跨域，但如果使用自定义前端页面，就要在 FastAPI 中允许跨域：

from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"], )

注意：allow_origins 使用星号只适合本地演示。如果项目要发布到公网，必须限定具体来源域名。

6. 参赛交付检查清单与后续扩展方向

6.1 提交前检查清单

以下清单可以直接打印出来，提交前逐项打勾：

• 代码能一键启动，README 写清楚运行命令和依赖安装方式。
• .env 文件未被提交，仓库里只保留 .env.example。
• API Key 已换成自己的账号，脚本里没有他人或测试 Key。
• 主要提示词模板独立成文件，修改后能快速回归。
• 至少测试过正常、超长、空输入三类数据。
• 答辩用的演示数据保存在 data 目录下，不依赖现场输入。
• 演示界面上有错误提示，模型调用失败不会白屏或卡死。
• 准备了一段录屏视频作为回退方案。
• 知道自己方案的局限：成本、延迟、幻觉、数据隐私。

其中“知道自己方案的局限”最容易被忽略。答辩时与其等评委问，不如主动说：这个方案目前对长文本需要分段处理，成本随 token 增加线性上升，生产环境还需要加缓存和内容审核。这种表达比“我们没有缺点”可信得多。

6.2 从黑客松到真实产品的扩展方向

黑客松项目是压缩验证，它证明的是“模型能力在这个场景里可行”。要变成真实产品，还需要补齐几层：

• 数据层：输入落库、用户 Session 管理、历史记录查询。
• 缓存层：相同输入的请求结果缓存，降低延迟和成本。
• 控制层：调用频率限制、内容安全过滤、敏感信息脱敏。
• 观测层：请求日志、耗时监控、token 消耗统计、错误告警。
• 发布层：服务容器化、环境变量注入、自动化部署、回滚脚本。

对话式 AI 应用尤其要注意提示词版本管理。产品上线后提示词不可能不变，建议把提示词模板作为独立文件部署，而不是写死在代码里。这样调整文案不用重新发版。

最后给新手一个练习建议：不要只追求“能跑”，也不要只追求“好看”。把时间分配在三个点上——模型输出正确性、错误处理完整度、演示故事线清晰度。黑客松开出的多个赛道，本质上都是在这三个点上做工程验证。你能稳定重复地跑通一条链路，就已经比只会复制 Demo 的团队高出一个段位。