企业官网建设流程全解析

在实际开发中，把 Grok 这类大模型 API 接入 Bot 项目，最麻烦的往往不是接口调通，而是模板怎么组织。同一个 Bot 里，系统提示词、用户消息、上下文信息、前端展示结构如果没有统一设计，功能一多就变成一堆字符串拼接，改一个需求要翻好几个文件。这篇文章围绕 Grok Bot 的常见实现方式，整理一套可复用的模板体系，包括提示词模板、消息模板、请求参数模板、前端渲染模板和排错模板，并给出一个最小可运行案例。适合正在做 AI 聊天助手、客服机器人、内容生成工具或者想把 Grok 接入现有系统的开发者。读完以后，你可以直接把这套模板结构套到自己的项目里。

1. 先理解 Grok Bot 模板到底解决什么问题

1.1 Grok、Bot、模板三者是什么关系

Grok 是模型的名称，Bot 是基于模型能力构建出来的产品形态，模板是 Bot 与模型之间的消息组织方式。很多项目把三者混在一起，导致代码里到处是魔法字符串。实际上，它们的分工非常清楚：Grok 提供推理能力，Bot 负责接收用户输入、调用模型、返回结果，模板负责把用户输入、系统约束和历史上下文拼成模型能理解的消息数组。

模板不是简单的字符串拼接工具。它决定了两件事：模型看到什么，以及模型输出的内容边界。同一个模型，使用不同的系统提示词模板，回答风格可以完全不同。使用不同的消息模板，模型对上下文的理解也会明显变化。

1.2 模板要解决的四类问题

第一类是提示词不稳定。直接写在代码里的提示词一旦换成带引号、换行、缩进的长文本，很容易破坏字符串结构。第二类是消息格式拼接混乱。OpenAI 兼容接口要求 messages 是数组，里面包含 role 和 content，如果手动拼 JSON，很容易出现缺少逗号、引号转义错误等问题。第三类是上下文体积膨胀。Bot 运行越久，历史消息越长，如果不做模板化裁剪，很快会触发 token 上限。第四类是异常信息不可读。接口返回的错误结构不规范，前端无法统一展示。

模板体系要做的就是把这些问题拆开：提示词统一放模板文件，消息组装统一走函数，上下文裁剪逻辑抽成独立模块。

1.3 模板体系的分层设计

推荐把 Grok Bot 的模板分成四层。

第一层是系统提示模板，定义 Bot 的人设、能力和输出要求。第二层是消息模板，负责把单个用户问题、历史摘要、上下文变量组装成模型输入。第三层是动作模板，如果 Bot 需要调用工具或执行固定动作，动作参数、动作说明、结果回写都要有固定格式。第四层是渲染模板，负责把模型返回的文本、JSON 或流式片段渲染成前端可读内容。

分层的好处是每一层都能单独测试。系统提示词可以单独跑几个 case 验证风格。消息模板可以脱离网络单独验证渲染结果。动作模板可以在没有真实 API 的情况下用 Mock 数据测试。

1.4 常见的错误设计方式

不少项目会把模板直接写在调用函数里，例如在chat_with_grok函数内部拼接一长段字符串。这种方式在调试早期没有问题，但进入多场景迭代后会非常痛苦：每个场景新增一个 if 分支，函数越来越长，模板越来越难维护。另一种错误设计是模板散落在各个文件，系统提示词在 A 文件、用户消息拼接在 B 文件、历史上下文处理在 C 文件，改一处约束要全局搜索。

推荐做法是把模板集中到 templates 目录，通过文件名和版本号管理，代码里只保留加载和渲染逻辑。

2. 环境准备与依赖配置，先把这两件事对齐

2.1 运行环境和依赖库

本文的示例使用 Python 3.10 及以上版本。建议先创建虚拟环境，避免把依赖装到全局。

mkdir grok-bot-template cd grok-bot-template python -m venv .venv source .venv/bin/activate pip install requests python-dotenv

这里使用 requests 直接调用兼容接口，不引入重量级 SDK，因为模板关注的重点是消息组装和渲染结构，不是 SDK 封装。如果你的服务商已经提供 OpenAI 兼容客户端，也可以替换成对应 SDK，但消息结构保持相同。

2.2 API 配置通过环境变量注入

不要把 API Key 写死在代码里。使用.env文件保存，并在代码里通过 dotenv 加载。

创建一个.env.example，内容如下：

GROK_API_KEY=your_api_key_here GROK_BASE_URL=https://your_provider_base_url/v1 GROK_MODEL=grok_your_model_name GROK_TEMPERATURE=0.7 GROK_MAX_TOKENS=1024

