调用 DeepSearch API 的详细指南

使用 Python、Node.js 或 cURL 实现 Jina AI 的 DeepSearch 集成

主要要点

获取 API 密钥是调用 DeepSearch API 的第一步。
支持多种编程语言，包括 Python 和 Node.js，以及使用 cURL 的命令行方式。
正确配置请求头和请求体对于成功调用 API 至关重要。

获取 API 密钥

要调用 Jina AI 的 DeepSearch API，首先需要获取一个有效的 API 密钥。以下是获取 API 密钥的步骤：

注册与申请

访问 Jina AI 的官方网站并注册一个账户。如果您已经拥有账户，可以直接登录。登录后，导航到开发者控制台或 API 管理页面，按照指引生成新的 API 密钥。

保存与安全

生成 API 密钥后，请妥善保存。避免在公共代码库或不安全的地方暴露 API 密钥，以防止未经授权的访问和滥用。

权限与限制

根据您的账户类型和订阅计划，不同的 API 密钥可能拥有不同的权限和调用限制。请确保了解您的 API 密钥的使用范围和限制，以避免超出配额或权限不足的问题。

安装必要的库

不同的编程语言调用 API 需要相应的库支持。以下是常用语言的安装说明：

Python 环境下安装 `requests` 库

使用 Python 调用 DeepSearch API，推荐使用 requests 库进行 HTTP 请求。安装方法如下：

pip install requests

Node.js 环境下安装 `axios` 库

在 Node.js 环境中，axios 是一个流行的 HTTP 客户端库。安装方法如下：

npm install axios

cURL 安装与配置

cURL 是一个命令行工具，用于发送 HTTP 请求，通常预装在大多数操作系统中。如果尚未安装，可以参考以下链接进行安装：

cURL 官方下载页面

安装后，可以在终端或命令提示符中直接使用 cURL 命令。

调用 DeepSearch API 的示例

以下提供了在 Python、Node.js 和使用 cURL 的示例代码，帮助您快速开始调用 DeepSearch API。

使用 Python 调用 DeepSearch API

以下是一个使用 Python 和 requests 库调用 DeepSearch API 的详细示例：

import requests

# 设置 API Key 和 API URL
API_KEY = "your_api_key_here"
API_URL = "https://deepsearch.jina.ai/v1/chat/completions"

# 设置请求头
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 设置请求体
data = {
    "model": "deepsearch-chat",  # 模型名称，根据实际情况调整
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你好，能帮我介绍一下 DeepSearch 吗？"}
    ],
    "max_tokens": 150,
    "temperature": 0.7,
    "stream": False
}

# 发送 POST 请求
response = requests.post(API_URL, headers=headers, json=data)

# 处理响应
if response.status_code == 200:
    response_data = response.json()
    assistant_reply = response_data.get("choices", [])[0].get("message", {}).get("content", "")
    print("助手回复:", assistant_reply)
else:
    print(f"请求失败，状态码：{response.status_code}")
    print("错误信息:", response.text)

此示例代码执行以下步骤：

设置 API 密钥和 API 端点 URL。
构建请求头，包括认证信息和内容类型。
构建请求体，包含模型名称、消息数组以及其他参数。
发送 POST 请求并处理响应，提取助手的回复内容。

使用 Node.js 调用 DeepSearch API

以下是一个使用 Node.js 和 axios 库调用 DeepSearch API 的详细示例：

const axios = require('axios');

// 设置 API Key 和 API URL
const API_KEY = 'your_api_key_here';
const API_URL = 'https://deepsearch.jina.ai/v1/chat/completions';

// 设置请求体
const requestBody = {
  model: "deepsearch-chat", // 模型名称，根据实际情况调整
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "你好，请介绍一下 DeepSearch 的功能。" }
  ],
  max_tokens: 150,
  temperature: 0.7,
  stream: false
};

