主要特性
V2 错误码与能力扩展包
13 种 V2 标准错误码，实现一致的错误处理。基于能力的扩展包：8 个可选包及完整包，支持最小或完整安装。
异步优先设计
全链路原生 async/await。基于 httpx 的传输层，带连接池。CancellableStream 实现优雅的流式终止。
Pydantic v2 类型
完整的类型提示与 Pydantic v2 校验。ProtocolManifest、Message、ContentBlock、StreamingEvent — 全部类型安全并支持运行时验证。
ResilientExecutor
ResilientExecutor 整合背压、限流、熔断和指数退避重试。PreflightChecker 在执行前对请求进行门控。
模型路由
ModelManager 配合 ModelArray 实现智能模型选择。策略包括轮询、加权、基于成本和基于质量的路由。
生产级遥测
MetricsCollector 支持 Prometheus 导出。通过 OpenTelemetry 实现分布式追踪。结构化日志。健康监控。用户反馈收集。
结构化输出
JSON 模式配置、从 Pydantic 模型生成 schema、输出校验。内容过滤和 PII 检测的护栏。
Python 风格与直观
简洁、符合 Python 风格的 API，使用自然。从模型标识符创建客户端，使用流式构建器构建请求，并遍历统一的流式事件。
同一套代码适用于所有提供商。从 OpenAI 切换到 Anthropic 或 DeepSeek，只需更改一个字符串 — 协议清单会处理其余工作。
from ai_lib_python import AiClient
# Works with ANY provider
client = await AiClient.create(
"anthropic/claude-3-5-sonnet"
)
# Streaming chat
async for event in client.chat() \
.user("Explain AI-Protocol") \
.temperature(0.7) \
.max_tokens(1000) \
.stream():
if event.is_content_delta:
print(event.as_content_delta.text,
end="")
# Non-streaming with stats
response, stats = await client.chat() \
.user("Summarize this") \
.execute_with_stats()
print(f"Tokens: {stats.total_tokens}")
print(f"Latency: {stats.latency_ms}ms")内部架构
与 Rust 运行时相同的分层架构 — 协议驱动、基于算子、默认弹性。
模块概览
client/ + errors/standard_codes/
AiClient、AiClientBuilder、ChatRequestBuilder、ChatResponse、CallStats、CancelToken、CancellableStream。
protocol/
ProtocolLoader（本地/环境变量/GitHub）、Pydantic 清单模型、JSON Schema 校验器、热重载支持。
pipeline/
Decoder（SSE、JSON Lines、Anthropic SSE）、Selector（JSONPath）、Accumulator、FanOut、EventMapper（协议驱动、默认、Anthropic）。
resilience/
ResilientExecutor、RetryPolicy、RateLimiter、CircuitBreaker、Backpressure、FallbackChain、SignalsSnapshot、PreflightChecker。
routing/
ModelManager、ModelArray，选择策略（轮询、加权、基于成本、基于质量）。主流提供商预配置目录。
telemetry/
MetricsCollector（Prometheus）、Tracer（OpenTelemetry）、结构化 Logger、HealthChecker、用户反馈收集。
embeddings/ + tokens/
EmbeddingClient 及向量操作。TokenCounter（tiktoken 集成）与成本估算，用于使用量追踪。
plugins/ + structured/
插件基类、PluginRegistry、HookManager、中间件链。JSON 模式配置、SchemaGenerator、OutputValidator。