OpenAI常用接口completions浅析

发表于 更新于 分类于 阅读次数：

在OpenAI的API中，/completions 是一个极为重要的端点，它为开发者提供了强大的文本生成能力。以下将从多个方面对其进行详细介绍，包括重要性、JavaScript调用代码实例、返回结构体实例和注释以及异常捕捉等。

/completions 的重要性

  • 基础且强大的文本生成功能：/completions 是OpenAI最基础的模型接口之一，它允许开发者输入一个文本提示，然后模型会根据这个提示生成相应的文本补全内容。从简单的文本续写，到复杂的文章创作、问题回答等任务，它都能胜任。其灵活性和强大性在于，通过调整输入的提示和各种参数，可以控制生成文本的风格、长度、主题等多个方面，以满足不同应用场景的需求。
  • 广泛的应用场景：在自然语言处理领域，该接口有着广泛的应用。例如，在内容创作方面，它可以帮助作家、编辑快速生成文章的大纲、段落，甚至完整的作品；在智能客服中，能够根据用户的问题生成准确的回答；在教育领域，可用于辅助教学，如生成练习题的答案、解释知识点等。它为各种基于文本生成的应用提供了核心动力，推动了人工智能在不同行业的应用和发展。
  • 定制化和可配置性：/completions 接口提供了丰富的参数，允许开发者对生成过程进行精细的控制。例如，通过调整 temperature 参数，可以控制生成内容的随机性，数值越高，生成的文本越多样化、富有创意，但也可能更偏离预期；而数值越低，生成的文本就越保守、准确，更符合常见的语言模式。max_tokens 参数则限制了生成文本的最大长度，避免生成过长或过短的内容，以满足具体应用的需求。

JavaScript调用代码实例

本文通过JavaScript对OpenAI的接口进行一个基础的讲解。在JavaScript中，可以使用 fetch 函数来调用OpenAI的 /completions 接口。以下是一个基本的示例：

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
// 获取OpenAI API Key（请确保此密钥安全）
const apiKey = 'your_openai_api_key';
const url = 'https://api.openai.com/v1/completions';

// 定义请求体
const requestBody = {
    model: "text-davinci-003", // 可以替换为其他合适的模型
    prompt: "请描述一下人工智能在医疗领域的应用。",
    temperature: 0.7, // 控制生成内容的随机性，范围0-1
    max_tokens: 150 // 控制生成内容的最大长度
};

// 发送请求到OpenAI API
fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify(requestBody)
})
.then(response => response.json())
.then(data => {
    console.log(data.choices[0].text); // 输出生成的内容
})
.catch(error => {
    console.error('Error:', error);
});

上述代码首先定义了API密钥和请求的URL，然后构建了一个包含模型名称、提示文本、温度和最大令牌数等参数的请求体。通过 fetch 函数发送POST请求到OpenAI的 /completions 接口，成功响应后，从返回的数据中提取并打印出生成的文本内容。如果发生错误，会在控制台打印出错误信息。

返回结构体实例和注释

