نکته

چنانچه به سرویس‌های متیس از داخل ایران دسترسی دارید از آدرس https://api.metisai.ir استفاده کنید. و چنانچه از سرویس‌هایی که ایران را تحریم کرده‌اند استفاده می‌کنید از https://api.tapsage.com برای استفاده از سرویس‌های متیس استفاده کنید(مانند Colab, یا Kaggle).

API ربات

در متیس امکان تعریف ربات‌های مختلف برای کاربردهای متنوع وجود دارد. در واقع راه ارتباط شما با مدل‌های متنی از طریق ربات‌ها می‌باشد. شما می‌توانید رباتی را بر روی یک مدل ساخته و برای آن دستورالعمل تعیین کنید. همچنین تمام ویژگی‌های دیگر را برای ربات تنظیم کنید. ویژگی‌های قابل تنظیم برای یک ربات در جدول زیر آمده‌اند:

ویژگی	نوع	توضیح	اجباری	پیش‌فرض
name	String	نام ربات	بله	-
instructions	String	دستورالعمل ربات (System Prompt)	خیر	null
providerConfig	ProviderConfig	تنظیمات مربوط به مدل هوش مصنوعی	بله	-
corpusIds	String Array	لیستی از شناسه پایگاه‌های دانش	خیر	null
summarizer	SummarizationConfig	تنظیمات مربوط به خلاصه‌ساز	خیر	null
functions	Array of BotFunction	لیستی از توابعی که ربات می‌تواند از آنها استفاده کند	خیر	null
description	String	توضیحات ربات(یادداشت برای شما)	خیر	null
avatar	StorageUrl	آدرس تصویر آواتار ربات	خیر	null
enabled	Boolean	فعال بودن یا نبودن ربات	بله	-
autoGenerateHeadline	Boolean	با فعال کردن این قابلیت به صورت خودکار برای هر گفتگو با ربات عنوان تولید می‌شود.	خیر	null
public	Boolean	با فعال بودن این قابلیت، امکان استفاده از ربات شما حتی بدون کلید API هم ممکن است.	خیر	false
memoryEnabled	Boolean	با فعال بودن این گزینه ربات شما کاربران و ویژگی‌های آنها را به خاطر می‌سپارد.	خیر	false
googleSearchEnabled	Boolean	با فعال کردن این قابلیت ربات به اینترنت متصل می‌شود.	خیر	false
ragTopK	Integer	تعداد نتایج برتر در بازیابی RAG	خیر	null
ragReranking	RerankingMeta	تنظیمات مربوط به ری‌رنکینگ RAG	خیر	null

بعد از ساخت ربات می‌توانید به راحتی در قالب گفتگو با ربات تعامل داشته باشید. همچنین ربات ساخته شده در پنل کاربری شما در متیس نیز قابل مشاهده است.

ساخت ربات

نمونه‌ای از درخواست برای ساخت ربات بدین شکل است:

POST /api/v2/bots

cURL
Python

curl --location 'https://api.metisai.ir/api/v2/bots' \
        --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
        --header 'content-type: application/json' \
        --data '{
            "name": "Metis Q/A Bot",
            "instructions": "You are bot which answers users question about Metis",
            "enabled": true,
            "public":false,
            "providerConfig": {
                "provider": {
                    "name": "openai_chat_completion",
                    "model": "gpt-4o-mini-2024-07-18"
                },
                "args": {
                    "temperature": 1,
                    "topP": 1,
                    "frequency_penalty": 0,
                    "presence_penalty": 0,
                    "max_tokens": 1000
                }
            }
        }'

import requests
import json

url = 'https://api.metisai.ir/api/v2/bots'

headers = {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'content-type': 'application/json'
}

data = {
    "name": "Metis Q/A Bot",
    "instructions": "You are bot which answers users question about Metis",
    "enabled": True,
    "public": False,
    "providerConfig": {
        "provider": {
            "name": "openai_chat_completion",
            "model": "gpt-4o-mini-2024-07-18"
        },
        "args": {
            "temperature": 1,
            "topP": 1,
            "frequency_penalty": 0,
            "presence_penalty": 0,
            "max_tokens": 1000
        }
    }
}

response = requests.post(url, headers=headers, json=data)

print(f"Status Code: {response.status_code}")
print(f"Response: {response.json()}")

خروجی درخواست به شکل زیر است:

{
  "id": "BOT_ID",
  "name": "Metis Q/A Bot",
  "instructions": "You are bot which answers users question about Metis",
  "providerConfig": {
    "provider": {
      "name": "openai_chat_completion",
      "model": "gpt-4o-mini-2024-07-18",
      "acceptImageAttachment": true,
      "acceptFileAttachment": true
    },
    "args": {}
  },
  "corpusIds": null,
  "summarizer": null,
  "functions": null,
  "description": "",
  "avatar": null,
  "enabled": true,
  "autoGenerateHeadline": false,
  "public": false,
  "memoryEnabled": false,
  "googleSearchEnabled": true,
  "createdAt": 1762343491598,
  "ragTopK": null,
  "ragReranking": null
}

ویرایش ربات

