# 快速入门指南
本指南将帮助您快速上手 `zai-rs` - Zhipu AI 的 Rust SDK。
## 前置要求
- Rust 1.88+（edition 2024）
- 智谱AI API Key（从 [智谱AI开放平台](https://open.bigmodel.cn/) 获取）
## 安装
在 `Cargo.toml` 中添加依赖：
```toml
[dependencies]
zai-rs = "0.5"
```
## 配置
### 环境变量
SDK 默认从环境变量读取 API 密钥：
```bash
export ZHIPU_API_KEY="your-api-key-here"
```
### 高级配置
使用 `HttpTransportConfig` 配置统一传输层。配置只允许收紧 SDK 的安全上限：
```rust,ignore
use zai_rs::client::{HttpTransportConfig, ZaiClient};
use std::time::Duration;
let transport = HttpTransportConfig::builder()
.max_attempts(2)?
.request_timeout(Duration::from_secs(30))?
.build();
let client = ZaiClient::builder(std::env::var("ZHIPU_API_KEY")?)
.transport(transport)
.build()?;
```
### 日志配置
使用 `tracing` 进行结构化日志记录：
```rust,ignore
use tracing_subscriber;
fn init_logging() {
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::from_default_env()
.add_directive("zai_rs=debug")
)
.init();
}
```
## 基础用法
### 1. 聊天补全
最简单的文本聊天：
```rust,ignore
use zai_rs::{client::ZaiClient, model::*};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let model = GLM4_5_flash {};
let messages = TextMessage::user("你好，请介绍一下你自己");
let client = ZaiClient::from_env()?;
let request = ChatCompletion::new(model, messages);
let resp = request.send_via(&client).await?;
println!("{}", resp.choices().first().unwrap().message.content_str().unwrap_or_default());
Ok(())
}
```
### 2. 流式响应
对于实时响应，启用流式输出：
```rust,ignore
use zai_rs::{client::ZaiClient, model::*};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let model = GLM4_5_flash {};
let messages = TextMessage::user("讲一个短故事");
let client = ZaiClient::from_env()?;
// 0.5 当前请使用非流式统一传输路径；SSE 接口将在后续版本恢复。
let response = ChatCompletion::new(model, messages).send_via(&client).await?;
println!("{:?}", response);
Ok(())
}
```
### 3. 图像生成
```rust,ignore
use zai_rs::model::gen_image::*;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let model = CogView4 {};
let key = std::env::var("ZHIPU_API_KEY")?;
let client = ImageGenRequest::new(model, key).with_prompt("一只可爱的猫咪");
let resp: ImageResponse = client.send().await?;
println!("生成的图像: {:#?}", resp);
Ok(())
}
```
### 4. 语音转文字
```rust,ignore
use zai_rs::model::audio_to_text::{AudioToTextResponse, GlmAsr, *};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let model = GlmAsr {};
let key = std::env::var("ZHIPU_API_KEY")?;
let client = AudioToTextRequest::new(model, key)
.with_file_path("audio.mp3")
.with_stream(false);
let resp: AudioToTextResponse = client.send().await?;
println!("识别结果: {:#?}", resp);
Ok(())
}
```
## 错误处理
SDK 提供了全面的错误类型：
```rust,ignore
use zai_rs::client::error::{ZaiError, ZaiResult};
async fn chat() -> ZaiResult<String> {
let model = GLM4_5_flash {};
let messages = TextMessage::user("Hello");
let key = std::env::var("ZHIPU_API_KEY")?;
let client = ChatCompletion::new(model, messages, key);
let resp = client.post().await?;
Ok(resp.choices().first().unwrap().message.content_str().unwrap_or_default().to_string())
}
#[tokio::main]
async fn main() {
match chat().await {
Ok(content) => println!("Response: {}", content),
Err(ZaiError::AuthError { code, message }) => {
tracing::error!("认证错误 [{}]: {}", code, message);
}
Err(ZaiError::RateLimitError { code, message }) => {
tracing::error!("速率限制 [{}]: {}", code, message);
}
Err(e) => {
tracing::error!("发生错误: {}", e);
}
}
}
```
## API 密钥验证
SDK 自动验证 API 密钥格式：
```rust,ignore
use zai_rs::client::error::validate_api_key;
fn main() {
let api_key = "your-api-key.here";
match validate_api_key(api_key) {
Ok(()) => println!("API 密钥格式正确"),
Err(e) => tracing::error!("API 密钥格式错误: {}", e),
}
}
```
## 高级配置
### 自定义参数
```rust,ignore
use zai_rs::model::*;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let model = GLM4_5_flash {};
let messages = TextMessage::user("写一首诗");
let key = std::env::var("ZHIPU_API_KEY")?;
let mut client = ChatCompletion::new(model, messages, key);
// 自定义生成参数
client.body_mut().temperature = Some(0.7);
client.body_mut().top_p = Some(0.9);
client.body_mut().max_tokens = Some(1000);
let resp = client.post().await?;
println!("{}", resp.choices().first().unwrap().message.content_str().unwrap_or_default());
Ok(())
}
```
### 日志敏感信息过滤
SDK 提供了敏感信息过滤功能，用于安全日志：
```rust,ignore
use zai_rs::client::error::mask_sensitive_info;
fn main() {
let log_text = "API key: abc123.abcdefghijklmnopqrstuvwxyz12345, password: secret";
let filtered = mask_sensitive_info(log_text);
// 输出: API key: [FILTERED], password: [FILTERED]
println!("{}", filtered);
}
```
## 更多示例
- 查看 [examples](../examples/) 目录了解更多用法示例
- 参考 [API 文档](../src/) 获取完整 API 参考
## 支持与帮助
- [智谱AI API 文档](https://docs.bigmodel.cn/)
- [GitHub Issues](https://github.com/AnlangA/zai-rs/issues)