在 Dify 中使用 OneAster

​

准备工作

1. 已注册 Dify 账户
   访问 Dify 官网 注册账户，可选择云端版或自部署版本
2. 已获取 OneAster API 密钥
   登录 OneAster 控制台 获取您的 API 密钥（以 sk- 开头）

​

第一步：登录 Dify 并进入设置

​

1.1 访问 Dify 平台

• 云端版： 访问 https://cloud.dify.ai 并登录
• 自部署版： 访问您的 Dify 部署地址

​

1.2 进入模型设置页面

1. 点击右上角的 头像图标
2. 选择 设置 或 Settings
3. 在左侧菜单中选择 模型提供商 或 Model Provider

​

第二步：添加 OneAster 模型提供商

​

2.1 选择添加方式

​

方式一：使用 OpenAI 自定义 API（推荐）

1. 在模型提供商页面找到 OpenAI 提供商
2. 点击 配置 或 设置 按钮
3. 在配置页面：
   • API Key：填入您的 OneAster API 密钥（sk-xxxxxxxxxxxx）
   • API Base URL 或 Base URL：填入 https://api.oneaster.ai/v1
4. 点击 保存

5. 配置完成后，返回 OpenAI 提供商页面，查看 模型列表
6. 在模型列表中，找到您需要使用的模型（如 gpt-4o、gpt-4o-mini、chatgpt-4o-latest 等）
7. 点击模型右侧的 开关 启用模型（开关变为蓝色表示已启用）

​

方式二：添加自定义模型提供商

1. 向下滚动到 自定义模型 或 Custom Model 部分
2. 点击 + 添加模型 或 + Add Model 按钮

​

2.2 配置 OneAster 提供商

​

2.3 添加更多模型（可选）

1. 在自定义模型部分，再次点击 + 添加模型 按钮
2. 填写另一个模型的配置信息
3. 点击保存

​

GPT-4/5 系列

​

Claude 系列

​

Gemini 系列

​

第三步：在应用中使用 OneAster 模型

​

3.1 创建新应用

1. 返回 Dify 主页
2. 点击 创建应用 按钮
3. 选择应用类型：
   • 聊天助手 - 对话式应用
   • 文本生成 - 文本生成应用
   • Agent - 智能代理
   • 工作流 - 复杂工作流应用

​

3.2 选择 OneAster 模型

1. 找到 模型设置 区域
2. 点击 选择模型 下拉菜单
3. 选择 OneAster 提供商
4. 选择您配置的具体模型（如 gpt-4o）

​

3.3 配置模型参数

​

第四步：构建和测试应用

​

4.1 添加提示词

1. 在 系统提示词 区域编写提示词
2. 使用变量动态化您的应用：
   • {{variable_name}} - 用户输入变量
   • {{context}} - 知识库上下文

你是一个专业的客服助手，擅长解答用户关于产品的问题。

产品信息：{{product_info}}

请根据用户的问题提供准确、友好的回答。如果不确定答案，请诚实地告知用户。

用户问题：{{user_question}}

​

4.2 添加知识库（可选）

1. 在左侧菜单点击 知识库
2. 创建新知识库并上传文档
3. 在应用编排页面关联知识库
4. 配置检索参数

​

4.3 测试应用

1. 在右侧 预览 面板输入测试问题
2. 查看 AI 响应效果
3. 根据需要调整提示词和参数
4. 重复测试直到满意

​

4.4 发布应用

1. 点击右上角 发布 按钮
2. 选择发布方式：
   • API 调用 - 通过 API 集成
   • 嵌入网站 - 生成嵌入代码
   • 公开链接 - 生成分享链接

​

第五步：监控和优化

​

5.1 查看应用日志

1. 点击 日志 标签
2. 查看所有对话记录
3. 分析用户问题和 AI 响应
4. 发现改进机会

​

5.2 监控 API 使用

• 📊 API 调用统计 - 总调用次数、成功率
• 💰 费用明细 - 每日/每月费用
• 📈 使用趋势 - 使用量变化趋势
• 🔍 请求日志 - 详细的请求记录

​

5.3 优化应用性能

1. 调整模型选择
   • 简单任务使用 gpt-4o-mini 降低成本
   • 复杂任务使用 gpt-4o 或 claude-sonnet-4-5 提升质量
2. 优化提示词
   • 使提示词更清晰具体
   • 添加示例提升效果
   • 使用思维链提升推理能力
3. 配置缓存
   • 对相似问题启用缓存
   • 降低 API 调用成本

​

高级功能

​

使用工作流编排

1. 条件分支 - 根据不同条件执行不同逻辑
2. 多模型协作 - 结合多个模型的优势
3. 外部工具调用 - 调用 API、数据库等外部资源
4. 变量传递 - 在不同节点间传递数据