برای ویرایش ربات شما می‌توانید از درخواست زیر استفاده کنید. تمامی مقادیر مانند بخش ساخت ربات است و فقط کافی است مقادیر جدید را به آنها اختصاص دهید. خروجی این درخواست مانند درخواست ساخت ربات است.

PUT /api/v2/bots/{botId}

cURL
Python

curl --location --request PUT 'https://api.metisai.ir/api/v2/bots/{bot_id}' \
    --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
    --header 'Content-Type: application/json' \
    --data '{
        "name": "New Name",
        "enabled": true,
        "description": "New Description",
        "public":false,
        "instructions": null,
        "providerConfig": {
            "provider": {
                "name": "openai_chat_completion",
                "model": "gpt-4o-mini"
            },
            "args": {
                "temperature": 1,
                "topP": 1,
                "frequency_penalty": 0,
                "presence_penalty": 0,
                "max_tokens": 1000
            }
        }
    }'

 import requests

 bot_id = 'YOUR_BOT_ID_HERE'
 url = f'https://api.metisai.ir/api/v2/bots/{bot_id}'

 headers = {
     'Authorization': 'Bearer YOUR_API_KEY_HERE',
     'Content-Type': 'application/json'
 }

 data = {
     "name": "New Name",
     "enabled": True,
     "description": "New Description",
     "public": False,
     "instructions": None,
     "providerConfig": {
         "provider": {
             "name": "openai_chat_completion",
             "model": "gpt-4o-mini"
         },
         "args": {
             "temperature": 1,
             "topP": 1,
             "frequency_penalty": 0,
             "presence_penalty": 0,
             "max_tokens": 1000
         }
     }
 }

 response = requests.put(url, headers=headers, json=data)

 print(f"Status Code: {response.status_code}")
 print(f"Response: {response.json()}")

دریافت اطلاعات ربات

برای دریافت اطلاعات ربات کافی است آدرس زیر را فراخوانی کنید. خروجی این درخواست نیز مانند خروجی درخواست ساخت ربات است.

GET /api/v2/bots/{botId}

cURL
Python

curl 'https://api.metisai.ir/api/v2/bots/{botId}' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json'

import requests

bot_id = 'YOUR_BOT_ID_HERE'
url = f'https://api.metisai.ir/api/v2/bots/{bot_id}'

headers = {
'Authorization': 'Bearer YOUR_API_KEY_HERE',
'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

print(f"Status Code: {response.status_code}")
print(f"Response: {response.json()}")

دریافت لیست ربات‌ها

برای دریافت لیست ربات‌ها می‌توانید از درخواست زیر استفاده کنید. خروجی این درخواست به صورت لیستی از ربات‌ها می‌باشد.

GET /api/v2/bots/all

cURL
Python

curl 'https://api.metisai.ir/api/v2/bots/all' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE'

import requests

url = 'https://api.metisai.ir/api/v2/bots/all'

headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY_HERE'
}

response = requests.get(url, headers=headers)

print(f"Status Code: {response.status_code}")
print(f"Response: {response.json()}")

حذف ربات

برای حذف ربات کافی است درخواست زیر را فراخوانی کنید.

DELETE /api/v2/bots/{botId}

cURL
Python

curl --location --request DELETE 'https://api.metisai.ir/api/v1/bots/{botId}' \
     --header 'Authorization: Bearer YOUR_API_KEY_HERE'

import requests

bot_id = 'YOUR_BOT_ID_HERE'
url = f'https://api.metisai.ir/api/v1/bots/{bot_id}'

headers = {
'Authorization': 'Bearer YOUR_API_KEY_HERE'
}

response = requests.delete(url, headers=headers)

print(f"Status Code: {response.status_code}")
print(f"Response: {response.text}")

مثال‌ها

ربات متصل به API آب‌وهوا

در ادامه نمونه‌ای کامل از ساخت یک ربات که قابلیت دریافت وضعیت آب و هوا را دارد آورده شده است. شما در این مثال با نحوه‌ی اتصال ربات با قابلیت فانکشن متیس آشنا می‌شوید:

POST /api/v2/bots

cURL
Python

curl --location 'https://api.metisai.ir/api/v2/bots' \
        --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
        --header 'content-type: application/json' \
        --data '{
            "name": "Weather Assistant Bot",
            "instructions": "You are a helpful weather assistant. When users ask about weather conditions, use the weather_status function to get accurate weather information. Always ask for the city name and date if not provided.",
            "enabled": true,
            "public": false,
            "providerConfig": {
                "provider": {
                    "name": "openai_chat_completion",
                    "model": "gpt-4o-mini-2024-07-18"
                },
                "args": {
                    "temperature": 0,
                    "topP": 0,
                    "frequency_penalty": 0,
                    "presence_penalty": 0,
                    "max_tokens": 1000
                }
            },
            "functions": [
                {
                    "name": "weather_status",
                    "description": "Get weather status for a specific city and date",
                    "args": [
                        {
                            "name": "location",
                            "description": "The city name to fetch the weather for",
                            "type": "STRING",
                            "enumValues": [],
                            "required": true
                        },
                        {
                            "name": "date",
                            "description": "The date to fetch the weather for in YYYY-MM-DD format",
                            "type": "STRING",
                            "enumValues": [],
                            "required": true
                        }
                    ],
                    "url": "https://api.weather-service.com/forecast",
                    "method": "POST",
                    "headers": {
                        "Authorization": "Bearer weather-api-token-12345",
                        "Content-Type": "application/json"
                    }
                }
            ]
        }'

