Xikapi 接入文档

最佳实践 ​

生产环境接入 Gemini 时，应优先关注密钥安全、服务端代理、上下文控制、结构化校验、函数权限、超时重试、成本控制和隐私保护。

API Key 不要放前端 ​

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

服务端代理调用 ​

推荐调用链路：

text
Browser / app -> your backend -> Xikapi -> Gemini

服务端可以统一处理：

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

合理设置 maxOutputTokens ​

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

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

控制上下文长度 ​

上下文越长，成本越高，也越容易引入无关信息。建议只传递当前任务必要内容。

常见做法：

  • 多轮对话定期摘要
  • 删除无关历史消息
  • 长文档先切分再检索
  • 固定长上下文使用上下文缓存

长文档先切分 ​

不要把大量文档无差别塞进单次请求。更稳妥的流程是：

  1. 文档清洗
  2. 按标题、段落或语义切分
  3. 建立检索索引
  4. 根据用户问题取回相关片段
  5. 让 Gemini 基于片段回答

结构化输出要校验 ​

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

建议校验：

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

函数调用要做权限控制 ​

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

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

生产环境增加超时和重试 ​

建议为上游请求设置超时，并对临时性错误增加有限重试。

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

成本控制 ​

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

  • 简单任务使用 Flash-Lite
  • 常规生产任务使用 Flash
  • 高价值复杂任务使用 Pro
  • 对长上下文使用上下文缓存
  • 对用户、应用和模型设置额度
  • 记录输入 token、输出 token 和缓存命中情况

日志与隐私保护 ​

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

建议记录：

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

谨慎记录：

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