DeepSeek V4 API 接入入门 — 小白也能跑通的第一个 Agent

DeepSeek 刚发布了 V4。这次更新里最实在的两件事：编程能力追到 Claude Opus 一线、上下文扩到 100 万 token。再加上价格只有 Claude 的四分之一，对于想开始折腾 AI 的个人开发者、或者第一次想自己搭个 Agent 的小白，现在就是最好的时机。

这篇不讲技术原理，只讲"怎么用"。读完你会拿到：

一个可用的 DeepSeek API Key
用 Python 跑通的第一个对话请求
一个能自己调工具的最简 Agent（就是大家说的"AI 能干活"那种）

全程不需要 GPU，不需要服务器，笔记本就够。

先搞清楚你要用哪个版本

DeepSeek V4 分两档，选哪个取决于你的任务复杂度：

版本	适合场景	输入价（$ / 百万 token）	输出价
V4-Flash	日常对话、快速写作、简单编程	0.14	0.28
V4-Pro	复杂推理、整个项目重构、多步 Agent	1.74	3.48

对照一下：GPT-5.4 的价格是 2.5 / 15，Claude Opus 4.6 是 15 / 75。Flash 比 GPT-5.4 Nano 还便宜，Pro 大约是 Claude Opus 的四分之一。

给新手的建议：先从 Flash 开始。学习阶段大部分请求都是简单的问答和代码补全，Flash 完全够用。等你真要跑多步任务、或者处理几十万字的长文档，再切到 Pro。

一个直观的成本感知：用 Flash 跑 100 次日常对话（平均输入 500 token，输出 800 token），总成本大约 2 分钱人民币。

第一步：拿到 API Key

打开 platform.deepseek.com，用手机号或微信注册
进入「API Keys」页面，点「创建 API Key」，起个名字（比如 test-1）
立刻复制保存。这个 key 只在创建时完整显示一次，丢了只能重新建
去「充值」页面充 10 块钱（对，10 块。新手学习完全够）

拿到的 key 长这样：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx（通常 30+ 位）。

安全提醒：这个 key 等于你的钱包，别提交到 GitHub、别写到前端代码里、别发到群里截图。泄露了立刻去后台撤销。

第二步：跑通第一个对话请求

DeepSeek 的 API 格式和 OpenAI 完全兼容——意思是任何支持 OpenAI 的代码库，换个 base URL 和 key 就能用 DeepSeek。

装一下 Python 的 OpenAI SDK：

pip install openai

写一个最小的脚本 hello.py：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的-key",
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "user", "content": "用一句话介绍一下你自己。"},
    ],
)

print(response.choices[0].message.content)

跑一下：

python hello.py

正常的话几秒钟你就会看到 AI 的回复。如果报 401，检查 key；报 429，说明请求太快被限流，等一会儿再试。

想用 Pro 版本？把 model="deepseek-v4-flash" 换成 model="deepseek-v4-pro" 就行。

第三步：什么是 Agent

这是最多人搞不清楚的概念。我用一句话说清：

Agent 就是让 AI 不光回答你的问题，还能自己决定"我需要调哪个工具"，然后调完工具拿结果继续思考，直到任务完成。

举个例子：

你问它「今天北京天气怎么样？」
普通对话：AI 说「我不知道实时天气」就结束了
Agent：AI 识别到「我需要查天气」→ 调用你给它的「天气查询工具」→ 拿到结果「多云 22 度」→ 组织成回答给你

核心差别：Agent 能主动决策调用工具，而不是只输出文字。

V4 为什么适合跑 Agent：

长上下文 100 万 token，整段对话历史 + 工具调用记录不会被截断
官方专门优化了工具调用稳定性（不会瞎编 JSON 格式）
Codeforces 3206、SWE-bench 80.6 的推理能力保证它能想清楚「该不该调工具」

第四步：跑通你的第一个 Agent

我们做一个最简单的天气查询 Agent。你不需要真的有天气 API，我们写一个假的：

from openai import OpenAI
import json

client = OpenAI(
    api_key="sk-你的-key",
    base_url="https://api.deepseek.com",
)

# 定义一个假的天气工具
def get_weather(city: str) -> dict:
    fake_db = {
        "北京": {"condition": "多云", "temp": 22},
        "上海": {"condition": "小雨", "temp": 19},
        "广州": {"condition": "晴", "temp": 28},
    }
    return fake_db.get(city, {"error": "没有这个城市的数据"})

# 告诉 AI 有哪些工具可用
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询指定城市的当前天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市中文名，例如 北京"},
            },
            "required": ["city"],
        },
    },
}]

# 初始用户消息
messages = [{"role": "user", "content": "北京和广州今天哪个更暖和？"}]

# Agent 循环：AI 想调工具就调，调完把结果给它，直到它给出最终答案
while True:
    response = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=messages,
        tools=tools,
    )
    msg = response.choices[0].message
    messages.append(msg)

    # AI 没想调工具，说明它觉得任务完成了
    if not msg.tool_calls:
        print("最终回答：", msg.content)
        break

    # AI 想调工具，我们真的去调
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })

跑一下，你会看到 AI 自己调了两次 get_weather（一次查北京、一次查广州），然后对比两个温度给出答案。

这就是 Agent 的本质：一个 while 循环 + 工具调用。所有复杂的 Agent 框架（LangChain、CrewAI、AutoGen）本质上都是在这个循环上加壳。

第五步：下一步学什么

如果你只是想用 Agent 干活，不想从零写框架，直接用现成的：

Claude Code：写代码类 Agent，已经原生支持切换到 DeepSeek V4
Coze / Dify：可视化搭 Agent，适合不写代码的产品经理
OpenClaw：开源的浏览器 Agent，V4 适配很稳

如果你想深入学原理，推荐看这几个概念：

ReAct 模式（Reason + Act）：大部分 Agent 框架的基础范式
Tool calling 格式规范：OpenAI / Anthropic / DeepSeek 三家差不多，学一家就能迁移
Context engineering：怎么把上下文（对话历史 + 工具结果 + 用户偏好）塞给 AI 不浪费 token

成本真的能低到什么程度？

用 Flash 跑一个 Agent 完成一次「查两个城市天气 + 对比回答」：

系统提示 + 工具定义：约 200 token
两轮工具调用：约 500 token
最终回答：约 100 token
总计约 800 token，成本 < 1 分钱

跑 100 次这样的任务，1 块钱。跑 10000 次，100 块。

这个价格下，你完全可以放心地用 Agent 处理自己的日常任务——整理收件箱、批量翻译文档、自动写日报、读长论文做笔记，都不用再心疼 API 费用。

一些避坑提醒

API Key 绝对不进 Git：用环境变量 DEEPSEEK_API_KEY，项目根加 .gitignore 排除 .env
请求加超时和重试：网络偶尔会抖，设置 30 秒超时 + 最多重试 2 次
Agent 设最大循环次数：防止 AI 陷入死循环调工具，一般设 10-20 次兜底
生产环境不要直接把用户输入塞进 prompt：注意 prompt injection
控制成本：后台看 Token 使用量页面，按天监控

下次会写 Claude、GPT、Kimi 这些模型在不同场景下的实际表现对比，以及更实战的 Agent 工程化经验。