285 lines
6.0 KiB
Markdown
285 lines
6.0 KiB
Markdown
# AI 智能体接入指南
|
||
|
||
> 集成 OpenClaw AI Agent，实现知识库问答、工作流触发与多模型切换。
|
||
|
||
## 🧠 什么是 AI 智能体？
|
||
|
||
AI 智能体（AI Agent）是 Websopy 平台的核心能力，它能：
|
||
|
||
- 🤖 基于自然语言理解用户意图
|
||
- 📚 连接你的知识库进行精准问答
|
||
- 🔗 触发业务工作流执行自动化任务
|
||
- 🔄 在多个 AI 模型间智能切换
|
||
|
||
## 📋 前提条件
|
||
|
||
- 已完成 [快速上手](./quickstart.md)
|
||
- 已开通 AI 功能（控制台 → 开发者中心 → AI 功能）
|
||
|
||
## 🚀 接入步骤
|
||
|
||
### 第一步：安装 AI SDK
|
||
|
||
```bash
|
||
npm install @websopy/ai-sdk
|
||
```
|
||
|
||
### 第二步：初始化 Agent
|
||
|
||
```typescript
|
||
import { AIAgent } from '@websopy/ai-sdk'
|
||
|
||
const agent = new AIAgent({
|
||
apiKey: process.env.WEBSOPY_API_KEY,
|
||
// 选择默认模型
|
||
defaultModel: 'gpt-4',
|
||
// 可用模型列表
|
||
models: ['gpt-4', 'claude-3', 'gemini-pro']
|
||
})
|
||
```
|
||
|
||
### 第三步：创建会话
|
||
|
||
```typescript
|
||
// 创建新的对话会话
|
||
const session = await agent.createSession({
|
||
userId: 'user-123',
|
||
// 关联知识库（可选）
|
||
knowledgeBaseId: 'kb-abc456',
|
||
// 会话元数据
|
||
metadata: {
|
||
source: 'website',
|
||
language: 'zh-CN'
|
||
}
|
||
})
|
||
|
||
console.log('会话 ID:', session.id)
|
||
```
|
||
|
||
### 第四步：发送消息
|
||
|
||
```typescript
|
||
// 发送用户消息
|
||
const response = await agent.sendMessage(session.id, {
|
||
content: '我想了解你们的产品价格',
|
||
// 可选：附加参数
|
||
context: {
|
||
userPlan: 'free',
|
||
priority: 'normal'
|
||
}
|
||
})
|
||
|
||
console.log('AI 回复:', response.content)
|
||
console.log('使用模型:', response.model)
|
||
console.log('置信度:', response.confidence)
|
||
```
|
||
|
||
### 第五步：流式响应（SSE）
|
||
|
||
对于需要实时反馈的场景，使用流式输出：
|
||
|
||
```typescript
|
||
const stream = await agent.sendMessageStream(session.id, {
|
||
content: '写一篇关于 AI 的博客文章'
|
||
})
|
||
|
||
for await (const chunk of stream) {
|
||
process.stdout.write(chunk.content)
|
||
}
|
||
```
|
||
|
||
## 📚 知识库集成
|
||
|
||
### 创建知识库
|
||
|
||
```typescript
|
||
const kb = await agent.createKnowledgeBase({
|
||
name: '产品文档',
|
||
description: '公司产品相关文档',
|
||
// 向量化模型
|
||
embeddingModel: 'text-embedding-3-small'
|
||
})
|
||
|
||
// 上传文档
|
||
await agent.uploadDocument(kb.id, {
|
||
file: './docs/product-guide.pdf',
|
||
// 文档元数据
|
||
metadata: {
|
||
category: 'documentation',
|
||
version: '2.0'
|
||
}
|
||
})
|
||
```
|
||
|
||
### 关联知识库问答
|
||
|
||
```typescript
|
||
const response = await agent.sendMessage(session.id, {
|
||
content: '你们的退款政策是什么？',
|
||
// 强制从知识库检索
|
||
retrieveFrom: 'kb-abc456',
|
||
// 检索参数
|
||
retrievalConfig: {
|
||
topK: 5, // 返回前 5 条相关片段
|
||
scoreThreshold: 0.7 // 相似度阈值
|
||
}
|
||
})
|
||
```
|
||
|
||
## 🔧 工作流触发
|
||
|
||
AI Agent 可以根据对话内容自动触发业务工作流：
|
||
|
||
```typescript
|
||
// 配置意图识别和触发
|
||
await agent.setIntentHandler(session.id, {
|
||
intents: [
|
||
{
|
||
name: 'create_order',
|
||
patterns: ['下单', '购买', '创建订单'],
|
||
action: 'trigger_workflow',
|
||
workflowId: 'wf-order-create'
|
||
},
|
||
{
|
||
name: 'cancel_subscription',
|
||
patterns: ['取消订阅', '退订'],
|
||
action: 'trigger_workflow',
|
||
workflowId: 'wf-subscription-cancel'
|
||
}
|
||
]
|
||
})
|
||
|
||
// 处理工作流结果
|
||
agent.onWorkflowComplete((result) => {
|
||
console.log('工作流完成:', result.workflowId)
|
||
console.log('结果:', result.output)
|
||
})
|
||
```
|
||
|
||
## 🔄 多模型切换
|
||
|
||
### 手动切换
|
||
|
||
```typescript
|
||
// 切换到指定模型
|
||
await agent.switchModel(session.id, 'claude-3')
|
||
|
||
const response = await agent.sendMessage(session.id, {
|
||
content: '解释量子计算原理'
|
||
})
|
||
```
|
||
|
||
### 自动路由
|
||
|
||
根据任务类型自动选择最优模型：
|
||
|
||
```typescript
|
||
const agent = new AIAgent({
|
||
apiKey: process.env.WEBSOPY_API_KEY,
|
||
// 配置自动路由
|
||
autoRoute: {
|
||
enabled: true,
|
||
rules: [
|
||
{ task: 'coding', models: ['gpt-4', 'claude-3'] },
|
||
{ task: 'creative', models: ['gpt-4', 'gemini-pro'] },
|
||
{ task: 'analysis', models: ['claude-3', 'gpt-4'] }
|
||
]
|
||
}
|
||
})
|
||
```
|
||
|
||
## 📊 高级配置
|
||
|
||
### 对话上下文管理
|
||
|
||
```typescript
|
||
// 设置上下文窗口大小
|
||
agent.setContextWindow(session.id, {
|
||
maxMessages: 50, // 保留最近 50 条消息
|
||
maxTokens: 8000 // 最大 token 数
|
||
})
|
||
|
||
// 手动添加系统提示
|
||
agent.addSystemPrompt(session.id, {
|
||
role: 'system',
|
||
content: '你是一个专业的客服助手，说话风格友好、专业。'
|
||
})
|
||
```
|
||
|
||
### 错误处理与重试
|
||
|
||
```typescript
|
||
const response = await agent.sendMessage(session.id, {
|
||
content: '复杂问题...'
|
||
}, {
|
||
// 重试配置
|
||
retry: {
|
||
maxAttempts: 3,
|
||
delayMs: 1000,
|
||
backoff: 'exponential'
|
||
},
|
||
// 超时配置（毫秒）
|
||
timeout: 30000
|
||
})
|
||
```
|
||
|
||
## 🧪 完整示例
|
||
|
||
```typescript
|
||
import { AIAgent } from '@websopy/ai-sdk'
|
||
|
||
async function main() {
|
||
const agent = new AIAgent({
|
||
apiKey: process.env.WEBSOPY_API_KEY,
|
||
defaultModel: 'gpt-4'
|
||
})
|
||
|
||
// 创建会话
|
||
const session = await agent.createSession({
|
||
userId: 'user-123',
|
||
knowledgeBaseId: 'kb-product-docs'
|
||
})
|
||
|
||
// 对话循环
|
||
const messages = [
|
||
'你好，我想了解一下企业版的功能',
|
||
'支持私有化部署吗？',
|
||
'好的，我想试用一下'
|
||
]
|
||
|
||
for (const msg of messages) {
|
||
const response = await agent.sendMessage(session.id, {
|
||
content: msg
|
||
})
|
||
console.log(`\n👤 用户: ${msg}`)
|
||
console.log(`🤖 AI: ${response.content}`)
|
||
}
|
||
}
|
||
|
||
main()
|
||
```
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q: 如何查看 API 调用量？
|
||
|
||
在控制台 → 开发者中心 → AI 功能，可以查看详细的使用统计。
|
||
|
||
### Q: 支持哪些 Embedding 模型？
|
||
|
||
目前支持：
|
||
- `text-embedding-3-small`（推荐，速度快）
|
||
- `text-embedding-3-large`（高精度）
|
||
- `text-embedding-ada-002`（兼容性）
|
||
|
||
### Q: 知识库检索不到相关内容？
|
||
|
||
1. 检查文档是否已成功上传和向量化
|
||
2. 调整 `scoreThreshold` 降低阈值
|
||
3. 尝试增加 `topK` 获取更多候选
|
||
|
||
---
|
||
|
||
**上一步：** [5 分钟快速上手](./quickstart.md)
|
||
**下一步：** [私有化部署完全指南](./deployment.md)
|