deepseek_sdk/completion/
fim.rs

1//! FIM (Fill-In-the-Middle) completion models and request types.
2//!
3//! This endpoint is beta and requires the beta base URL:
4//! `https://api.deepseek.com/beta`.
5use std::collections::HashMap;
6use std::sync::mpsc as std_mpsc;
7
8use crate::chat::request::{Stop, StreamOptions, is_none_or_empty_stop};
9use crate::chat::response::ChatGeneric;
10use crate::error::DeepSeekError;
11use crate::{DeepSeekClient, api_request_stream};
12use crate::{DeepSeekRequest, api_post};
13use derive_builder::Builder;
14use futures_util::StreamExt;
15use reqwest::Method;
16use reqwest_eventsource::Event;
17use serde::{Deserialize, Serialize};
18use tokio::sync::mpsc;
19
20/// Non-streaming FIM completion response.
21pub type Completion = ChatGeneric<CompletionChoice>;
22
23/// FIM completion request payload.
24#[derive(Clone, Debug, PartialEq, Serialize, Builder)]
25#[builder(
26    pattern = "owned",
27    setter(into, strip_option),
28    build_fn(validate = "Self::validate"),
29    name = "FIMCompletionRequestBuilder"
30)]
31pub struct FIMCompletionRequest {
32    #[serde(skip_serializing)]
33    pub client: DeepSeekClient,
34
35    /// Possible values: \[`deepseek-v4-pro`\]
36    ///
37    /// ID of the model to use.
38    pub model: String,
39
40    /// The prompt to generate completions for.
41    pub prompt: String,
42
43    /// Echo back the prompt in addition to the completion
44    #[builder(default)]
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub echo: Option<bool>,
47
48    /// Possible values: `<= 20`
49    ///
50    /// Include the log probabilities on the `logprobs` most likely output tokens,
51    /// as well the chosen tokens. For example, if `logprobs` is 20, the API will return a list of the 20 most likely tokens.
52    /// The API will always return the logprob of the sampled token, so there may be up to `logprobs+1` elements in the response.
53    /// The maximum value for `logprobs` is 20.
54    #[builder(default)]
55    #[serde(skip_serializing_if = "Option::is_none")]
56    pub logprobs: Option<u32>,
57
58    /// The maximum number of tokens that can be generated in the completion.
59    #[builder(default)]
60    #[serde(skip_serializing_if = "Option::is_none")]
61    pub max_tokens: Option<u32>,
62
63    /// Up to 16 sequences where the API will stop generating further tokens.
64    /// The returned text will not contain the stop sequence.
65    #[builder(default)]
66    #[serde(skip_serializing_if = "is_none_or_empty_stop")]
67    pub stop: Option<Stop>,
68
69    /// Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent events as they become available,
70    /// with the stream terminated by a · message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions).
71    #[builder(default)]
72    #[serde(skip_serializing_if = "Option::is_none")]
73    pub stream: Option<bool>,
74
75    /// Options for streaming response. Only set this when you set `stream: true`.
76    #[builder(default)]
77    #[serde(skip_serializing_if = "Option::is_none")]
78    pub stream_options: Option<StreamOptions>,
79
80    /// The suffix that comes after a completion of inserted text.
81    #[builder(default)]
82    #[serde(skip_serializing_if = "Option::is_none")]
83    pub suffix: Option<String>,
84
85    /// Possible values: `<= 2`
86    ///
87    /// Default value: `1`
88    ///
89    /// What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random,
90    /// while lower values like 0.2 will make it more focused and deterministic.
91    /// We generally recommend altering this or `top_p` but not both.
92    #[builder(default)]
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub temperature: Option<f64>,
95
96    /// Possible values: `<= 1`
97    ///
98    /// Default value: `1`
99    ///
100    /// An alternative to sampling with temperature, called nucleus sampling,
101    /// where the model considers the results of the tokens with top_p probability mass.
102    /// So 0.1 means only the tokens comprising the top 10% probability mass are considered.
103    /// We generally recommend altering this or `temperature` but not both.
104    #[builder(default)]
105    #[serde(skip_serializing_if = "Option::is_none")]
106    pub top_p: Option<f64>,
107}
108
109impl FIMCompletionRequestBuilder {
110    fn validate(&self) -> Result<(), String> {
111        if let Some(temperature) = self.temperature.flatten()
112            && !(0.0..=2.0).contains(&temperature) {
113                return Err("temperature must be between 0 and 2".to_string());
114            }
115        if let Some(logprobs) = self.logprobs.flatten()
116            && logprobs > 20 {
117                return Err("logprobs must be <= 20".to_string());
118            }
119
120        if let Some(top_p) = self.top_p.flatten()
121            && !(0.0..=1.0).contains(&top_p) {
122                return Err("top_p must be between 0 and 1".to_string());
123            }
124
125        if let Some(stream) = self.stream.flatten()
126            && !stream && self.stream_options.is_some() {
127                return Err("stream_options cannot be set when stream is false".to_string());
128            }
129
130        if let Some(stop) = self.stop.as_ref().and_then(|s| s.as_ref())
131            && let Stop::Many(values) = stop
132                && values.len() > 16 {
133                    return Err("a maximum of 16 stop sequences are allowed".to_string());
134                }
135
136        Ok(())
137    }
138}
139
140/// Completion choice the model generated for the input prompt.
141#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
142pub struct CompletionChoice {
143    /// Possible values: [`stop`, `length`, `content_filter`, `insufficient_system_resource`]
144    ///
145    /// The reason the model stopped generating tokens.
146    /// This will be `stop` if the model hit a natural stop point or a provided stop sequence,
147    /// `length` if the maximum number of tokens specified in the request was reached,
148    /// `content_filter` if content was omitted due to a flag from our content filters,
149    /// or `insufficient_system_resource` if the request is interrupted due to insufficient resource of the inference system.
150    pub finish_reason: FinishReason,
151    pub index: u64,
152    pub text: String,
153    #[serde(skip_serializing_if = "Option::is_none")]
154    pub logprobs: Option<Logprobs>,
155}
156
157/// Completion finish reason.
158#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
159#[serde(rename_all = "snake_case")]
160pub enum FinishReason {
161    Stop,
162    Length,
163    ContentFilter,
164    InsufficientSystemResources,
165}
166
167/// Logprob details for completion tokens.
168#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
169pub struct Logprobs {
170    pub text_offset: Vec<u64>,
171    pub token_logprobs: Vec<f64>,
172    pub tokens: Vec<String>,
173    pub top_logprobs: Option<Vec<HashMap<String, f64>>>,
174}
175/// Streaming completion choice.
176#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
177pub struct CompletionChoiceStream {
178    pub finish_reason: Option<FinishReason>,
179    pub index: u64,
180    pub text: String,
181    #[serde(skip_serializing_if = "Option::is_none")]
182    pub logprobs: Option<Logprobs>,
183}
184/// Streaming FIM completion response (SSE chunks).
185pub type CompletionStream = ChatGeneric<CompletionChoiceStream>;
186/// Stream item produced by FIM completion streaming.
187pub type CompletionStreamItem = Result<CompletionStream, DeepSeekError>;
188/// Blocking iterator over FIM completion streaming chunks.
189pub struct CompletionStreamBlocking {
190    rx: std_mpsc::Receiver<CompletionStreamItem>,
191}
192
193impl Iterator for CompletionStreamBlocking {
194    type Item = CompletionStreamItem;
195
196    fn next(&mut self) -> Option<Self::Item> {
197        self.rx.recv().ok()
198    }
199}
200impl DeepSeekRequest for FIMCompletionRequest {
201    type Response = Completion;
202    type StreamItem = CompletionStreamItem;
203    type BlockingStream = CompletionStreamBlocking;
204
205    async fn send(self) -> Result<Self::Response, DeepSeekError> {
206        let client = self.client.clone();
207        api_post("/completions", &self, client).await
208    }
209
210    async fn stream(self) -> Result<mpsc::Receiver<Self::StreamItem>, DeepSeekError> {
211        let mut request = self;
212        request.stream = Some(true);
213
214        let client = request.client.clone();
215        let mut event_source = api_request_stream(
216            Method::POST,
217            "/completions",
218            |builder| builder.json(&request),
219            client,
220        )
221        .await?;
222
223        let (tx, rx) = mpsc::channel(32);
224
225        tokio::spawn(async move {
226            while let Some(event) = event_source.next().await {
227                match event {
228                    Ok(Event::Open) => {}
229                    Ok(Event::Message(message)) => {
230                        if message.data == "[DONE]" {
231                            break;
232                        }
233                        match serde_json::from_str::<CompletionStream>(&message.data) {
234                            Ok(chunk) => {
235                                if tx.send(Ok(chunk)).await.is_err() {
236                                    break;
237                                }
238                            }
239                            Err(err) => {
240                                let _ = tx
241                                    .send(Err(DeepSeekError::decode(err.to_string(), message.data)))
242                                    .await;
243                                break;
244                            }
245                        }
246                    }
247                    Err(err) => {
248                        let _ = tx
249                            .send(Err(DeepSeekError::decode(err.to_string(), String::new())))
250                            .await;
251                        break;
252                    }
253                }
254            }
255        });
256
257        Ok(rx)
258    }
259
260    fn stream_blocking(self) -> Result<CompletionStreamBlocking, DeepSeekError> {
261        let (tx, rx) = std_mpsc::channel();
262
263        std::thread::spawn(move || {
264            let runtime = match tokio::runtime::Builder::new_current_thread()
265                .enable_all()
266                .build()
267            {
268                Ok(runtime) => runtime,
269                Err(err) => {
270                    let _ = tx.send(Err(DeepSeekError::decode(err.to_string(), String::new())));
271                    return;
272                }
273            };
274
275            runtime.block_on(async move {
276                match self.stream().await {
277                    Ok(mut stream_rx) => {
278                        while let Some(item) = stream_rx.recv().await {
279                            if tx.send(item).is_err() {
280                                break;
281                            }
282                        }
283                    }
284                    Err(err) => {
285                        let _ = tx.send(Err(err));
286                    }
287                }
288            });
289        });
290
291        Ok(CompletionStreamBlocking { rx })
292    }
293}
294
295#[cfg(test)]
296mod tests {
297    use super::*;
298    use crate::DEFAULT_BETA_BASE_URL;
299
300    fn get_client() -> DeepSeekClient {
301        DeepSeekClient::new(
302            std::env::var("DEEPSEEK_API_KEY").expect("DEEPSEEK_API_KEY is not set"),
303            DEFAULT_BETA_BASE_URL.clone(),
304        )
305    }
306
307    fn get_fim_builder() -> FIMCompletionRequestBuilder {
308        FIMCompletionRequestBuilder::default()
309            .client(get_client())
310            .model("deepseek-v4-flash")
311            .max_tokens(64_u32)
312    }
313
314    #[tokio::test]
315    async fn test_fim_completion() {
316        let fim_request = get_fim_builder()
317            .prompt("def fib(a):")
318            .suffix("    return fib(a-1) + fib(a-2)")
319            .build()
320            .unwrap();
321        let response = fim_request.send().await.unwrap();
322        println!("{:#?}", response);
323        assert_eq!(response.object, "text_completion");
324        assert_eq!(response.model, "deepseek-v4-flash");
325        assert_eq!(response.choices.len(), 1);
326    }
327
328    #[tokio::test]
329    async fn test_fim_completion_stream() {
330        let fim_request = get_fim_builder()
331            .prompt("def fib(a):")
332            .suffix("    return fib(a-1) + fib(a-2)")
333            .stream(true)
334            .build()
335            .unwrap();
336        let mut stream = fim_request.stream().await.unwrap();
337        while let Some(item) = stream.recv().await {
338            match item {
339                Ok(chunk) => println!("Received chunk: {:#?}", chunk),
340                Err(err) => eprintln!("Stream error: {}", err),
341            }
342        }
343    }
344
345    #[tokio::test]
346    async fn test_fim_completion_stream_blocking() {
347        let fim_request = get_fim_builder()
348            .prompt("def fib(a):")
349            .suffix("    return fib(a-1) + fib(a-2)")
350            .stream(true)
351            .build()
352            .unwrap();
353        let stream = fim_request.stream_blocking().unwrap();
354        for item in stream {
355            match item {
356                Ok(chunk) => println!("Received chunk: {:#?}", chunk),
357                Err(err) => eprintln!("Stream error: {}", err),
358            }
359        }
360    }
361}
deepseek_sdk/completion/fim.rs

deepseek_sdk/completion/
fim.rs
