核心 API

核心API是XAI-SDK的基础接口，提供了与AI服务交互的主要功能。

XAI_SDK 类

构造函数

class XAI_SDK {
  constructor(config: XAIConfig)
}

XAIConfig 配置

interface XAIConfig {
  /** 默认适配器名称 */
  defaultAdapter?: string
  
  /** 适配器配置 */
  adapters?: Record<string, AdapterConfig>
  
  /** 插件配置 */
  plugins?: PluginConfig[]
  
  /** 中间件配置 */
  middleware?: MiddlewareConfig[]
  
  /** 全局配置 */
  global?: {
    /** 默认模型 */
    defaultModel?: string
    
    /** 请求超时时间 */
    timeout?: number
    
    /** 最大重试次数 */
    maxRetries?: number
    
    /** 调试模式 */
    debug?: boolean
    
    /** 日志级别 */
    logLevel?: 'debug' | 'info' | 'warn' | 'error'
  }
  
  /** 缓存配置 */
  cache?: {
    /** 是否启用缓存 */
    enabled?: boolean
    
    /** 缓存过期时间(毫秒) */
    ttl?: number
    
    /** 最大缓存条目数 */
    maxSize?: number
  }
}

基础方法

initialize()

初始化SDK实例：

async initialize(): Promise<void>

示例：

const sdk = new XAI_SDK({
  defaultAdapter: 'openai',
  adapters: {
    openai: {
      apiKey: process.env.OPENAI_API_KEY!,
      defaultModel: 'gpt-3.5-turbo'
    }
  }
})

await sdk.initialize()

chat()

发送聊天请求：

async chat(
  messages: Message[],
  options?: ChatOptions
): Promise<ChatResponse>

参数：

• messages: 消息数组
• options: 可选的聊天配置

返回值：

interface ChatResponse {
  /** 响应内容 */
  content: string
  
  /** 使用的模型 */
  model: string
  
  /** 使用的适配器 */
  adapter: string
  
  /** 响应时间(毫秒) */
  responseTime: number
  
  /** Token使用统计 */
  usage?: {
    promptTokens: number
    completionTokens: number
    totalTokens: number
  }
  
  /** 响应元数据 */
  metadata?: Record<string, any>
}

示例：

const response = await sdk.chat([
  { role: 'user', content: '你好，请介绍一下你自己' }
], {
  model: 'gpt-4',
  temperature: 0.7,
  maxTokens: 1000
})

console.log(response.content)
console.log(`响应时间: ${response.responseTime}ms`)
console.log(`使用Token: ${response.usage?.totalTokens}`)

streamChat()

发送流式聊天请求：

async *streamChat(
  messages: Message[],
  options?: ChatOptions
): AsyncIterable<StreamChunk>

返回值：

interface StreamChunk {
  /** 内容片段 */
  content: string
  
  /** 是否为最后一个片段 */
  done: boolean
  
  /** 累计内容 */
  fullContent?: string
  
  /** 响应元数据 */
  metadata?: Record<string, any>
}

示例：

let fullResponse = ''

for await (const chunk of sdk.streamChat([
  { role: 'user', content: '请写一首关于春天的诗' }
])) {
  process.stdout.write(chunk.content)
  fullResponse += chunk.content
  
  if (chunk.done) {
    console.log('\n流式响应完成')
    console.log('完整响应:', fullResponse)
  }
}

batchChat()

批量处理聊天请求：

async batchChat(
  requests: BatchChatRequest[],
  options?: BatchOptions
): Promise<BatchChatResponse[]>

参数：

interface BatchChatRequest {
  id: string
  messages: Message[]
  options?: ChatOptions
}

interface BatchOptions {
  /** 并发数量 */
  concurrency?: number
  
  /** 失败时是否继续 */
  continueOnError?: boolean
  
  /** 进度回调 */
  onProgress?: (completed: number, total: number) => void
}

interface BatchChatResponse {
  id: string
  success: boolean
  response?: ChatResponse
  error?: Error
}

示例：

const requests: BatchChatRequest[] = [
  {
    id: 'req1',
    messages: [{ role: 'user', content: '什么是AI？' }]
  },
  {
    id: 'req2',
    messages: [{ role: 'user', content: '什么是机器学习？' }]
  },
  {
    id: 'req3',
    messages: [{ role: 'user', content: '什么是深度学习？' }]
  }
]

