Using OneAster in Dify

​

Prerequisites

1. Dify account registered Visit Dify Official Website to register an account, choose cloud or self-hosted version
2. OneAster API Key obtained Log in to OneAster Console to get your API key (starts with sk-)

​

Step 1: Log in to Dify and Access Settings

​

1.1 Access Dify Platform

• Cloud Version: Visit https://cloud.dify.ai and log in
• Self-hosted Version: Visit your Dify deployment address

​

1.2 Navigate to Model Settings

1. Click the avatar icon in the top right corner
2. Select Settings
3. Choose Model Provider in the left menu

​

Step 2: Add OneAster Model Provider

​

2.1 Select Configuration Method

​

Method 1: Use OpenAI Custom API (Recommended)

1. Find the OpenAI provider on the Model Provider page
2. Click the Configure or Settings button
3. On the configuration page:
   • API Key: Enter your OneAster API key (sk-xxxxxxxxxxxx)
   • API Base URL or Base URL: Enter https://api.oneaster.ai/v1
4. Click Save

5. After configuration, return to the OpenAI provider page and view the Model List
6. In the model list, find the models you need (e.g., gpt-4o, gpt-4o-mini, chatgpt-4o-latest, etc.)
7. Click the switch on the right side of the model to enable it (blue indicates enabled)

​

Method 2: Add Custom Model Provider

1. Scroll down to the Custom Model section
2. Click the + Add Model button

​

2.2 Configure OneAster Provider

​

2.3 Add More Models (Optional)

1. In the custom model section, click the + Add Model button again
2. Fill in the configuration information for another model
3. Click Save

​

GPT-4/5 Series

​

Claude Series

​

Gemini Series

​

Step 3: Use OneAster Models in Applications

​

3.1 Create New Application

1. Return to Dify homepage
2. Click Create App button
3. Select application type:
   • Chatbot - Conversational application
   • Text Generator - Text generation application
   • Agent - Intelligent agent
   • Workflow - Complex workflow application

​

3.2 Select OneAster Model

1. Find the Model Settings area
2. Click the Select Model dropdown
3. Select OneAster provider
4. Choose your configured model (e.g., gpt-4o)

​

3.3 Configure Model Parameters

​

Step 4: Build and Test Application

​

4.1 Add Prompts

1. Write prompts in the System Prompt area
2. Use variables to make your app dynamic:
   • {{variable_name}} - User input variable
   • {{context}} - Knowledge base context

You are a professional customer service assistant, skilled at answering product questions.

Product Information: {{product_info}}

Please provide accurate and friendly answers based on user questions. If unsure, honestly inform the user.

User Question: {{user_question}}

​

4.2 Add Knowledge Base (Optional)

1. Click Knowledge Base in the left menu
2. Create new knowledge base and upload documents
3. Link knowledge base on application orchestration page
4. Configure retrieval parameters

​

4.3 Test Application

1. Input test questions in the Preview panel on the right
2. Review AI response effectiveness
3. Adjust prompts and parameters as needed
4. Repeat testing until satisfied

​

4.4 Publish Application

1. Click Publish button in top right
2. Select publishing method:
   • API Call - Integration via API
   • Embed in Website - Generate embed code
   • Public Link - Generate share link

​

Step 5: Monitor and Optimize

​

5.1 View Application Logs

1. Click the Logs tab
2. View all conversation records
3. Analyze user questions and AI responses
4. Discover improvement opportunities

​

5.2 Monitor API Usage

• 📊 API Call Statistics - Total calls, success rate
• 💰 Cost Details - Daily/monthly costs
• 📈 Usage Trends - Usage change trends
• 🔍 Request Logs - Detailed request records

​

5.3 Optimize Application Performance

1. Adjust Model Selection
   • Use gpt-4o-mini for simple tasks to reduce costs
   • Use gpt-4o or claude-sonnet-4-5 for complex tasks to improve quality
2. Optimize Prompts
   • Make prompts clearer and more specific
   • Add examples to improve effectiveness
   • Use chain-of-thought for better reasoning
3. Configure Caching
   • Enable caching for similar questions
   • Reduce API call costs

​

Advanced Features

​

Using Workflow Orchestration

1. Conditional Branches - Execute different logic based on conditions
2. Multi-model Collaboration - Combine advantages of multiple models
3. External Tool Calls - Call APIs, databases, and other external resources
4. Variable Passing - Pass data between different nodes

​

Configuring Agent Capabilities