// 设置请求头
const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${API_KEY}`
};

// 调用 API
axios.post(API_URL, requestBody, { headers })
  .then(response => {
    const assistantReply = response.data.choices[0].message.content;
    console.log('助手回复:', assistantReply);
  })
  .catch(error => {
    if (error.response) {
      console.error('请求失败，状态码：', error.response.status);
      console.error('错误信息：', error.response.data);
    } else {
      console.error('调用 DeepSearch API 出现错误:', error.message);
    }
  });

此示例代码执行以下步骤：

引入 axios 库以支持 HTTP 请求。
设置 API 密钥和 API 端点 URL。
构建请求体，包含模型名称、消息数组及其他参数。
设置请求头，包括认证信息和内容类型。
发送 POST 请求，并在成功响应时提取助手的回复内容。
处理可能的错误，输出错误信息以便调试。

使用 cURL 调用 DeepSearch API

如果您更倾向于使用命令行工具，可以使用 cURL 来调用 DeepSearch API。以下是一个详细的示例：

curl https://deepsearch.jina.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_here" \
  -d '{
        "model": "deepsearch-chat",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "你好！"}
        ],
        "max_tokens": 150,
        "temperature": 0.7,
        "stream": false
      }'

此命令执行以下操作：

指定 API 端点 URL。
设置请求头，包括内容类型和授权信息。
通过 -d 参数传递请求体，包含模型名称、消息数组及其他参数。

高级功能与参数

DeepSearch API 提供了一些高级功能和额外参数，以便用户根据需求自定义请求：

max_tokens

指定生成回复的最大标记数。更高的值可能生成更长的回复，但也会增加响应时间。

temperature

控制生成文本的随机性。较高的值（如 0.8）会使输出更加多样化，较低的值（如 0.2）则会使输出更集中和确定。

stream

设置为 true 时，API 将以流的方式返回响应，适用于需要实时响应的应用场景。

实例扩展：处理流式响应

如果启用了流式响应，您可以逐步接收和处理数据。以下是一个 Python 示例，展示如何处理流式响应：

import requests

API_KEY = "your_api_key_here"
API_URL = "https://deepsearch.jina.ai/v1/chat/completions"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

data = {
    "model": "deepsearch-chat",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "请实时显示回复内容。"}
    ],
    "stream": True
}

# 发送 POST 请求并处理流式响应
with requests.post(API_URL, headers=headers, json=data, stream=True) as response:
    if response.status_code == 200:
        for line in response.iter_lines():
            if line:
                decoded_line = line.decode('utf-8')
                print("助手部分回复:", decoded_line)
    else:
        print(f"请求失败，状态码：{response.status_code}")
        print("错误信息:", response.text)

该示例通过设置 stream 参数为 true，实现逐步接收助手的回复。

请求参数详解

为了更好地理解和使用 DeepSearch API，下面详细介绍主要的请求参数：

参数	类型	描述	默认值
`model`	string	指定调用的模型名称，例如 "deepsearch-chat"	—
`messages`	array	对话消息数组，每条消息包含角色和内容。例如，{"role": "user", "content": "你好"}	—
`max_tokens`	integer	生成回复的最大标记数	150
`temperature`	float	控制生成文本的随机性，范围通常为 0.0 到 1.0	0.7
`stream`	boolean	是否启用流式响应模式	false

详细参数说明

model

此参数指定了要使用的预训练模型。根据 Jina AI 的文档，确保使用有效的模型名称，以避免请求失败。

messages

这是一个消息数组，定义了对话的上下文。每条消息应包含 role（如 "system"、"user" 或 "assistant"）和 content。首次对话通常由系统消息设置助手的行为。

max_tokens

控制 API 生成回复的长度。较高的值允许生成更长的文本，但会消耗更多的资源。

temperature

调节生成文本的创造性和随机性。较高的温度值（如 0.8）会使输出更具多样性，而较低的值（如 0.2）则使输出更精确和可预测。

stream

启用后，API 将以流式方式返回生成的文本，适用于需要实时显示输出的应用场景。

错误处理与调试

在调用 DeepSearch API 过程中，可能会遇到各种错误。以下是常见错误类型及其处理方法：

认证错误

如果提供的 API 密钥无效或缺失，API 会返回 401 Unauthorized 错误。确保 API 密钥正确，并包含在请求头中。

请求参数错误

如果请求体中缺少必需的参数或参数格式不正确，API 会返回 400 Bad Request 错误。请检查所有参数是否正确设置，并参考官方文档确认参数要求。

速率限制

如果在短时间内发出过多请求，API 可能会返回 429 Too Many Requests 错误。请了解您的订阅计划的速率限制，并在应用中实现适当的速率控制。

服务器错误

当 API 端出现内部错误时，会返回 500 Internal Server Error 或 503 Service Unavailable 错误。此时应稍后重试请求，并联系 Jina AI 支持团队获取帮助。

调试建议

仔细阅读错误响应中的信息，以了解具体问题所在。
使用日志记录工具记录请求和响应，帮助定位问题。
参考官方文档和示例代码，确保请求格式和参数设置正确。
在调试过程中，尝试简化请求，仅使用必要参数，逐步添加其他参数以发现问题。

最佳实践与安全建议

为了确保在使用 DeepSearch API 时的效率和安全性，以下是一些最佳实践和安全建议：

保护 API 密钥

绝不在客户端代码中直接暴露 API 密钥，特别是在前端应用中。
使用环境变量或安全存储服务来管理 API 密钥。
定期更换 API 密钥，尤其是在密钥可能泄露的情况下。

优化请求设置

根据应用需求调整 max_tokens 和 temperature 参数，平衡回复质量和资源消耗。
使用流式响应模式时，确保应用能够处理分段数据并实时显示。
合理使用速率控制策略，避免触发 API 的速率限制。

监控与日志记录

实现详细的日志记录，记录每次 API 调用的请求和响应。
监控 API 使用情况，了解调用频率和资源消耗。
设置警报系统，当检测到异常调用或错误率上升时及时响应。

遵循官方文档

定期查阅 Jina AI 的官方 API 文档，了解最新的更新和变更。
参考官方提供的示例代码，确保最佳实践的应用。
参加 Jina AI 社区讨论，获取支持和分享经验。

实例扩展：集成到 Web 应用中

将 DeepSearch API 集成到实际的 Web 应用中，可以实现丰富的交互功能。以下是一个使用 Flask（Python Web 框架）集成 DeepSearch API 的基本示例：

Flask 应用示例

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

API_KEY = "your_api_key_here"
API_URL = "https://deepsearch.jina.ai/v1/chat/completions"

@app.route('/chat', methods=['POST'])
def chat():
    user_message = request.json.get('message')
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "model": "deepsearch-chat",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": user_message}
        ],
        "max_tokens": 150,
        "temperature": 0.7,
        "stream": False
    }
    response = requests.post(API_URL, headers=headers, json=data)
    if response.status_code == 200:
        assistant_reply = response.json().get("choices", [])[0].get("message", {}).get("content", "")
        return jsonify({"reply": assistant_reply})
    else:
        return jsonify({"error": "请求失败", "status_code": response.status_code, "message": response.text}), response.status_code

if __name__ == '__main__':
    app.run(debug=True)

此示例展示了如何创建一个简单的 Flask 应用，通过一个 POST 端点接收用户消息，并调用 DeepSearch API 返回助手的回复。

前端集成

您可以在前端使用 JavaScript 发送 AJAX 请求到上述 Flask 端点，实现实时聊天功能。以下是一个简单的前端示例：

<!DOCTYPE html>
<html lang="zh">
<head>
    <meta charset="UTF-8">
    <title>DeepSearch 聊天应用</title>
</head>
<body>
    <h1>与 DeepSearch 助手聊天</h1>
    <textarea id="userInput" rows="4" cols="50" placeholder="输入您的消息..."></textarea><br>
    <button onclick="sendMessage()">发送</button>
    <h2>助手回复:</h2>
    <div id="assistantReply"></div>

    <script>
        function sendMessage() {
            const userMessage = document.getElementById('userInput').value;
            fetch('/chat', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({ message: userMessage }),
            })
            .then(response => response.json())
            .then(data => {
                if (data.reply) {
                    document.getElementById('assistantReply').innerText = data.reply;
                } else {
                    document.getElementById('assistantReply').innerText = '发生错误: ' + data.error;
                }
            })
            .catch((error) => {
                document.getElementById('assistantReply').innerText = '错误: ' + error;
            });
        }
    </script>
</body>
</html>

此前端示例创建了一个简单的用户界面，允许用户输入消息并显示助手的回复。

常见问题及注意事项

API 端点确认

根据提供的信息，DeepSearch API 的端点地址为 https://deepsearch.jina.ai/v1/chat/completions。如果在使用过程中发现端点不可用，建议：

核实端点 URL 是否正确。
查阅 Jina AI 的最新官方文档，确认端点是否有更新或变更。
联系 Jina AI 的技术支持团队，获取最新的 API 访问信息。

API 版本管理

随着 API 的迭代，版本更新可能会带来不兼容的变化。建议在集成 API 时：

明确指定 API 版本，如有可能。
监控版本更新公告，及时调整集成代码。
在测试环境中先行验证新版本的兼容性。

处理多语言支持

DeepSearch API 支持多种语言输入和输出。使用时需确保编码正确，避免由于字符编码问题导致的错误。例如，发送中文消息时，确保请求体的字符编码为 UTF-8。

优化响应时间

为了提高应用的响应速度，可以考虑以下优化措施：

减少请求中的 max_tokens，适当缩短回复长度。
在客户端实现缓存策略，避免频繁重复请求。
使用更高效的网络连接，减少网络延迟。

多会话管理

在需要管理多个用户会话的应用场景中，应保持每个会话的上下文独立。可以在请求体的 messages 中逐步添加每个会话的消息，使助手能够理解对话的上下文。

结论

通过本文提供的详细指南，您可以轻松地调用 Jina AI 的 DeepSearch API，并将其集成到您的应用程序中。无论您使用的是 Python、Node.js 还是 cURL，理解和正确配置请求参数是成功调用 API 的关键。请确保保护好您的 API 密钥，遵循最佳实践，并参考官方文档以获取最新的信息和支持。通过合理的配置和优化，DeepSearch API 可以为您的应用带来强大的自然语言处理能力，提升用户体验和功能丰富度。

参考资料

api-docs.deepseek.com

DeepSeek API 官方文档（中文）

api-docs.deepseek.com

DeepSeek API 官方文档

github.com

Jina AI Node-DeepResearch 项目

Last updated February 15, 2025

调用 DeepSearch API 的详细指南

使用 Python、Node.js 或 cURL 实现 Jina AI 的 DeepSearch 集成

主要要点

获取 API 密钥

注册与申请

保存与安全

权限与限制

安装必要的库

Python 环境下安装 requests 库

Node.js 环境下安装 axios 库

cURL 安装与配置

调用 DeepSearch API 的示例

使用 Python 调用 DeepSearch API

使用 Node.js 调用 DeepSearch API

使用 cURL 调用 DeepSearch API

高级功能与参数

max_tokens

temperature

stream

实例扩展：处理流式响应

请求参数详解

详细参数说明

model

messages

max_tokens

temperature

stream

错误处理与调试

认证错误

请求参数错误

速率限制

服务器错误

调试建议

最佳实践与安全建议

保护 API 密钥

优化请求设置

监控与日志记录

遵循官方文档

实例扩展：集成到 Web 应用中

Flask 应用示例

前端集成

常见问题及注意事项

API 端点确认

API 版本管理

处理多语言支持

优化响应时间

多会话管理

结论

参考资料

Python 环境下安装 `requests` 库

Node.js 环境下安装 `axios` 库