​

配置 Agent 能力

1. 工具调用 - 让 AI 调用外部工具
2. 记忆管理 - 维护长期对话记忆
3. 自主决策 - AI 自主规划执行步骤

​

多模态应用

1. 图像理解 - 使用 gpt-4o 或 claude-3 处理图像
2. 图像生成 - 集成 OneAster 的图像生成 API
3. 语音处理 - 集成 TTS 和 STT 服务

​

常见问题

​

Q1: 无法连接到 OneAster 服务？

1. 检查 Base URL：
   • 确保是 https://api.oneaster.ai/v1（包含 /v1）
   • 不要添加额外的路径或遗漏 /v1
2. 验证 API Key：
   • 确认 API Key 以 sk- 开头
   • 在 OneAster 控制台 检查密钥是否有效
3. 检查网络连接：
   • 确保服务器能访问 https://api.oneaster.ai
   • 自部署版本需要确保服务器网络畅通

​

Q2: 模型响应速度慢？

1. 切换更快的模型：
   • 使用 gpt-4o-mini 代替 gpt-4o
   • 使用 gemini-2.0-flash-exp 获得更快响应
2. 优化提示词长度：
   • 减少不必要的上下文
   • 简化提示词描述
3. 调整知识库检索：
   • 减少检索文档数量
   • 提高相似度阈值

​

Q3: API 调用失败或返回错误？

​

Q4: 如何降低 API 使用成本？

1. 模型选择：
   • 简单任务使用 gpt-4o-mini（成本仅为 gpt-4o 的 1/10）
   • 批量任务考虑使用更经济的模型
2. 启用缓存：
   • 对相同问题返回缓存结果
   • 在 Dify 中配置相似度匹配
3. 优化输出长度：
   • 设置合理的 Max Tokens
   • 避免生成过长的响应
4. 使用流式输出：
   • 提升用户体验的同时不增加成本

​

Q5: 如何处理敏感数据？

1. 使用环境变量：
   • 不要在代码中硬编码 API Key
   • 使用 Dify 的环境变量功能
2. 配置访问控制：
   • 设置应用访问权限
   • 使用 API 调用时启用认证
3. 审计日志：
   • 定期检查应用日志
   • 监控异常访问模式

​

最佳实践

​

1. 提示词工程

# 角色定义
你是一个专业的 [角色描述]

# 任务目标
你需要帮助用户 [任务描述]

# 输出要求
- 要求1
- 要求2
- 要求3

# 输入信息
{{user_input}}

​

2. 知识库管理

• 分块策略：合理设置文档分块大小（推荐 500-1000 字符）
• 元数据标注：为文档添加元数据便于检索
• 定期更新：保持知识库内容最新

​

3. 错误处理

• 友好提示：给用户清晰的错误提示
• 降级策略：主模型失败时切换备用模型
• 重试机制：自动重试临时性错误

​

4. 性能监控

• 设置告警：余额不足、错误率过高时告警
• 定期分析：每周/月分析使用数据
• 持续优化：根据数据调整配置

​

使用场景示例

​

1. 智能客服

• 模型：gpt-4o-mini（高性价比）
• 知识库：产品文档、FAQ
• 功能：自动回答常见问题，复杂问题转人工

​

2. 内容创作助手

• 模型：gpt-4o 或 claude-sonnet-4-5（高质量）
• 功能：文章生成、改写、润色
• 参数：Temperature=0.8（提升创意性）

​

3. 代码助手

• 模型：claude-sonnet-4-5（擅长代码）
• 功能：代码生成、解释、调试
• 知识库：项目文档、API 文档

​

4. 数据分析助手

• 模型：gpt-4o（强大的推理能力）
• 工具：Python 代码执行、数据可视化
• 功能：数据分析、报告生成

​

功能特性

• 🤖 快速构建 AI 应用 - 无需编码即可创建强大的 AI 应用
• 📚 知识库增强 - RAG 技术让 AI 基于您的数据回答
• 🔧 灵活的工作流 - 可视化编排复杂的 AI 逻辑
• 🎯 精准的提示词管理 - 版本控制和 A/B 测试
• 📊 完整的监控分析 - 了解应用使用情况和性能
• 🔌 多种集成方式 - API、嵌入式、WebApp 等多种方式
• 👥 团队协作 - 支持多人协作开发应用
• 🌐 多模型支持 - 灵活切换不同的 AI 模型

​

支持与帮助

• 📚 OneAster 文档中心
• 📚 Dify 官方文档
• 💬 Discord 社区
• 🐦 Twitter @oneaster_
• 📧 技术支持：[email protected]