ds_api/raw/
mod.rs

1//! 原始 API 数据结构模块
2//!
3//! 提供与 DeepSeek API 直接对应的原始数据结构，这些结构体直接映射到 API 的 JSON 格式。
4//! 这个模块适合需要直接控制 API 请求和响应的用户。
5//!
6//! # 模块结构
7//!
8//! - [`request`]
9//! - [`response`]
10//!
11//! # 主要类型
12//!
13//! ## 请求类型
14//!
15//! - [`ChatCompletionRequest`]
16//! - [`Message`]
17//! - [`Model`]
18//! - [`Tool`]
19//! - [`ResponseFormat`]
20//! - [`Thinking`]
21//! - [`Stop`]
22//! - [`StreamOptions`]
23//!
24//! ## 响应类型
25//!
26//! - [`ChatCompletionResponse`]
27//! - [`ChatCompletionChunk`]
28//! - [`Choice`]
29//! - [`Usage`]
30//!
31//! # 使用场景
32//!
33//! 使用原始数据结构适合以下场景：
34//!
35//! 1. **需要完全控制 API 请求**：直接设置所有字段
36//! 2. **高级功能使用**：如工具调用、推理模式等
37//! 3. **性能优化**：避免构建器的开销
38//! 4. **与现有代码集成**：直接使用 serde 序列化/反序列化
39//!
40//! # 示例
41//!
42//! ## 基本使用
43//!
44//! ```rust
45//! use ds_api::raw::{ChatCompletionRequest, Message, Model, Role};
46//! use serde_json::json;
47//!
48//! fn main() {
49//!     // 示例 1: 基本聊天补全请求
50//!     let basic_request = ChatCompletionRequest {
51//!         messages: vec![
52//!             Message::new(Role::System, "You are a helpful assistant."),
53//!             Message::new(Role::User, "What is the capital of France?"),
54//!         ],
55//!         model: Model::DeepseekChat,
56//!         max_tokens: Some(100),
57//!         temperature: Some(0.7),
58//!         stream: Some(false),
59//!         ..Default::default()
60//!     };
61//!
62//!     println!("Basic request JSON:");
63//!     let json = serde_json::to_string_pretty(&basic_request).unwrap();
64//!     println!("{}\n", json);
65//!
66//!     // 示例 2: 带工具调用的请求
67//!     use ds_api::raw::{Tool, ToolChoice, ToolChoiceType, ToolType, Function};
68//!
69//!     let tool_request = ChatCompletionRequest {
70//!         messages: vec![Message::new(Role::User, "What's the weather like in Tokyo?")],
71//!         model: Model::DeepseekChat,
72//!         max_tokens: Some(200),
73//!         temperature: Some(0.8),
74//!         stream: Some(false),
75//!         tools: Some(vec![Tool {
76//!             r#type: ToolType::Function,
77//!             function: Function {
78//!                 name: "get_weather".to_string(),
79//!                 description: Some("Get the current weather for a location".to_string()),
80//!                 parameters: json!({
81//!                     "type": "object",
82//!                     "properties": {
83//!                         "location": {
84//!                             "type": "string",
85//!                             "description": "The city and country, e.g. Tokyo, Japan"
86//!                         }
87//!                     },
88//!                     "required": ["location"]
89//!                 }),
90//!                 strict: Some(true),
91//!             },
92//!         }]),
93//!         tool_choice: Some(ToolChoice::String(ToolChoiceType::Auto)),
94//!         ..Default::default()
95//!     };
96//!
97//!     println!("Tool request JSON:");
98//!     let json = serde_json::to_string_pretty(&tool_request).unwrap();
99//!     println!("{}\n", json);
100//!
101//!     // 示例 3: 使用 DeepSeek Reasoner 模型
102//!     use ds_api::raw::{Thinking, ThinkingType};
103//!
104//!     let reasoner_request = ChatCompletionRequest {
105//!         messages: vec![
106//!             Message::new(Role::System, "You are a helpful assistant that explains your reasoning."),
107//!             Message::new(Role::User, "Solve this math problem: What is 15% of 200?"),
108//!         ],
109//!         model: Model::DeepseekReasoner,
110//!         thinking: Some(Thinking {
111//!             r#type: ThinkingType::Enabled,
112//!         }),
113//!         max_tokens: Some(150),
114//!         temperature: Some(0.3),
115//!         stream: Some(false),
116//!         ..Default::default()
117//!     };
118//!
119//!     println!("Reasoner request JSON:");
120//!     let json = serde_json::to_string_pretty(&reasoner_request).unwrap();
121//!     println!("{}\n", json);
122//!
123//!     // 示例 4: JSON 模式响应格式
124//!     use ds_api::raw::{ResponseFormat, ResponseFormatType};
125//!
126//!     let json_request = ChatCompletionRequest {
127//!         messages: vec![
128//!             Message::new(Role::System, "You are a helpful assistant that always responds in valid JSON format."),
129//!             Message::new(Role::User, "Give me information about Paris in JSON format with fields: name, country, population, and landmarks."),
130//!         ],
131//!         model: Model::DeepseekChat,
132//!         max_tokens: Some(200),
133//!         temperature: Some(0.5),
134//!         stream: Some(false),
135//!         response_format: Some(ResponseFormat {
136//!             r#type: ResponseFormatType::JsonObject,
137//!         }),
138//!         ..Default::default()
139//!     };
140//!
141//!     println!("JSON mode request:");
142//!     let json = serde_json::to_string_pretty(&json_request).unwrap();
143//!     println!("{}\n", json);
144//! }
145//! ```
146//!
147//! # 序列化/反序列化
148//!
149//! 所有结构体都实现了 `Serialize` 和 `Deserialize` trait，可以直接使用 `serde_json` 进行序列化和反序列化：
150//!
151//! ```rust
152//! use ds_api::raw::{ChatCompletionRequest, Message, Model, Role};
153//!
154//! let request = ChatCompletionRequest {
155//!     messages: vec![Message::new(Role::User, "Hello")],
156//!     model: Model::DeepseekChat,
157//!     ..Default::default()
158//! };
159//! let json_string = serde_json::to_string(&request).unwrap();
160//! let parsed_request: ChatCompletionRequest = serde_json::from_str(&json_string).unwrap();
161//! ```
162//!
163//! # 与高级 API 的关系
164//!
165//! 高级 API（如 [`Request`](../request/struct.Request.html)）内部使用这些原始数据结构，
166//! 但提供了更友好的构建器接口和验证逻辑。如果你需要更简单的使用方式，请
167pub mod request;
168pub mod response;
169
170pub use request::*;
171pub use response::*;
ds_api/raw/mod.rs

ds_api/raw/
mod.rs