const responses = await sdk.batchChat(requests, {
  concurrency: 2,
  onProgress: (completed, total) => {
    console.log(`进度: ${completed}/${total}`)
  }
})

for (const response of responses) {
  if (response.success) {
    console.log(`${response.id}: ${response.response?.content}`)
  } else {
    console.error(`${response.id} 失败:`, response.error?.message)
  }
}

适配器管理

addAdapter()

添加适配器：

addAdapter(name: string, adapter: BaseAdapter): void

示例：

const customAdapter = new CustomAdapter({
  apiKey: 'your-api-key',
  baseURL: 'https://api.custom.com'
})

sdk.addAdapter('custom', customAdapter)

getAdapter()

获取适配器：

getAdapter(name?: string): BaseAdapter | undefined

示例：

// 获取默认适配器
const defaultAdapter = sdk.getAdapter()

// 获取指定适配器
const openaiAdapter = sdk.getAdapter('openai')

setDefaultAdapter()

设置默认适配器：

setDefaultAdapter(name: string): void

示例：

sdk.setDefaultAdapter('anthropic')

listAdapters()

列出所有适配器：

listAdapters(): string[]

示例：

const adapters = sdk.listAdapters()
console.log('可用适配器:', adapters)

插件管理

addPlugin()

添加插件：

addPlugin(plugin: Plugin): void

示例：

const loggerPlugin = new LoggerPlugin({
  level: 'info',
  format: 'json'
})

sdk.addPlugin(loggerPlugin)

removePlugin()

移除插件：

removePlugin(name: string): boolean

示例：

const removed = sdk.removePlugin('logger')
console.log('插件移除结果:', removed)

listPlugins()

列出所有插件：

listPlugins(): string[]

示例：

const plugins = sdk.listPlugins()
console.log('已安装插件:', plugins)

工具系统

addTool()

添加工具：

addTool(tool: Tool): void

示例：

const weatherTool = {
  name: 'get_weather',
  description: '获取天气信息',
  parameters: {
    type: 'object',
    properties: {
      location: {
        type: 'string',
        description: '城市名称'
      }
    },
    required: ['location']
  },
  execute: async (params: { location: string }) => {
    // 实现天气查询逻辑
    return `${params.location}的天气是晴天`
  }
}

sdk.addTool(weatherTool)

executeTool()

执行工具：

async executeTool(
  name: string,
  parameters: Record<string, any>
): Promise<ToolResult>

示例：

const result = await sdk.executeTool('get_weather', {
  location: '北京'
})

console.log(result.content)

listTools()

列出所有工具：

listTools(): Tool[]

示例：

const tools = sdk.listTools()
for (const tool of tools) {
  console.log(`工具: ${tool.name} - ${tool.description}`)
}

中间件系统

addMiddleware()

添加中间件：

addMiddleware(middleware: Middleware): void

示例：

const rateLimitMiddleware = {
  name: 'rate-limit',
  async before(context: MiddlewareContext) {
    // 请求前的处理逻辑
    console.log('检查请求频率限制')
  },
  async after(context: MiddlewareContext, result: any) {
    // 请求后的处理逻辑
    console.log('更新请求计数')
    return result
  },
  async onError(context: MiddlewareContext, error: Error) {
    // 错误处理逻辑
    console.error('中间件错误:', error.message)
    throw error
  }
}

sdk.addMiddleware(rateLimitMiddleware)

配置管理

getConfig()

获取配置：

getConfig(): XAIConfig

示例：

const config = sdk.getConfig()
console.log('当前配置:', config)

updateConfig()

更新配置：

updateConfig(config: Partial<XAIConfig>): void

示例：

sdk.updateConfig({
  global: {
    timeout: 60000,
    debug: true
  }
})

健康检查

healthCheck()

检查SDK健康状态：

async healthCheck(): Promise<HealthCheckResult>

返回值：

interface HealthCheckResult {
  /** 整体状态 */
  status: 'healthy' | 'degraded' | 'unhealthy'
  
  /** 适配器状态 */
  adapters: Record<string, HealthStatus>
  
  /** 插件状态 */
  plugins: Record<string, HealthStatus>
  