这里的关键点是有三个值必须由你实际申请到的服务商配置决定：GROK_API_KEY、GROK_BASE_URL、GROK_MODEL。不同服务商的接口地址和模型名称可能不同，不要直接复制网上任意一个 URL 就当作生产配置。落地前先确认你手上的 API 文档。

2.3 项目目录结构

推荐使用下面的目录结构：

grok-bot-template/ ├── .env.example ├── requirements.txt ├── config.py ├── templates/ │ ├── system_prompt.md │ ├── user_message.md │ └── context_hint.md ├── bot.py └── render.py

config.py 负责读取环境变量，bot.py 负责组装请求和调用接口，render.py 负责把返回结果结构化。templates 目录只放模板文件，不放业务代码。

2.4 环境检查清单

在开始写代码前，按下面的清单检查环境：

3. 用模板文件组织消息，跑通最小调用案例

3.1 系统提示词模板

在templates/system_prompt.md中写入：

你是一个技术问答助手。 你的任务是回答用户提出的技术问题。 回答时必须遵守以下规则： 1. 使用中文回答。 2. 如果问题需要分点说明，条目不要超过 5 条。 3. 对于不确定的信息，必须明确说明“这一点我无法确认”。 4. 不要编造命令、参数、版本号和数值。 5. 回答结束后，可以给出一句下一步排查建议。 当前场景：{scene}

这里的{scene}是模板变量，由代码在渲染时替换。同一个模板可以复用于技术问答、运维排查、代码 review 等不同场景。

3.2 用户消息模板

在templates/user_message.md中写入：

用户问题：{question} 历史相关答案： {history_summary}

如果历史答案为空，渲染时应生成“暂无相关历史记录”而不是空行。这样可以减少模型对空内容的猜测。

3.3 配置文件读取逻辑

创建config.py：

import os from dotenv import load_dotenv load_dotenv() GROK_API_KEY = os.getenv("GROK_API_KEY", "") GROK_BASE_URL = os.getenv("GROK_BASE_URL", "").rstrip("/") GROK_MODEL = os.getenv("GROK_MODEL", "") GROK_TEMPERATURE = float(os.getenv("GROK_TEMPERATURE", "0.7")) GROK_MAX_TOKENS = int(os.getenv("GROK_MAX_TOKENS", "1024"))

代码里对 base_url 做了末尾去斜杠，避免后面拼路径时出现双斜杠。API Key 为空时可以直接抛异常，避免请求后才发现配置缺失。

3.4 模板渲染函数

创建bot.py，核心逻辑如下：

import json import os import requests import config def load_template(path: str, **kwargs) -> str: with open(path, "r", encoding="utf-8") as f: content = f.read() return content.format(**kwargs) def build_messages(question: str, scene: str = "通用技术问答", history_summary: str = "暂无相关历史记录"): system_prompt = load_template( "templates/system_prompt.md", scene=scene, ) user_message = load_template( "templates/user_message.md", question=question, history_summary=history_summary, ) return [ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_message}, ] def chat_with_grok(question: str, history_summary: str = "暂无相关历史记录"): messages = build_messages(question, history_summary=history_summary) payload = { "model": config.GROK_MODEL, "messages": messages, "temperature": config.GROK_TEMPERATURE, "max_tokens": config.GROK_MAX_TOKENS, "stream": False, } url = f"{config.GROK_BASE_URL}/chat/completions" headers = { "Authorization": f"Bearer {config.GROK_API_KEY}", "Content-Type": "application/json", } resp = requests.post(url, headers=headers, json=payload, timeout=60) resp.raise_for_status() data = resp.json() return data["choices"][0]["message"]["content"]

这个最小案例有三个关键点。一是模板渲染使用了str.format，所以模板里的变量必须用{变量名}声明，如果模板内容里包含 JSON 示例，需要写成{{和}}转义，后面会专门说这个坑。二是 messages 是数组结构，系统消息在前，用户消息在后。三是请求结束后只取最终文本，流式场景要在后面的小节扩展。

3.5 调用入口

在文件末尾追加：

if __name__ == "__main__": if not config.GROK_API_KEY: raise SystemExit("GROK_API_KEY 未配置") if not config.GROK_BASE_URL: raise SystemExit("GROK_BASE_URL 未配置") if not config.GROK_MODEL: raise SystemExit("GROK_MODEL 未配置") result = chat_with_grok("Docker 容器启动后立即退出，如何排查？") print(result)

运行：

python bot.py

正常输出应该是模型生成的排查步骤。如果请求失败，会看到 HTTP 状态异常或 JSON 解析错误，这正好进入后面的排错环节。