1. Tool Calling - Let AI call external tools
2. Memory Management - Maintain long-term conversation memory
3. Autonomous Decision-making - AI autonomously plans execution steps

​

Multimodal Applications

1. Image Understanding - Use gpt-4o or claude-3 to process images
2. Image Generation - Integrate OneAster’s image generation API
3. Voice Processing - Integrate TTS and STT services

​

FAQ

​

Q1: Cannot connect to OneAster service?

1. Check Base URL:
   • Ensure it’s https://api.oneaster.ai/v1 (includes /v1)
   • Don’t add extra paths or omit /v1
2. Verify API Key:
   • Confirm API Key starts with sk-
   • Check if key is valid in OneAster Console
3. Check Network Connection:
   • Ensure server can access https://api.oneaster.ai
   • Self-hosted versions need to ensure server network connectivity

​

Q2: Model response is slow?

1. Switch to Faster Models:
   • Use gpt-4o-mini instead of gpt-4o
   • Use gemini-2.0-flash-exp for faster response
2. Optimize Prompt Length:
   • Reduce unnecessary context
   • Simplify prompt descriptions
3. Adjust Knowledge Base Retrieval:
   • Reduce number of retrieved documents
   • Increase similarity threshold

​

Q3: API calls fail or return errors?

​

Q4: How to reduce API usage costs?

1. Model Selection:
   • Use gpt-4o-mini for simple tasks (cost is only 1/10 of gpt-4o)
   • Consider more economical models for batch tasks
2. Enable Caching:
   • Return cached results for same questions
   • Configure similarity matching in Dify
3. Optimize Output Length:
   • Set reasonable Max Tokens
   • Avoid generating overly long responses
4. Use Streaming Output:
   • Improve user experience without increasing costs

​

Q5: How to handle sensitive data?

1. Use Environment Variables:
   • Don’t hardcode API Keys in code
   • Use Dify’s environment variable feature
2. Configure Access Control:
   • Set application access permissions
   • Enable authentication for API calls
3. Audit Logs:
   • Regularly check application logs
   • Monitor abnormal access patterns

​

Best Practices

​

1. Prompt Engineering

# Role Definition
You are a professional [role description]

# Task Objective
You need to help users [task description]

# Output Requirements
- Requirement 1
- Requirement 2
- Requirement 3

# Input Information
{{user_input}}

​

2. Knowledge Base Management

• Chunking Strategy: Set reasonable document chunk size (recommended 500-1000 characters)
• Metadata Tagging: Add metadata to documents for easier retrieval
• Regular Updates: Keep knowledge base content up-to-date

​

3. Error Handling

• Friendly Messages: Provide clear error messages to users
• Fallback Strategy: Switch to backup model when primary fails
• Retry Mechanism: Auto-retry for temporary errors

​

4. Performance Monitoring

• Set Alerts: Alert for low balance, high error rates
• Regular Analysis: Analyze usage data weekly/monthly
• Continuous Optimization: Adjust configuration based on data

​

Use Case Examples

​

1. Intelligent Customer Service

• Model: gpt-4o-mini (cost-effective)
• Knowledge Base: Product docs, FAQ
• Features: Auto-answer common questions, escalate complex issues to human

​

2. Content Creation Assistant

• Model: gpt-4o or claude-sonnet-4-5 (high quality)
• Features: Article generation, rewriting, polishing
• Parameters: Temperature=0.8 (enhance creativity)

​

3. Code Assistant

• Model: claude-sonnet-4-5 (excellent for code)
• Features: Code generation, explanation, debugging
• Knowledge Base: Project docs, API docs

​

4. Data Analysis Assistant

• Model: gpt-4o (strong reasoning ability)
• Tools: Python code execution, data visualization
• Features: Data analysis, report generation

​

Features

• 🤖 Quickly Build AI Apps - Create powerful AI applications without coding
• 📚 Knowledge Base Enhancement - RAG technology lets AI answer based on your data
• 🔧 Flexible Workflows - Visually orchestrate complex AI logic
• 🎯 Precise Prompt Management - Version control and A/B testing
• 📊 Complete Monitoring & Analytics - Understand app usage and performance
• 🔌 Multiple Integration Methods - API, embedded, WebApp, and more
• 👥 Team Collaboration - Support multi-user collaborative development
• 🌐 Multi-model Support - Flexibly switch between different AI models

​

Support & Help

• 📚 OneAster Documentation
• 📚 Dify Official Documentation
• 💬 Discord Community
• 🐦 Twitter @oneaster_
• 📧 Technical Support: [email protected]