import requests

url = 'https://api.metisai.ir/api/v2/bots'

headers = {
'Authorization': 'Bearer YOUR_API_KEY_HERE',
'content-type': 'application/json'
}

data = {
"name": "Weather Assistant Bot",
"instructions": "You are a helpful weather assistant. When users ask about weather conditions, use the weather_status function to get accurate weather information. Always ask for the city name and date if not provided.",
"enabled": True,
"public": False,
"providerConfig": {
  "provider": {
      "name": "openai_chat_completion",
      "model": "gpt-4o-mini-2024-07-18"
  },
  "args": {
      "temperature": 0,
      "topP": 0,
      "frequency_penalty": 0,
      "presence_penalty": 0,
      "max_tokens": 1000
  }
},
"functions": [
  {
      "name": "weather_status",
      "description": "Get weather status for a specific city and date",
      "args": [
          {
              "name": "location",
              "description": "The city name to fetch the weather for",
              "type": "STRING",
              "enumValues": [],
              "required": True
          },
          {
              "name": "date",
              "description": "The date to fetch the weather for in YYYY-MM-DD format",
              "type": "STRING",
              "enumValues": [],
              "required": True
          }
      ],
      "url": "https://api.weather-service.com/forecast",
      "method": "POST",
      "headers": {
          "Authorization": "Bearer weather-api-token-12345",
          "Content-Type": "application/json"
      }
  }
]
}

response = requests.post(url, headers=headers, json=data)

print(f"Status Code: {response.status_code}")
print(f"Response: {response.json()}")

پس از ساخت این ربات، کاربران می‌توانند سوالاتی مانند "هوای تهران فردا چطور است؟" بپرسند و ربات به صورت خودکار از تابع weather_status برای دریافت اطلاعات دقیق آب و هوا استفاده خواهد کرد.

اتصال پایگاه‌های دانش به ربات

شما می‌توانید ربات خود را به پایگاه‌های دانش خود متصل کنید. پیش از این باید پایگاه دانش را ساخته باشید و به ID آنها دسترسی داشته باشید. در ادامه مثالی از رباتی که به دو پایگاه دانش متصل شده است را می‌بینید:

POST /api/v2/bots

cURL
Python

curl --location 'https://api.metisai.ir/api/v2/bots' \
        --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
        --header 'content-type: application/json' \
        --data '{
            "name": "Knowledge Base Assistant",
            "instructions": "You are a knowledgeable assistant that can answer questions based on information from company documentation and product manuals. Always cite your sources when providing information.",
            "enabled": true,
            "public": false,
            "corpusIds": ["CORPUS_ID_1", "CORPUS_ID_2"],
            "ragTopK": 5,
            "ragReranking": {
                "enabled": true,
                "threshold": 0.7
            },
            "providerConfig": {
                "provider": {
                    "name": "openai_chat_completion",
                    "model": "gpt-4o-mini-2024-07-18"
                },
                "args": {
                    "temperature": 0.3,
                    "topP": 0.9,
                    "frequency_penalty": 0,
                    "presence_penalty": 0,
                    "max_tokens": 2000
                }
            }
        }'

import requests

url = 'https://api.metisai.ir/api/v2/bots'

headers = {
'Authorization': 'Bearer YOUR_API_KEY_HERE',
'content-type': 'application/json'
}

data = {
"name": "Knowledge Base Assistant",
"instructions": "You are a knowledgeable assistant that can answer questions based on information from company documentation and product manuals. Always cite your sources when providing information.",
"enabled": True,
"public": False,
"corpusIds": ["CORPUS_ID_1", "CORPUS_ID_2"],
"ragTopK": 5,
"ragReranking": {
  "enabled": True,
  "threshold": 0.7
},
"providerConfig": {
  "provider": {
      "name": "openai_chat_completion",
      "model": "gpt-4o-mini-2024-07-18"
  },
  "args": {
      "temperature": 0.3,
      "topP": 0.9,
      "frequency_penalty": 0,
      "presence_penalty": 0,
      "max_tokens": 2000
  }
}
}

response = requests.post(url, headers=headers, json=data)

print(f"Status Code: {response.status_code}")
print(f"Response: {response.json()}")

API ربات

ساخت ربات​

ویرایش ربات​

دریافت اطلاعات ربات​

دریافت لیست ربات‌ها​

حذف ربات​

مثال‌ها​

ربات متصل به API آب‌وهوا​

اتصال پایگاه‌های دانش به ربات​

ساخت ربات

ویرایش ربات

دریافت اطلاعات ربات

دریافت لیست ربات‌ها

حذف ربات

مثال‌ها

ربات متصل به API آب‌وهوا

اتصال پایگاه‌های دانش به ربات