# DeepSeek 网页搜索 > 通用 按 query 搜索网页，返回结构化的结果列表。`model` 固定为 `deepseek-tools-search`，仅用于平台选路，转发前被剥离；其余字段原样透传给上游。 `query` 支持以下搜索语法，可在一个 query 中组合多个操作符，语法会原样传递给搜索服务： | 操作符 | 示例 | 说明 | |---|---|---| | `site:` | `DeepSeek site:github.com` | 将结果限制在指定站点，指定多个时用空格分隔并通过 `OR` 连接，例如 `DeepSeek site:github.com OR site:huggingface.co` | | `-site:` | `DeepSeek -site:example.com` | 排除指定站点，指定多个时用空格分隔 | | `-` | `DeepSeek -广告` | 排除包含指定关键词的网页，指定多个时用空格分隔 | | `-"..."` | `DeepSeek -"release notes"` | 排除包含指定短语的网页，短语内可以包含空格，指定多个时用空格分隔 | | `"..."` | `DeepSeek "精确短语"` | 精确匹配指定短语，指定多个时用空格分隔 | | `lang:` | `DeepSeek lang:zh,en` | 将结果限制在指定语言，多种语言用逗号分隔 | | `after:` | `DeepSeek after:2025` 或 `DeepSeek after:2025-01-01` | 将结果限制在指定日期之后发布的网页 | | `before:` | `DeepSeek before:2026` 或 `DeepSeek before:2026-06-01` | 将结果限制在指定日期之前发布的网页 | ## 请求地址 `POST https://api.modelverse.cn/v1/web_search` ## 请求体 ## 响应 - **200** — - **default** — 错误响应（网关侧参数/鉴权错误或上游非 200，原样透传状态码与错误体）。上游错误使用 OpenAI 兼容格式，`param` 恒为 `null`。 上游常见错误： | HTTP 状态码 | 说明 | |---|---| | 400 | 请求体不合法，包括 JSON 格式错误或字段值无效（如 `count` 超出 1～50、`query` 为空白） | | 401 | API Key 缺失或无效 | | 408 | 读取请求体超时 | | 413 | 请求体超过大小限制 | | 429 | 触发频率限制 | | 500 | 服务器内部错误 | | 504 | 下游请求超时 | 遇到 408、429 或 5xx 时请等待后重试；其它 4xx 错误如不修改请求，请勿重试。 ## OpenAPI 定义 ```json { "openapi": "3.1.0", "x-language": "zh-CN", "info": { "title": "DeepSeek 网页搜索接口文档", "version": "1.0.0", "description": "这是 ModelVerse 上 **DeepSeek 网页搜索** 模型的接口文档。该能力由 DeepSeek 自研搜索引擎提供支持。\n统一入口 `POST /v1/web_search`，通过请求体中的 `model` 字段选路（转发前被剥离）。\n其余字段为 DeepSeek Search 原生参数，**原样透传、原样返回，不做归一化**。响应为非流式，一次性返回 JSON。\n计费：按次计费，HTTP 200 且 `results` 非空计 1 次；请求失败、搜索无结果（`results` 为空数组）或超时不计费。`count` 只控制返回条数，不影响单次价格。\n" }, "servers": [ { "url": "https://api.modelverse.cn", "description": "ModelVerse API endpoint." } ], "tags": [ { "name": "Web Search", "description": "DeepSeek 网页搜索。" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/web_search": { "post": { "tags": [ "Web Search" ], "operationId": "createDeepseekToolsSearch", "summary": "DeepSeek 网页搜索", "description": "按 query 搜索网页，返回结构化的结果列表。`model` 固定为 `deepseek-tools-search`，仅用于平台选路，转发前被剥离；其余字段原样透传给上游。\n\n`query` 支持以下搜索语法，可在一个 query 中组合多个操作符，语法会原样传递给搜索服务：\n\n| 操作符 | 示例 | 说明 |\n|---|---|---|\n| `site:` | `DeepSeek site:github.com` | 将结果限制在指定站点，指定多个时用空格分隔并通过 `OR` 连接，例如 `DeepSeek site:github.com OR site:huggingface.co` |\n| `-site:` | `DeepSeek -site:example.com` | 排除指定站点，指定多个时用空格分隔 |\n| `-` | `DeepSeek -广告` | 排除包含指定关键词的网页，指定多个时用空格分隔 |\n| `-\"...\"` | `DeepSeek -\"release notes\"` | 排除包含指定短语的网页，短语内可以包含空格，指定多个时用空格分隔 |\n| `\"...\"` | `DeepSeek \"精确短语\"` | 精确匹配指定短语，指定多个时用空格分隔 |\n| `lang:` | `DeepSeek lang:zh,en` | 将结果限制在指定语言，多种语言用逗号分隔 |\n| `after:` | `DeepSeek after:2025` 或 `DeepSeek after:2025-01-01` | 将结果限制在指定日期之后发布的网页 |\n| `before:` | `DeepSeek before:2026` 或 `DeepSeek before:2026-06-01` | 将结果限制在指定日期之前发布的网页 |\n", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepseekSearchRequest" }, "examples": { "basic": { "summary": "基础搜索", "value": { "model": "deepseek-tools-search", "query": "DeepSeek V4 模型 发布", "count": 5 } }, "withContent": { "summary": "返回正文并携带原始问题", "value": { "model": "deepseek-tools-search", "query": "北京 周末 天气", "ori_question": "这周末北京适合出去玩吗？", "count": 3, "need_content": true } }, "syntax": { "summary": "组合搜索语法", "value": { "model": "deepseek-tools-search", "query": "DeepSeek 模型 site:github.com OR site:huggingface.co lang:zh after:2025", "count": 10 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepseekSearchResponse" }, "examples": { "success": { "summary": "成功响应", "value": { "results": [ { "rerank_score": 2.4, "title": "DeepSeek V4 模型发布", "url": "https://example.com/deepseek-v4", "snippet": "DeepSeek V4 已上线，支持工具调用与长上下文。", "summary": "DeepSeek 发布了 V4 模型。此次发布改进了工具调用与长上下文能力，适合 Agent 工作流。", "content": "DeepSeek V4 现已正式上线……", "site_name": "Example News", "site_icon": "https://example.com/favicon.ico", "date": "2026-06-01T00:00:00+00:00", "authority": 3 } ] } }, "empty": { "summary": "无匹配结果", "value": { "results": [] } } } } } }, "default": { "description": "错误响应（网关侧参数/鉴权错误或上游非 200，原样透传状态码与错误体）。上游错误使用 OpenAI 兼容格式，`param` 恒为 `null`。\n\n上游常见错误：\n\n| HTTP 状态码 | 说明 |\n|---|---|\n| 400 | 请求体不合法，包括 JSON 格式错误或字段值无效（如 `count` 超出 1～50、`query` 为空白） |\n| 401 | API Key 缺失或无效 |\n| 408 | 读取请求体超时 |\n| 413 | 请求体超过大小限制 |\n| 429 | 触发频率限制 |\n| 500 | 服务器内部错误 |\n| 504 | 下游请求超时 |\n\n遇到 408、429 或 5xx 时请等待后重试；其它 4xx 错误如不修改请求，请勿重试。\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeepseekErrorResponse" }, "examples": { "invalidCount": { "summary": "count 越界", "value": { "error": { "message": "'count' must be between 1 and 50", "type": "invalid_request_error", "param": null, "code": "invalid_request_error" } } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "平台下发的 API Key，通过 `Authorization: Bearer ` 传入。" } }, "schemas": { "DeepseekSearchRequest": { "type": "object", "additionalProperties": true, "description": "请求体中的未知字段会被上游忽略。", "required": [ "model", "query" ], "properties": { "model": { "type": "string", "const": "deepseek-tools-search", "description": "模型选路标识，固定为 `deepseek-tools-search`，转发前被剥离。" }, "query": { "type": "string", "minLength": 1, "maxLength": 128, "description": "搜索词，1～128 个 Unicode 字符，不能全为空白。支持 `site:`、`-site:`、引号等搜索语法。" }, "count": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "返回条数，1～50，默认 10。" }, "ori_question": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128, "description": "触发搜索的用户原始问题，1～128 个字符。提供该字段有助于更好地理解搜索意图；传 `null` 视为未提供。" }, "localization": { "type": "string", "default": "", "description": "用于优先返回本地化搜索结果的 IP 地址，默认为空字符串。原样透传，网关不会自动填充客户端真实 IP。" }, "need_content": { "type": "boolean", "default": false, "description": "是否在 `content` 中返回网页正文。默认为 `false`；为 `false` 时，`content` 恒为空字符串。" } } }, "DeepseekSearchResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "description": "搜索结果；没有匹配结果时为空数组。", "items": { "$ref": "#/components/schemas/DeepseekSearchResult" } } } }, "DeepseekSearchResult": { "type": "object", "required": [ "rerank_score", "title", "url", "snippet", "summary", "content", "site_name", "site_icon", "date", "authority" ], "properties": { "rerank_score": { "type": "number", "format": "float", "minimum": 0, "maximum": 3, "description": "排序分数，0～3 分，综合考虑相关性、权威性、时效性等维度。大于等于 1.5 分为优质结果。" }, "title": { "type": "string", "description": "搜索结果标题。" }, "url": { "type": "string", "description": "搜索结果链接。" }, "snippet": { "type": "string", "description": "短摘要，与 query 相关，通常为 100～200 字符，适用于前端展现。" }, "summary": { "type": "string", "description": "长摘要，与 query 相关，通常为 600～800 字符，适用于给模型阅读。" }, "content": { "type": "string", "description": "网页正文。`need_content` 为 `false` 或正文缺失时为空字符串。" }, "site_name": { "type": [ "string", "null" ], "description": "站点名称；缺失时为 `null`。" }, "site_icon": { "type": [ "string", "null" ], "description": "站点图标 URL；缺失时为 `null`。" }, "date": { "type": [ "string", "null" ], "format": "date-time", "description": "发布时间，统一为 UTC 的 RFC 3339 格式；未知时为 `null`。", "examples": [ "2026-06-01T00:00:00+00:00" ] }, "authority": { "type": "integer", "minimum": -1, "maximum": 4, "description": "网页权威性，0～4（`-1` 表示未知）；大于等于 3 为极权威结果。" } } }, "DeepseekErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/DeepseekError" } } }, "DeepseekError": { "type": "object", "required": [ "message", "type", "code" ], "properties": { "message": { "type": "string", "description": "错误说明。" }, "type": { "type": "string", "description": "错误类型。", "examples": [ "invalid_request_error" ] }, "param": { "type": [ "string", "null" ], "description": "上游错误中恒为 `null`。" }, "code": { "type": "string", "description": "机器可读的错误码。", "examples": [ "invalid_request_error" ] } } } } } } ```