特性开关(Features)与可选模块

本文说明如何在 Cargo 项目中按需引入 ai-lib 的可选特性,并给出不同场景的推荐组合。

基础依赖

[dependencies]
ai-lib = "0.3.4"
tokio = { version = "1", features = ["full"] }

启用特性

ai-lib 默认保持精简。根据需要开启特性:

[dependencies]
ai-lib = { version = "0.3.4", features = ["resilience", "streaming"] }

友好别名(提高易用性)

  • resilience → 启用 interceptors(重试/限流/熔断等拦截链)
  • streaming → 启用 unified_sse(统一流式解析)
  • transport → 启用 unified_transport(共享 reqwest 客户端工厂)
  • hot_reload → 启用 config_hot_reload(配置提供者/监听接口)
  • all → 打开大多数 OSS 特性:interceptorsunified_transportunified_ssecost_metricsrouting_mvpobservabilityconfig_hot_reload

新增:基础故障转移(OSS)

自 v0.3.x 起,AiClient::with_failover(Vec<Provider>) 可在网络/超时/限流/5xx 等可重试错误发生时,按照给定顺序切换到备用 Provider。与 routing_mvp 搭配时,会保留模型选择。

这些别名只是聚合启用粒度特性,本身不增加额外代码。

推荐组合

  • 最小化应用:不开启(按需增加)
  • 生产应用:resiliencetransportstreaming
  • 运维增强:resiliencetransportstreamingobservability
  • 动态配置:加上 hot_reload

示例:生产简化配置

[dependencies]
ai-lib = { version = "0.3.4", features = [
  "resilience",
  "transport",
  "streaming"
] }

导入风格

推荐使用根级导入,提升开发者体验:

// 推荐用于应用程序
use ai_lib::prelude::*;

// 或者库开发时使用显式导入
use ai_lib::{AiClient, Provider, ChatCompletionRequest, Message, Role, Content};
use ai_lib::{Tool, FunctionCallPolicy};

说明

  • 尽量保持依赖面最小:只启用你用到的特性。
  • 特性前向兼容;我们避免破坏性重命名。
  • 参考:快速开始聊天与流式处理
Build: b635c6a · 2025-09-17T16:29:53.050Z · v0.21