DeepSeek API 工程接入

最后核验日期：2026-08-15。模型名称、价格、限流和预览能力以 DeepSeek API 官方文档 为准。

先选择接口能力

能力	适合场景	工程注意
Chat Completions	兼容现有 OpenAI 风格客户端	处理多轮消息和 Tool Calls
Responses API	需要统一响应和 Agent 工具循环	检查 SDK/模型支持范围
Thinking Mode	复杂规划、代码审查	不把思考文本当业务事实
JSON Output	下游需要稳定结构	仍需服务端 schema 校验
Tool Calls	查询、执行和编排	工具权限不由模型决定
Context Caching	重复系统提示和大段规则	关注缓存命中和失效

安全配置

$env:DEEPSEEK_API_KEY = "replace-with-your-key"
$env:DEEPSEEK_BASE_URL = "https://api.deepseek.com"

不要把真实 Key 写入 Markdown、仓库规则、终端日志或提交记录。生产环境使用密钥管理服务，并为模型调用设置额度和审计。

Go 最小请求

type ChatRequest struct {
    Model    string    `json:"model"`
    Messages []Message `json:"messages"`
}

type Message struct {
    Role    string `json:"role"`
    Content string `json:"content"`
}

func call(ctx context.Context, client *http.Client, key string) error {
    body := ChatRequest{
        Model: "deepseek-v4-flash",
        Messages: []Message{
            {Role: "user", Content: "用一句话解释幂等性"},
        },
    }
    payload, err := json.Marshal(body)
    if err != nil {
        return err
    }
    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        "https://api.deepseek.com/chat/completions",
        bytes.NewReader(payload))
    if err != nil {
        return err
    }
    req.Header.Set("Authorization", "Bearer "+key)
    req.Header.Set("Content-Type", "application/json")
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if resp.StatusCode/100 != 2 {
        return fmt.Errorf("deepseek status: %s", resp.Status)
    }
    return json.NewDecoder(resp.Body).Decode(&result)
}

真实服务还需要超时、响应大小限制、错误体脱敏、请求 trace id 和重试预算。

Java 最小请求

var request = HttpRequest.newBuilder()
    .uri(URI.create(System.getenv("DEEPSEEK_BASE_URL")
        + "/chat/completions"))
    .header("Authorization", "Bearer " + System.getenv("DEEPSEEK_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
        {
          "model": "deepseek-v4-flash",
          "messages": [
            {"role": "user", "content": "用一句话解释幂等性"}
          ]
        }
        """))
    .build();

var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

生产代码不要直接拼接用户输入到 JSON；使用 JSON 库、超时、重试和响应 schema。

Tool Calls 的闭环

关键点：

• Tool definition 是模型的使用说明，不是授权；
• 参数先做 JSON schema 和业务校验；
• 工具返回值要有明确错误语义；
• 多轮循环必须设置最大轮数、总 token 和总耗时；
• 最终回答必须基于真实工具结果。

JSON Output 的边界

JSON Output 解决格式倾向，不等于完整 schema 验证。服务端仍应：

1. 限制响应大小；
2. 解析 JSON；
3. 校验必填字段、枚举和长度；
4. 拒绝未知高风险字段；
5. 对失败结果重新请求或转人工。

模型选择原则

不要只按模型名字选择。用你的任务集比较：

• 代码修改后的测试通过率；
• Tool Call 参数正确率；
• 结构化输出解析失败率；
• 平均延迟和 token 成本；
• 复杂任务的人工介入率。

练习

1. 为 search_symbol Tool 写一个 JSON schema 和服务端校验器。
2. 设计一个遇到 429、超时、无效参数时不同的重试策略。
3. 用同一任务比较快模型和思考模型的成本、质量和延迟。

参考资料

• DeepSeek API 文档
• Tool Calls
• JSON Output
• Context Caching