当成功调用 /completions 接口后，OpenAI会返回一个JSON格式的数据结构，以下是一个示例及对其各字段的注释：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "choices": [
        {
            "text": "\n\n人工智能在医疗领域有诸多应用。它可以辅助医生进行疾病诊断，通过分析大量的医疗影像数据，如X光、CT等，帮助发现潜在的病变。还能用于药物研发，加速新药的发现和开发过程，预测药物的疗效和副作用。此外，人工智能也可用于医疗机器人，协助手术操作，提高手术的精度和安全性。",
            "index": 0,
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "created": 1681234567,
    "model": "text-davinci-003",
    "object": "text_completion",
    "usage": {
        "prompt_tokens": 10,
        "completion_tokens": 120,
        "total_tokens": 130
    }
}
  • choices：是一个数组，包含了模型生成的多个候选结果。通常情况下，默认只生成一个结果，所以数组中只有一个元素。如果在调用时设置了 n 参数，会生成多个候选结果。
    • text：生成的文本内容，这是最重要的字段，包含了模型根据提示生成的具体信息。
    • index：表示该选择在 choices 数组中的索引，通常为0。
    • logprobs：包含与生成文本相关的对数概率信息，一般用于更高级的分析和调试，通常为 null，除非在请求中明确指定了需要返回该信息。
    • finish_reason：表示生成结束的原因，"stop" 表示达到了停止条件，正常结束；"length" 表示达到了最大令牌数限制，生成被截断；"content_filter" 表示生成的内容被内容过滤器拦截；"null" 表示生成过程因其他原因提前结束。
  • created：一个时间戳，表示生成该结果的时间。
  • model：显示使用的模型名称，这里是 "text-davinci-003"。
  • object：表示返回对象的类型，这里是 "text_completion"，表示这是一个文本补全结果。
  • usage：包含了关于令牌使用情况的信息。
    • prompt_tokens：表示用于生成补全的提示中使用的令牌数量。
    • completion_tokens：表示生成的补全文本中使用的令牌数量。
    • total_tokens：提示令牌数和补全令牌数的总和，即本次请求总共使用的令牌数量，这是OpenAI进行计费的依据。

异常捕捉

在调用OpenAI的 /completions 接口时，可能会出现各种错误情况，需要进行适当的异常捕捉和处理，以提高应用的稳定性和可靠性。以下是一些常见的异常情况及处理方式：

  • 网络连接问题：可能由于网络不稳定、服务器故障等原因导致请求无法成功发送或接收响应。可以使用 try...catch 语句来捕捉 fetch 操作中的错误，并给出相应的提示信息。例如：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
try {
    const response = await fetch(url, {
        method: 'POST',
        headers: {
            'Content - Type': 'application/json',
            'Authorization': `Bearer ${apiKey}`
        },
        body: JSON.stringify(requestBody)
    });
    if (!response.ok) {
        throw new Error('网络连接问题，请检查网络设置并确保OpenAI服务器正常运行。');
    }
    const data = await response.json();
    console.log(data.choices[0].text);
} catch (error) {
    console.error('Error:', error.message);
}
  • API请求错误：如果请求的参数不正确、模型不存在或API密钥无效等，OpenAI会返回相应的错误信息。可以通过检查响应的状态码和错误信息来进行处理。例如：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
try {
    const response = await fetch(url, {
        method: 'POST',
        headers: {
            'Content - Type': 'application/json',
            'Authorization': `Bearer ${apiKey}`
        },
        body: JSON.stringify(requestBody)
    });
    if (!response.ok) {
        const errorData = await response.json();
        throw new Error(`API请求错误：${errorData.error.message}`);
    }
    const data = await response.json();
    console.log(data.choices[0].text);
} catch (error) {
    console.error('Error:', error.message);
}
  • 其他未知错误：对于其他可能出现的未知错误，可以使用通用的 catch 块来捕捉，并记录错误信息，以便后续进行排查和处理。例如：
1
2
3
4
5
6
try {
    // 执行API调用操作
} catch (error) {
    console.error('发生未知错误：', error);
    // 可以将错误信息发送到服务器进行日志记录，以便后续分析
}

通过以上的异常捕捉和处理机制，可以让应用在面对各种可能出现的错误情况时，能够更优雅地应对，提供更好的用户体验，并帮助开发者快速定位和解决问题。

OpenAI的 /completions 接口是一个功能强大且灵活的文本生成工具，通过JavaScript可以方便地进行调用。了解其返回结构体的各个字段以及如何进行异常捕捉，对于开发者来说是非常重要的，可以帮助他们更好地利用这个接口来构建各种智能应用，实现自然语言处理任务的自动化和智能化。同时，开发者在使用过程中要注意合理设置参数，根据实际需求调整生成策略，并妥善处理各种异常情况，以确保应用的稳定运行和高质量的输出。