  /** 系统信息 */
  system: {
    uptime: number
    memory: {
      used: number
      total: number
    }
    version: string
  }
  
  /** 检查时间 */
  timestamp: Date
}

示例：

const health = await sdk.healthCheck()
console.log('SDK状态:', health.status)

for (const [name, status] of Object.entries(health.adapters)) {
  console.log(`适配器 ${name}: ${status.status}`)
}

for (const [name, status] of Object.entries(health.plugins)) {
  console.log(`插件 ${name}: ${status.status}`)
}

统计信息

getStats()

获取使用统计：

getStats(): SDKStats

返回值：

interface SDKStats {
  /** 请求统计 */
  requests: {
    total: number
    successful: number
    failed: number
    averageResponseTime: number
  }
  
  /** 适配器统计 */
  adapters: Record<string, {
    requests: number
    errors: number
    averageResponseTime: number
  }>
  
  /** Token使用统计 */
  tokens: {
    totalPromptTokens: number
    totalCompletionTokens: number
    totalTokens: number
  }
  
  /** 缓存统计 */
  cache: {
    hits: number
    misses: number
    hitRate: number
  }
  
  /** 启动时间 */
  startTime: Date
  
  /** 运行时间 */
  uptime: number
}

示例：

const stats = sdk.getStats()
console.log('总请求数:', stats.requests.total)
console.log('成功率:', (stats.requests.successful / stats.requests.total * 100).toFixed(2) + '%')
console.log('平均响应时间:', stats.requests.averageResponseTime + 'ms')
console.log('缓存命中率:', (stats.cache.hitRate * 100).toFixed(2) + '%')

resetStats()

重置统计信息：

resetStats(): void

示例：

sdk.resetStats()
console.log('统计信息已重置')

事件系统

on()

监听事件：

on(event: string, listener: (...args: any[]) => void): void

支持的事件：

• request:start - 请求开始
• request:end - 请求结束
• request:error - 请求错误
• adapter:added - 适配器添加
• adapter:removed - 适配器移除
• plugin:added - 插件添加
• plugin:removed - 插件移除
• tool:executed - 工具执行
• config:updated - 配置更新

示例：

sdk.on('request:start', (context) => {
  console.log('请求开始:', context.messages[0].content)
})

sdk.on('request:end', (context, response) => {
  console.log('请求完成，响应时间:', response.responseTime + 'ms')
})

sdk.on('request:error', (context, error) => {
  console.error('请求失败:', error.message)
})

off()

移除事件监听：

off(event: string, listener?: (...args: any[]) => void): void

示例：

// 移除特定监听器
sdk.off('request:start', specificListener)

// 移除所有监听器
sdk.off('request:start')

emit()

触发事件：

emit(event: string, ...args: any[]): void

示例：

sdk.emit('custom:event', { data: 'custom data' })

资源管理

dispose()

清理资源：

async dispose(): Promise<void>

示例：

// 应用退出时清理资源
process.on('SIGINT', async () => {
  console.log('正在清理资源...')
  await sdk.dispose()
  process.exit(0)
})

类型定义

核心类型

interface Message {
  role: 'user' | 'assistant' | 'system'
  content: string
  name?: string
  metadata?: Record<string, any>
}

interface ChatOptions {
  /** 使用的适配器 */
  adapter?: string
  
  /** 使用的模型 */
  model?: string
  
  /** 温度参数 */
  temperature?: number
  
  /** 最大Token数 */
  maxTokens?: number
  
  /** Top-p参数 */
  topP?: number
  
  /** 频率惩罚 */
  frequencyPenalty?: number
  
  /** 存在惩罚 */
  presencePenalty?: number
  
  /** 停止词 */
  stop?: string[]
  
  /** 是否启用工具 */
  tools?: boolean
  
  /** 可用工具列表 */
  availableTools?: string[]
  
  /** 自定义元数据 */
  metadata?: Record<string, any>
}

interface MiddlewareContext {
  messages: Message[]
  options: ChatOptions
  adapter: string
  startTime: number
  metadata: Record<string, any>
}

interface Middleware {
  name: string
  before?(context: MiddlewareContext): Promise<void>
  after?(context: MiddlewareContext, result: any): Promise<any>
  onError?(context: MiddlewareContext, error: Error): Promise<void>
}

