简介:本文面向接入DeepSeek API的开发者,给出不依赖未确认内置工具的实现路径:用外部检索获取实时资料,用模型问答完成总结,并补充PDF解析、链接读取、错误重试与上线选型。示例强调环境变量、降级策略与官方文档核对,帮助快速落地。
核对说明:本文写作核对日期为2026-06-22,接口入口以 DeepSeek 官方文档为准。模型名、工具字段、限流策略可能随版本调整,生产上线前请在官方控制台与文档中再次确认。本文示例采用 OpenAI 兼容调用方式,常见对话模型名使用 deepseek-chat,复杂推理可评估 deepseek-reasoner;如当前账号或文档中模型名称不同,以官方最新说明为准。
如果你要接入 DeepSeek 并做“联网搜索 + 文件解析”,最稳妥的路径不是直接假设模型自带搜索工具,而是拆成三层:
这样即使官方接口字段变化,也不会把整条业务链路写死。下面给出一套可操作的接入方案。
| 目标 | 推荐实现 | 是否必须依赖 DeepSeek 内置工具 | 上线注意点 |
|---|---|---|---|
| 联网搜索 | 外部搜索 API 获取摘要,再交给 DeepSeek 总结 | 否 | 搜索结果需去重、截断、标注来源 |
| 文件输入 | 官方文件接口或本地解析 PDF/DOCX | 视官方能力而定 | 文件过大先拆分或压缩 |
| 网页总结 | 抓取公开链接后清洗正文,再交给模型 | 否 | 仅抓取合法公开内容,限制域名 |
| 内容安全 | 应用层输入输出审核 + 日志留存 | 否 | 不能只依赖模型参数 |
| 复杂推理 | 使用对话模型或推理模型 | 视场景选择 | 关注延迟与 token 成本 |
如果你在官方文档中看到文件上传、联网检索、链接读取等专用参数,应按官方字段实现;如果当前文档没有提供对应能力,建议采用上述“外部检索/解析 + DeepSeek 对话”的工程方案,避免把未确认参数写入生产代码。
不要让模型直接回答实时问题,而是先检索,再让模型基于检索结果回答。这样更稳定,也更便于审计。
流程:
title、url、snippet 等结果。以下代码使用 OpenAI 兼容 SDK 调用 DeepSeek。web_search 是自定义占位函数,你需要替换为官方搜索接口、企业搜索接口或自建检索服务。
import osimport timefrom openai import OpenAIclient = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"],base_url="https://api.deepseek.com")def web_search(query: str, top_k: int = 5):# 自定义占位:替换为真实搜索服务。# 返回结构示例:# [{"title": "...", "url": "...", "snippet": "..."}]return [{"title": "示例结果","url": "https://example.com","snippet": "请替换为真实检索结果"}]def build_search_prompt(query: str, results: list):lines = []for index, item in enumerate(results, start=1):title = item.get("title", "")snippet = item.get("snippet", "")url = item.get("url", "")lines.append(f"[{index}] {title} {snippet} {url}")return f"""用户问题:{query}检索资料:{os.linesep.join(lines)}要求:1. 仅基于上述资料回答;2. 如资料不足,请明确说明“未检索到可靠来源”;3. 尽量在关键结论后标注引用编号。"""def chat_with_retry(messages, model="deepseek-chat"):last_error = Nonefor attempt in range(4):try:return client.chat.completions.create(model=model,messages=messages)except Exception as error:last_error = errorif attempt == 3:raisetime.sleep(2 ** attempt + 0.5)raise last_errorquery = "近期 AI 大模型发布有哪些值得关注的方向?"results = web_search(query)response = chat_with_retry(messages=[{"role": "user", "content": build_search_prompt(query, results)}])print(response.choices[0].message.content)
url 和 title,不要只依赖模型输出。文件解析的核心不是“把文件丢给模型”,而是先把文件转成模型可读的文本,再进入问答链路。
以下示例依赖 pypdf,安装命令:
pip install pypdf openai
import osfrom pypdf import PdfReaderfrom openai import OpenAIclient = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"],base_url="https://api.deepseek.com")def extract_pdf_text(path: str, max_chars: int = 12000) -> str:reader = PdfReader(path)text_parts = []total_chars = 0for page in reader.pages:page_text = page.extract_text() or ""if not page_text:continuetext_parts.append(page_text)total_chars += len(page_text)if total_chars >= max_chars:breakreturn "\n\n".join(text_parts)[:max_chars]def summarize_document(file_path: str):content = extract_pdf_text(file_path)if not content.strip():return "文档未提取到有效文本,请检查文件是否为扫描件或图片型 PDF。"response = client.chat.completions.create(model="deepseek-chat",messages=[{"role": "user","content": f"""请总结以下文档的核心要点,并给出风险提示。文档内容:{content}"""}])return response.choices[0].message.contentprint(summarize_document("report.pdf"))
如果用户给了一个网页链接,推荐流程是:
import osimport requestsfrom bs4 import BeautifulSoupfrom openai import OpenAIclient = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"],base_url="https://api.deepseek.com")def fetch_and_clean(url: str, max_chars: int = 8000):headers = {"User-Agent": "Mozilla/5.0 compatible search-reader/1.0"}response = requests.get(url, headers=headers, timeout=10)response.raise_for_status()soup = BeautifulSoup(response.text, "html.parser")# 简单清洗:移除脚本、样式、导航等for tag in soup(["script", "style", "nav", "footer", "header", "aside"]):tag.decompose()text = soup.get_text(separator="\n", strip=True)return text[:max_chars]def summarize_url(url: str):content = fetch_and_clean(url)if not content.strip():return "未能提取网页正文,请直接粘贴正文内容。"response = client.chat.completions.create(model="deepseek-chat",messages=[{"role": "user","content": f"""请总结以下网页的核心观点,并列出三个关键事实。网页内容:{content}"""}])return response.choices[0].message.contentprint(summarize_url("https://example.com/article"))
注意事项:
| 错误码 | 常见原因 | 处理建议 |
|---|---|---|
| 400 | 请求参数错误 | 检查 model、messages、文件格式 |
| 401 | API Key 无效 | 检查环境变量与密钥轮换机制 |
| 403 | 无权限或地区限制 | 检查账号权限、服务开通状态 |
| 404 | 模型或接口不存在 | 核对官方模型名与接口路径 |
| 413 | 内容或文件过大 | 拆分、压缩、分段总结 |
| 429 | 限流 | 指数退避、降低并发、增加队列 |
| 500/502/503 | 服务端波动 | 重试并保留 request_id |
| 搜索为空 | 检索服务无结果 | 允许模型回答“未找到可靠来源” |
| 网页抓取失败 | 反爬、登录、超时 | 提示用户粘贴正文或更换链接 |
| PDF 解析失败 | 扫描件或加密文件 | 转 OCR、解密或更换文件 |
建议在后端增加统一重试策略:
def request_with_retry(func, max_attempts=4):for attempt in range(max_attempts):try:return func()except Exception as error:if attempt == max_attempts - 1:raisetime.sleep(2 ** attempt)
同时记录脱敏日志:request_id、时间、模型名、输入摘要、输出摘要、错误码、是否命中安全策略。不要记录完整 API Key、用户隐私原文或完整文件内容。
| 方案 | 优点 | 缺点 | 适合场景 |
|---|---|---|---|
| 单模型直连 | 接入简单、链路短、延迟较低 | 多模型适配成本高 | 快速验证、单一业务 |
| 统一 API 网关 | 便于多模型切换、路由、比价 | 需要维护协议转换与监控 | 多模型业务、成本控制 |
| 平台托管 | 运维、合规、生态更完整 | 需要评估绑定与成本 | 对外服务、长期运营 |
如果只是验证 DeepSeek 的问答与总结能力,优先直连。
如果业务需要同时接入多家模型,或按任务路由不同模型,建议使用统一网关。
如果面向公众服务,且对内容审核、日志、运营、合规要求较高,应优先评估托管能力。
总结:DeepSeek 接入的关键不是堆更多参数,而是把“搜索、解析、模型生成、安全治理”拆成可监控、可重试、可降级的工程模块。先跑通最小闭环,再根据官方文档补充字段,才能稳定上线。