【Agent进阶专题】接入 DeepSeek

本篇实现第一个模型插件 DeepSeek,将消息列表转换为流式请求,并持续返回生成内容。

能力介绍

Agent 只负责组织一次对话,真正生成回答的是模型插件。DeepSeek 插件是一组 ModelProvider 插件中的一个具体实现,专门负责 DeepSeek 模型的配置认证信息、发送 Chat Completion 请求,并把 SSE 响应转换成统一的文本流。后续,我们可能会增加其他模型插件,支持不同的模型和服务。

这一层隔离了具体接口。Agent 不需要了解请求地址、认证方式和响应格式,只处理连续返回的文本。

实现思路

插件创建时读取 API Key、服务地址和模型名称。每项配置都可以显式传入,也可以从环境变量读取;服务地址默认是 https://api.deepseek.com,模型默认是 deepseek-v4-flash。

对话请求发送到 /chat/completions。MVP 版本消息只保留 role 和 content,同时关闭思考模式并启用流式响应。

响应体是一段 SSE 数据流。网络分块不一定与 SSE 事件边界对齐,因此实现中保留一个 buffer:每次读取新数据后按空行拆分事件,无法组成完整事件的尾部留到下一轮继续处理。遇到 [DONE] 结束迭代,其余事件提取 choices[0].delta.content 并向外返回。

setup 行为

setup 检查 API Key,然后把当前实现加入模型能力列表:

1
2
3
4
5
6
7
setup(context) {
if (!apiKey) {
throw new Error("DEEPSEEK_API_KEY is required.");
}

context.add(Hook.ModelProviders, provider);
}

缺少 API Key 时,Kernel 会在 setup 阶段直接启动失败。DeepSeek 不持有跨生命周期资源,因此没有 start 和 stop。

抓手

DeepSeek 对外暴露一个名为 model.providers 的能力,它的契约是 ModelProvider:

1
2
3
4
export interface ModelProvider {
id: string;
chat(messages: ChatMessage[], signal?: AbortSignal): AsyncIterable<string>;
}
  • id:模型实现的唯一标识。DeepSeek 的值是 deepseek。
  • chat():接收完整消息列表和可选的取消信号,以异步迭代器持续返回文本片段。

DeepSeek 的 chat() 首先构造请求:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const response = await request(`${baseUrl}/chat/completions`, {
method: "POST",
headers: {
authorization: `Bearer ${apiKey}`,
"content-type": "application/json",
},
body: JSON.stringify({
model,
messages: messages.map(({ role, content }) => ({ role, content })),
thinking: { type: "disabled" },
stream: true,
}),
signal,
});

非成功状态会带上状态码和响应内容抛出错误;响应体为空也会立即失败。通过检查后,开始解析 SSE:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

try {
while (true) {
const { done, value } = await reader.read();
buffer += decoder.decode(value, { stream: !done });

const events = buffer.split(/\r?\n\r?\n/);
buffer = events.pop() ?? "";

for (const entry of events) {
for (const line of entry.split(/\r?\n/)) {
if (!line.startsWith("data:")) continue;

const data = line.slice(5).trim();
if (data === "[DONE]") return;
if (!data) continue;

const chunk = JSON.parse(data);
const content = chunk.choices?.[0]?.delta?.content;
if (content) yield content;
}
}

if (done) break;
}
} finally {
reader.releaseLock();
}

无论读取正常结束还是中途失败,reader 最终都会释放。至此,底层 SSE 已经变成 Agent 可以直接使用的文本流。

现在内核已经具备完整的对话链路。下一篇接入 CLI,让用户真正从终端发起一轮对话。