LLM API 接口设计原则

3.1 核心请求参数

// POST /v1/chat/completions
{
  "model":       "gpt-4o",                // 模型选择（必填）
  "messages":    [                           // 对话历史（必填）
    { "role": "system",  "content": "..." },
    { "role": "user",    "content": "..." }
  ],
  "stream":      true,                    // 是否流式输出
  "temperature": 0.7,                     // 随机性控制
  "max_tokens":  4096,                    // 最大输出 token 数
  "top_p":       0.95,                    // 核采样阈值
  "tools":       [...],                     // Function Calling 工具定义
  "user":        "user_123"               // 终端用户标识（用于监控/滥用检测）
}

3.2 非流式响应 vs 流式响应

// 非流式 — 一次返回完整结果
{
  "id":      "chatcmpl-xxx",
  "object":  "chat.completion",
  "created": 1717401600,
  "model":   "gpt-4o",
  "choices": [{
    "index":        0,
    "message":      { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage":   { "prompt_tokens": 42, "completion_tokens": 128, "total_tokens": 170 }
}

// 流式 (SSE) — 逐 token 推送
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"你"}}]}
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"好"}}]}
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"！"}}]}
data: {"id":"chatcmpl-xxx","choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]

工具定义示例

{
  "type": "function",
  "function": {
    "name":        "get_weather",
    "description": "获取指定城市的天气信息",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string", "description": "城市名" },
        "unit": { "type": "string", "enum": ["celsius","fahrenheit"] }
      },
      "required": ["city"]
    }
  }
}

11.1 语义缓存

对相似的问题（非完全相同）返回缓存结果。实现方式：用 Embedding 向量计算问题相似度，超过阈值命中缓存。代价是牺牲一点准确性换取 50%~80% 的延迟和成本降低。

11.2 请求幂等

通过 X-Idempotency-Key 请求头实现：相同 key 的重复请求返回已缓存的结果，避免网络重试导致重复计费。服务端保留时效一般设为 24 小时。

11.3 可观测性

• 每个请求返回唯一 id：便于排查问题
• 日志记录：输入/输出（脱敏）、延迟、token 用量
• Metrics：TTFT（首 token 延迟）、TPOT（token 间延迟）、吞吐量、错误率
• 成本追踪：按 user 参数区分终端用户，精确计费

11.4 结构化输出

通过 response_format: { "type": "json_schema", "json_schema": {...} } 约束模型输出格式。底层通常通过 grammar-based sampling 或 constrained decoding 实现，保证输出 100% 符合 Schema。