最佳实践

生产环境接入 Grok 时，应优先关注密钥安全、服务端代理、状态管理、实时搜索边界、结构化校验、工具权限、超时重试、成本控制和隐私保护。

API Key 不要放前端

不要把 XIKAPI_API_KEY 写入浏览器代码、移动端包或公开仓库。所有 Grok 调用都应通过服务端代理发起。

服务端代理调用

推荐调用链路：

Browser / app -> your backend -> Xikapi -> xAI Grok

服务端可以统一处理：

• 用户鉴权
• 额度限制
• 模型选择
• 请求日志
• 错误映射
• 敏感信息过滤
• 工具权限控制

合理设置 max_output_tokens

max_output_tokens 直接影响输出长度和成本。不同场景建议使用不同上限：

场景	建议
客服短回复	256 - 512
普通问答	512 - 1024
文档总结	1024 - 4096
复杂分析	根据模型能力和业务预算设置

管理多轮状态

Responses API 支持用 previous_response_id 延续对话，但这意味着部分状态由上游保存。生产环境需要明确：

• 是否允许上游保存对话历史
• 本地是否也保存完整消息
• 如何处理超过保存期限的对话
• 是否需要关闭上游状态存储
• 日志中如何关联多轮请求

实时搜索要有边界

实时搜索适合最新信息，但会增加延迟、成本和不确定性。

建议：

• 只在需要最新信息时启用搜索
• 要求模型说明来源和日期
• 对高风险信息做人工复核
• 对搜索次数设置上限
• 缓存可复用的搜索结果

结构化输出要校验

即使设置了 text.format，也要在服务端做解析和业务校验。

建议校验：

• JSON 是否可解析
• 必填字段是否存在
• 枚举值是否合法
• 金额、时间、手机号等格式是否正确
• 是否包含不应出现的额外字段

工具调用要做权限控制

模型只能提出工具调用请求，不能直接执行真实业务动作。服务端必须检查：

• 当前用户是否有权限
• 工具是否在白名单内
• 参数是否通过校验
• 是否需要二次确认
• 操作是否需要审计日志

生产环境增加超时和重试

推理模型、视觉任务和搜索任务可能耗时更长。建议为上游请求设置超时，并对临时性错误增加有限重试。

Suggested strategy:
- Connection timeout
- Total request timeout
- Exponential backoff for 429 / 500 / 503
- Maximum retry attempts
- Fallback model or fallback response

成本控制

成本控制可以从模型选择、上下文长度、搜索工具和并发限制入手。

• 普通任务使用快速模型
• 高价值复杂任务使用推理模型
• 只在必要时启用搜索
• 对用户、应用和模型设置额度
• 记录输入 token、输出 token、工具调用和搜索成本

日志与隐私保护

日志要能排查问题，但不要无边界保存敏感信息。

建议记录：

• 请求 ID
• 响应 ID
• 用户 ID
• 模型名
• HTTP 状态码
• 错误类型
• token 使用量
• 工具调用类型
• 延迟

谨慎记录：

• 原始用户输入
• 图片内容
• 搜索结果全文
• 证件、手机号、邮箱
• 支付、订单、合同等敏感信息