4. 模板变量与参数设计，避免提示词越长越不可控

4.1 模板变量要做清洗和校验

模板变量最怕出现两类问题：空值和非预期字符。空值会让模板出现“用户问题：”这种不完整结构。非预期字符则可能破坏 JSON 或 Markdown 结构。

在渲染前，建议做三个处理：先strip()去除首尾空白；然后对超出长度的内容做截断；最后对历史内容做摘要替换而不是原样塞入。示例：

def clean_text(text: str, max_len: int = 2000) -> str: text = text.strip() if len(text) > max_len: return text[: max_len] + "..." return text

4.2 消息历史的模板化裁剪

上下文越长，请求越慢，费用越高。不要把所有历史消息都传给模型。常用的做法是把历史消息先压缩成摘要，再把摘要填入用户消息模板的history_summary字段。

mini 实现思路：

def build_history_summary(history: list[dict], max_items: int = 5) -> str: if not history: return "暂无相关历史记录" lines = [] for item in history[-max_items:]: role = item.get("role", "user") content = item.get("content", "") lines.append(f"{role}: {content[:200]}") return "\n".join(lines)

生产环境可以进一步让模型生成历史摘要，但要注意摘要本身也会消耗 token。常规做法是先用长度阈值判断是否需要摘要，再触发摘要请求。

4.3 关键参数的含义与调优

下面以常见的 OpenAI 兼容参数为例，说明它们对模板输出的影响。

实际项目中，不要同时对 temperature 和 top_p 大幅调整，容易造成结果不可解释。通常是固定 top_p，只调 temperature。

4.4 模板版本管理

模板文件也会变更。给模板文件加上版本号是一种低成本高收益的做法：

templates/ ├── system_prompt.v1.md ├── system_prompt.v2.md └── user_message.v1.md

变更模板时，不要直接覆盖旧文件，而是新增一个版本文件。代码里通过配置项指定当前使用的版本。这样如果新模板效果不好，可以快速回退到旧模板，不需要回滚代码。

5. 前端消息渲染模板，让 Bot 输出结构化和可读

5.1 标准消息结构

模型返回的文本不能直接当成前端展示对象。建议先转换成统一结构，再交给渲染层。常见结构如下：

{ "id": "message-001", "role": "assistant", "content": "这是模型返回的文本。", "created_at": "2025-01-01T10:00:00Z", "meta": { "model": "grok_model_name", "tokens_used": 512 } }

字段说明：

5.2 流式响应的处理模板

流式接口返回的不是一次性 JSON，而是一串 data 行。前端不能等到全部结束再渲染，必须逐段追加。

简单的流式拼接思路：

def parse_stream_line(line: str) -> str | None: line = line.strip() if not line.startswith("data:"): return None data = line[len("data:"):].strip() if data == "[DONE]": return None payload = json.loads(data) choices = payload.get("choices", []) if not choices: return None delta = choices[0].get("delta", {}) return delta.get("content", "")

前端拿到增量片段后，只追加到当前消息的 content 尾部，不要重新渲染整个历史列表。如果内容包含 Markdown 代码块，流式渲染时可以先按纯文本追加，等结束后再统一做代码高亮。

5.3 错误消息结构

接口失败时，不要直接把异常文本塞进聊天记录。统一成下面的结构：

{ "role": "assistant", "content": "请求暂时失败，请稍后重试。", "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded", "retry_after": 30 } }

前端根据error.code决定是否显示重试按钮，而不是解析中文字符串。建议在模板中准备一份错误码对照表。

5.4 一个最小渲染函数

如果使用原生 JavaScript，可以这样渲染消息：

<div class="chat-message">function appendMessage(message) { const container = document.getElementById('chat-list'); const node = document.createElement('div'); node.className = 'chat-message'; node.dataset.role = message.role; const content = document.createElement('div'); content.className = 'chat-content'; content.textContent = message.content; const meta = document.createElement('div'); meta.className = 'chat-meta'; meta.textContent = message.meta ? message.meta.model : ''; node.appendChild(content); node.appendChild(meta); container.appendChild(node); return node; }

这里强调一点：渲染用户输入时不要使用innerHTML直接插入，防止 XSS 风险。模型返回内容同样需要避免被当作 HTML 执行。

6. 常见问题与排查链路

6.1 f-string 或 str.format 与 JSON 大括号冲突

现象：模板里写了 JSON 示例，运行时抛出KeyError或IndexError。

