简介:本文面向想用DeepSeek API做应用的开发者,梳理对话、工具调用、文件解析、链接阅读和语音能力的接入思路,并给出可核对的步骤、示例代码与工程注意事项。读完可以判断哪些能力需要查官方文档确认,并规划出从连通测试到上线的路径。
DeepSeek 开放 API 把模型对话、工具调用、文件解析、链接阅读和语音能力拆成相互独立的模块。开发者可以只用其中一部分,也可以把几项组合起来,做出能查资料、读文档、听说话的应用。
接口名称、模型版本和可用工具会随时间变化。本文没有逐项核对官方文档,所以文中涉及具体字段和地址的地方都是示意。动手前,请先以 DeepSeek 官方文档为准,确认以下几件事:当前可用的模型名、接口形态、工具调用的参数格式、各项能力是否已开通,以及计费规则。
很多接入问题都出在假设上。开发者常假定某个模型一定支持联网或文件输入,结果上线后才发现接口返回错误。建议先列一张核对表。
| 核对项 | 需要确认的内容 | 确认来源 |
|---|---|---|
| 模型名 | 当前可调用的模型标识符 | 模型列表接口或官方模型文档 |
| 接口形态 | 对话接口的路径与请求结构 | API 参考文档 |
| 工具调用 | 工具声明格式、返回结构、是否支持并行调用 | 工具调用章节 |
| 联网与阅读链接 | 是否由平台内置,还是需要自行实现 | 功能说明与更新日志 |
| 文件与语音 | 支持的格式、大小限制、是否为独立接口 | 对应接口文档 |
| 计费与配额 | 输入输出单价、附加能力的计费方式 | 价格页面 |
只把确认过的能力写进产品设计。没有确认的能力,可以先用自建方案替代。例如,用自己的爬虫或搜索服务获取网页内容,再交给模型总结。
在控制台创建 API Key,并把它保存在环境变量里。密钥不应写进代码、提交到代码仓库或打印到日志中。
export DEEPSEEK_API_KEY="你的密钥"
下面的代码是结构示意。API_BASE 与 MODEL 都是占位值,运行前请替换成官方文档给出的地址和模型名。
import osimport requestsAPI_BASE = "https://YOUR_API_BASE" # 占位,以官方文档为准MODEL = "YOUR_MODEL_NAME" # 占位,以官方模型列表为准API_KEY = os.environ["DEEPSEEK_API_KEY"]def chat(messages, timeout=30):resp = requests.post(f"{API_BASE}/chat/completions",headers={"Authorization": f"Bearer {API_KEY}","Content-Type": "application/json",},json={"model": MODEL, "messages": messages},timeout=timeout,)resp.raise_for_status()return resp.json()["choices"][0]["message"]["content"]print(chat([{"role": "system", "content": "你是一个严谨的助手,回答时说明依据。"},{"role": "user", "content": "用两句话介绍你能做什么。"},]))
代码里设置了超时,并在 HTTP 错误时抛出异常。这两点在生产环境中必不可少。
如果平台没有内置联网搜索,可以把搜索声明为一个工具,由模型决定何时调用。下面的声明采用常见的函数调用格式,仅作示意。
tools = [{"type": "function","function": {"name": "web_search","description": "搜索互联网,返回标题、链接和摘要。","parameters": {"type": "object","properties": {"query": {"type": "string", "description": "搜索关键词"},"limit": {"type": "integer", "description": "返回条数,建议不超过5"},},"required": ["query"],},},}]
应用收到模型发出的工具调用请求后,执行真实的搜索函数,再把结果以工具消息的形式回传给模型。这个过程需要循环,直到模型不再请求工具为止。循环次数应设上限,避免模型反复搜索。
先用纯文本问题测通连接,再加入工具,最后加文件和语音。每加一项,都单独验证一次。出错时,排查范围很小,容易定位。
命令行客户端或图形化聊天客户端等第三方调试工具,可以用来快速检查密钥和模型名是否正确。它们只是测试手段,不代表完整支持官方的全部能力。
用户提问后,应用调用搜索工具,拿到链接和摘要,再让模型生成回答。回答中应附上来源链接。页面展示时,同时显示标题、域名和抓取时间,方便用户核验。
实现要点:
用户上传 PDF 或 Word 文件后,系统先提取文本,再把相关段落拼入上下文。长文档不应整篇放入请求,而应先切分,再按问题检索相关段落。
实现要点:
语音助手的常见流程分为三段:语音识别、