interface Tool {
  name: string
  description: string
  parameters: {
    type: 'object'
    properties: Record<string, any>
    required?: string[]
  }
  execute: (parameters: Record<string, any>) => Promise<any>
}

interface ToolResult {
  success: boolean
  content: any
  error?: string
  executionTime: number
}

错误类型

class XAIError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: any
  ) {
    super(message)
    this.name = 'XAIError'
  }
}

const ErrorCodes = {
  INITIALIZATION_FAILED: 'INITIALIZATION_FAILED',
  ADAPTER_NOT_FOUND: 'ADAPTER_NOT_FOUND',
  INVALID_CONFIG: 'INVALID_CONFIG',
  REQUEST_FAILED: 'REQUEST_FAILED',
  TOOL_NOT_FOUND: 'TOOL_NOT_FOUND',
  TOOL_EXECUTION_FAILED: 'TOOL_EXECUTION_FAILED',
  PLUGIN_ERROR: 'PLUGIN_ERROR',
  MIDDLEWARE_ERROR: 'MIDDLEWARE_ERROR'
} as const

使用示例

基础使用

import { XAI_SDK } from 'xai-sdk'

const sdk = new XAI_SDK({
  defaultAdapter: 'openai',
  adapters: {
    openai: {
      apiKey: process.env.OPENAI_API_KEY!,
      defaultModel: 'gpt-3.5-turbo'
    }
  },
  global: {
    timeout: 30000,
    debug: true
  }
})

await sdk.initialize()

const response = await sdk.chat([
  { role: 'user', content: '你好' }
])

console.log(response.content)

高级使用

import { XAI_SDK, LoggerPlugin, CachePlugin } from 'xai-sdk'

const sdk = new XAI_SDK({
  defaultAdapter: 'openai',
  adapters: {
    openai: {
      apiKey: process.env.OPENAI_API_KEY!,
      defaultModel: 'gpt-4'
    },
    anthropic: {
      apiKey: process.env.ANTHROPIC_API_KEY!,
      defaultModel: 'claude-3-sonnet-20240229'
    }
  },
  plugins: [
    {
      name: 'logger',
      config: { level: 'info' }
    },
    {
      name: 'cache',
      config: { ttl: 300000 }
    }
  ],
  cache: {
    enabled: true,
    ttl: 300000,
    maxSize: 1000
  }
})

// 添加自定义工具
sdk.addTool({
  name: 'calculate',
  description: '执行数学计算',
  parameters: {
    type: 'object',
    properties: {
      expression: {
        type: 'string',
        description: '数学表达式'
      }
    },
    required: ['expression']
  },
  execute: async (params) => {
    // 安全的数学表达式计算
    return eval(params.expression)
  }
})

// 添加中间件
sdk.addMiddleware({
  name: 'request-logger',
  async before(context) {
    console.log(`[${new Date().toISOString()}] 请求开始:`, context.messages[0].content)
  },
  async after(context, result) {
    console.log(`[${new Date().toISOString()}] 请求完成，耗时: ${Date.now() - context.startTime}ms`)
    return result
  }
})

await sdk.initialize()

// 使用不同适配器
const openaiResponse = await sdk.chat([
  { role: 'user', content: '用OpenAI回答：什么是人工智能？' }
], { adapter: 'openai' })

const anthropicResponse = await sdk.chat([
  { role: 'user', content: '用Anthropic回答：什么是人工智能？' }
], { adapter: 'anthropic' })

// 流式响应
for await (const chunk of sdk.streamChat([
  { role: 'user', content: '请详细解释机器学习的概念' }
])) {
  process.stdout.write(chunk.content)
}

// 批量处理
const batchRequests = [
  {
    id: 'q1',
    messages: [{ role: 'user', content: '什么是深度学习？' }]
  },
  {
    id: 'q2',
    messages: [{ role: 'user', content: '什么是神经网络？' }]
  }
]

const batchResponses = await sdk.batchChat(batchRequests, {
  concurrency: 2
})

// 健康检查
const health = await sdk.healthCheck()
console.log('SDK健康状态:', health.status)

// 获取统计信息
const stats = sdk.getStats()
console.log('请求统计:', stats.requests)

---

核心API提供了XAI-SDK的所有基础功能，通过这些接口可以轻松实现各种AI应用场景。