原因：str.format会把所有{...}当成变量占位符。例如模板里写了"temperature": 0.7，没有大括号时没问题，但如果写了{"role": "user"}，{就会被解析为模板变量起点。

解决方式：模板中需要展示大括号时写成双大括号：

当前支持的请求参数示例：{{"temperature": 0.7, "max_tokens": 1024}}

或者在代码中不使用format，改用string.Template或第三方模板引擎，比如 Jinja2。对于包含大量 JSON 示例的模板，更推荐 Jinja2，它的变量语法是{{ var }}，和 JSON 的{}天然区分。

6.2 模板变量没有被替换

现象：模型看到了{question}这样的原文。

原因：模板变量名和代码里传入的 kwargs 不一致。例如模板写的是{question}，代码传的是{query}。

解决方式：渲染前打印一次渲染结果，确认没有遗留占位符。也可以写一个测试函数，断言渲染结果中不包含{加变量名这种原始标记：

def test_template_rendered(): content = build_messages("测试问题", history_summary="无") rendered = json.dumps(content, ensure_ascii=False) assert "{question}" not in rendered assert "{scene}" not in rendered

6.3 上下文超长错误

现象：接口返回 context_length_exceeded。

原因：历史消息没有裁剪，导致 messages 总长度超过模型限制。

解决方式：参考 4.2 的摘要逻辑，只保留最近 N 轮消息。同时可以通过响应的usage.total_tokens记录每次请求的消耗，提前设置告警阈值。

6.4 中文内容变成\uXXXX或乱码

现象：打印 JSON 时内容变成\u4f60\u597d。

原因：这是 JSON 的 Unicode 转义，不是乱码。如果想让日志可读，在打印时指定ensure_ascii=False：

print(json.dumps(payload, ensure_ascii=False, indent=2))

HTTP 请求部分使用 requests 的json=参数时，中文会自动按 UTF-8 编码，不需要手动转码。

6.5 排查顺序

遇到问题按下面的顺序检查：

1. 检查 API Key、base_url、model 是否配置正确。
2. 检查模板渲染结果是否符合预期，是否还有占位符。
3. 检查 messages 数组结构和 role 字段是否正确。
4. 检查参数 temperature、max_tokens 是否在合法范围。
5. 检查历史消息是否太长。
6. 查看接口返回的 error 字段，不要只看 HTTP 状态码。
7. 如果是流式接口，先关闭 stream 测试一次，确认基本链路可用。

7. 模板最佳实践与上线前检查清单

7.1 模板目录规范化

一个可维护的模板目录建议包含三部分内容：模板本身、模板说明、模板示例。模板说明记录模板适用的场景，模板示例记录调用参数和预期输出。

templates/ ├── system_prompt.v1.md ├── system_prompt.v1.example.json ├── system_prompt.v1.md └── README.md

在 README 中记录：当前使用哪个版本，变更了哪些内容，上一个版本为什么被替换。这样模板调优不再依赖开发记忆。

7.2 模板测试不能少

给模板加测试的最小方式是准备一组固定输入，断言输出字符串中必须包含和必须不包含的内容。例如：

def test_system_prompt_contains_rule(): system_prompt = load_template("templates/system_prompt.v1.md", scene="运维") assert "用中文回答" in system_prompt assert "不要编造命令" in system_prompt

更进一步，可以把一组典型问题输入到 Bot，验证输出是否包含关键词。这类测试不适合每次提交都跑全量，可以作为夜间回归用例。

7.3 生产环境额外要做的六件事

模板在开发环境跑通后，进入生产环境前还要补齐：

第一，配置外置化。API Key、base_url、model、temperature 都不能写死在代码里。第二，日志要记录 request_id、model、token 消耗和耗时，但不要记录完整用户输入和 API Key。第三，对用户输入做长度限制和风险过滤。第四，增加超时和重试机制，但重试时要避免重复写入用户消息。第五，对敏感场景增加人工审核或内容过滤。第六，保留模板版本回滚能力。

7.4 上线前检查清单

7.5 扩展方向

这套模板体系可以继续扩展成工具调用模板，也就是让 Bot 返回结构化动作指令，再由后端执行对应操作。还可以扩展成 Agent 工作流模板，把用户目标拆成多个子任务，每个子任务单独使用不同的提示词模板。另一个方向是模板配置管理，把模板从文件系统迁移到配置中心，方便非开发人员调整提示词。

最重要的判断是：模板不是一次性写出来的，而是随着真实使用持续迭代的。每次调整模板之后，记录输入、输出和观察结论，让模板变更有据可循。新手刚开始可以只维护 system_prompt 和 user_message 两个文件，等业务复杂度上来后，再引入版本管理和测试机制。