gpt3_rs/api/completions.rs
1//! Create completions for a prompt
2//! # Builder
3//! Use the [`completions::Builder`][struct@Builder] to construct a [`completions::Request`][Request] struct
4use std::collections::HashMap;
5
6use derive_builder::Builder;
7use serde::{Deserialize, Serialize};
8
9use crate::{into_vec::IntoVec, model::Model};
10
11use super::{LogProbs, RequestInfo};
12/// Create completions for a prompt
13///
14/// # OpenAi documentation
15/// Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position.
16/// # Example
17/// ```ignore
18/// let request = completions::Builder::default()
19/// .model(Model::Curie)
20/// .prompt(&["Say this is a test"])
21/// .max_tokens(5)
22/// .temperature(1.0)
23/// .top_p(1.0)
24/// .n(1)
25/// .stop(&["\n"])
26/// .build()
27/// .unwrap();
28/// ```
29/// # Required
30/// ```ignore
31/// model
32/// ```
33#[derive(Debug, Clone, PartialEq, Serialize, Builder)]
34#[builder_struct_attr(doc = "# Required")]
35#[builder_struct_attr(doc = "[`model`][Self::model()]")]
36#[builder_struct_attr(doc = "")]
37#[builder(name = "Builder")]
38pub struct Request {
39 #[serde(skip_serializing)]
40 pub model: Model,
41 /// The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays.
42 /// Note that <|endoftext|> is the document separator that the model sees during training,
43 /// so if a prompt is not specified the model will generate as if from the beginning of a new document.
44 #[builder(default, setter(strip_option, into))]
45 #[serde(skip_serializing_if = "Option::is_none")]
46 pub prompt: Option<IntoVec<String>>,
47 /// The suffix that comes after a completion of inserted text.
48 #[builder(default, setter(strip_option, into))]
49 #[serde(skip_serializing_if = "Option::is_none")]
50 pub suffix: Option<String>,
51 /// The maximum number of tokens to generate in the completion.
52 /// The token count of your prompt plus max_tokens cannot exceed the model's context length.
53 /// Most models have a context length of 2048 tokens (except for the newest models, which support 4096).
54 /// # Default
55 /// Defaults to 16
56 #[builder(default, setter(strip_option))]
57 #[serde(skip_serializing_if = "Option::is_none")]
58 pub max_tokens: Option<u64>,
59 /// What sampling temperature to use. Higher values means the model will take more risks.
60 /// Try 0.9 for more creative applications, and 0 (argmax sampling) for ones with a well-defined answer.
61 /// We generally recommend altering this or top_p but not both.
62 /// # Default
63 /// Defaults to 1.0
64 #[builder(default, setter(strip_option))]
65 #[serde(skip_serializing_if = "Option::is_none")]
66 pub temperature: Option<f64>,
67 /// An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.
68 /// So 0.1 means only the tokens comprising the top 10% probability mass are considered.
69 /// We generally recommend altering this or temperature but not both.
70 /// # Default
71 /// Defaults to 1.0
72 #[builder(default, setter(strip_option))]
73 #[serde(skip_serializing_if = "Option::is_none")]
74 pub top_p: Option<f64>,
75 /// How many completions to generate for each prompt.
76 /// Note: Because this parameter generates many completions, it can quickly consume your token quota.
77 /// Use carefully and ensure that you have reasonable settings for max_tokens and stop.
78 /// # Default
79 /// Defaults to 1
80 #[builder(default, setter(strip_option))]
81 #[serde(skip_serializing_if = "Option::is_none")]
82 pub n: Option<i64>,
83 /// Whether to stream back partial progress.
84 /// If set, tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: [DONE] message.
85 /// # Default
86 /// Defaults to false
87 #[builder(default, setter(strip_option))]
88 #[serde(skip_serializing_if = "Option::is_none")]
89 pub stream: Option<bool>,
90 /// Include the log probabilities on the logprobs most likely tokens, as well the chosen tokens.
91 /// For example, if logprobs is 5, the API will return a list of the 5 most likely tokens.
92 /// The API will always return the logprob of the sampled token, so there may be up to logprobs+1 elements in the response.
93 /// The maximum value for logprobs is 5. If you need more than this, please contact support@openai.com and describe your use case.
94 /// # Default
95 /// Defaults to none
96 #[builder(default, setter(strip_option))]
97 pub logprobs: Option<u8>,
98 /// Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
99 #[builder(default, setter(strip_option, into))]
100 #[serde(skip_serializing_if = "Option::is_none")]
101 pub stop: Option<IntoVec<String>>,
102 /// Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
103 ///
104 /// [See more information about frequency and presence penalties](https://beta.openai.com/docs/api-reference/parameter-details)
105 #[builder(default, setter(strip_option))]
106 #[serde(skip_serializing_if = "Option::is_none")]
107 pub presence_penalty: Option<f64>,
108 /// Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
109 ///
110 /// [See more information about frequency and presence penalties](https://beta.openai.com/docs/api-reference/parameter-details)
111 #[builder(default, setter(strip_option))]
112 #[serde(skip_serializing_if = "Option::is_none")]
113 pub frequency_penalty: Option<f64>,
114 /// Generates best_of completions server-side and returns the "best" (the one with the lowest log probability per token). Results cannot be streamed.
115 /// When used with n, best_of controls the number of candidate completions and n specifies how many to return – best_of must be greater than n.
116 /// Note: Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for max_tokens and stop.
117 #[builder(default, setter(strip_option))]
118 #[serde(skip_serializing_if = "Option::is_none")]
119 pub best_of: Option<u8>,
120 /// Modify the likelihood of specified tokens appearing in the completion.
121 /// Accepts a json object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100.
122 /// You can use this tokenizer tool (which works for both GPT-2 and GPT-3) to convert text to token IDs.
123 /// Mathematically, the bias is added to the logits generated by the model prior to sampling.
124 /// The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection;
125 /// values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
126 /// As an example, you can pass {"50256": -100} to prevent the <|endoftext|> token from being generated.
127 #[builder(default, setter(strip_option))]
128 #[serde(skip_serializing_if = "Option::is_none")]
129 pub logit_bias: Option<HashMap<String, i8>>,
130 /// A unique identifier representing your end-user, which will help OpenAI to monitor and detect abuse.
131 #[builder(default, setter(strip_option, into))]
132 #[serde(skip_serializing_if = "Option::is_none")]
133 pub user: Option<String>,
134}
135/// A response corresponding to a [`Request`]
136#[derive(Default, Debug, Clone, PartialEq, Serialize, Deserialize)]
137pub struct Response {
138 /// completion id
139 pub id: String,
140 /// The requested action
141 pub object: String,
142 /// The creation Time of the request
143 pub created: u64,
144 /// The model used to create the completion
145 pub model: String,
146 /// The answers created by this request
147 pub choices: Vec<Choice>,
148}
149
150#[derive(Default, Debug, Clone, PartialEq, Serialize, Deserialize)]
151pub struct Choice {
152 /// The text generated by the model
153 pub text: String,
154 /// The index of this choice
155 pub index: usize,
156 /// A list of the n most likely tokens
157 pub logprobs: Option<LogProbs>,
158 /// reason why the model finished
159 pub finish_reason: String,
160}
161
162impl RequestInfo for Request {
163 fn url(&self) -> String {
164 self.model.url("/completions")
165 }
166}
167#[cfg_attr(not(feature = "blocking"), async_trait::async_trait)]
168impl crate::client::Request for Request {
169 type Response = Response;
170}