Документация API

Что мы поддерживаем из API?

Мы специализируемся на текстовых нейросетях.

В первую очередь мы поддерживаем только часть OpenAI API, касающуюся текстовых нейросетей – зато для самых разных нейросетей (chat completions).

Также мы поддерживаем

• v1/embeddings – модель для создания текстовых эмбеддингов
• chat completions для vision-нейросетей
• генерации картинок,
• audio/transcriptions (speech to text)
• получение баланса и статуса аккаунта пользователя
• генерации голоса (TTS),

В планах поддержка:

• поискового API (не OpenAI)

Нет планов на поддержку:

• кастомных ассистенты и пр. – но вы можете использовать наш пример реализации RAG (поиска по документам), если вам нужна такая функциональность.

Мы не поддерживаем

• решения с сайта OpenAI (хотя для них есть аналоги)

Механика доступа по API

Поддерживается стандартный доступ по API OpenAI – вы можете использовать любые программы для доступа по нему.

Не забудьте указать следующие кастомные параметры – URL точки доступ и имя модели:

URL: https://api.vsegpt.ru/v1/chat/completions

• В зависимости от программы, это может быть https://api.vsegpt.ru/v1 или ещё что-то, см. примеры в Руководстве по подключению сторонних инструментов

также поддерживается старый URL на другом порту https://api.vsegpt.ru:6070/, который можно увидеть в некоторых примерах подключения

model: id модели из списка моделей

• Вы можете поменять только ID модели при запросе и перенаправить запрос к Antropic Claude, Google или опенсорс моделям, не меняя остальные поля в запросе. Мы поддерживаем единый интерфейс для всех моделей.
• Допускается указание стандартных идентификаторов gpt-3.5-turbo, gpt-4 – они будут автоматически преобразованы в соответствующие полные ID моделей OpenAI в большинстве случаев.
• Также возможно автоматическое преобразование ваших моделей в новые идентификаторы, если вы настроите маппинг моделей в Настройках

Пример вызова API (Python)

Новая библиотека (openai=1.x)

from openai import OpenAI

client = OpenAI(
    api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
    base_url="https://api.vsegpt.ru/v1",
)

prompt = "Напиши последовательно числа от 1 до 10"

messages = []
#messages.append({"role": "system", "content": system_text})
messages.append({"role": "user", "content": prompt})

response_big = client.chat.completions.create(
    model="anthropic/claude-3-haiku", # id модели из списка моделей - можно использовать OpenAI, Anthropic и пр. меняя только этот параметр
    messages=messages,
    temperature=0.7,
    n=1,
    max_tokens=3000, # максимальное число ВЫХОДНЫХ токенов. Для большинства моделей не должно превышать 4096
    extra_headers={ "X-Title": "My App" }, # опционально - передача информация об источнике API-вызова
)

#print("Response BIG:",response_big)
response = response_big.choices[0].message.content
print("Response:",response)

Подробнее: openai пакет на Github

Старая библиотека (openai=0.28.1)

Требуется pip install openai==0.28.1

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

prompt = "Напиши последовательно числа от 1 до 10"

messages = []
#messages.append({"role": "system", "content": system_text})
messages.append({"role": "user", "content": prompt})

response_big = openai.ChatCompletion.create(
    model="anthropic/claude-instant-v1", # id модели из списка моделей - можно использовать OpenAI, Anthropic и пр. меняя только этот параметр
    messages=messages,
    temperature=0.7,
    n=1,
    max_tokens=3000, # максимальное число ВЫХОДНЫХ токенов. Для большинства моделей не должно превышать 4096
    headers={ "X-Title": "My App" }, # опционально - передача информация об источнике API-вызова    
)

#print("Response BIG:",response_big)
response = response_big["choices"][0]["message"]
print("Response:",response)

Генерация Embedding (openai=0.28.1)

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

response_big = openai.Embedding.create(
    model="text-embedding-ada-002",
    input="function add(a, b) { return a + b; }",
)

print("Response BIG:",response_big)
res = response_big["data"][0]["embedding"]

Embedding в LangChain

В model указывается ID эмбеддингов из списка моделей (по умолчанию 'text-embedding-ada-002', и это будет обработано)

from langchain_openai import OpenAIEmbeddings

model = OpenAIEmbeddings(model="text-embedding-3-large", openai_api_base = "https://api.vsegpt.ru/v1/")

Ссылка на документацию: https://api.python.langchain.com/en/latest/embeddings/langchain_openai.embeddings.base.OpenAIEmbeddings.html

Vision-модель (openai=0.28.1)

Вариант с указанием картинки по URL (если картинка не будет найдена, или будет заблокирована, получите ошибку в духе openai.error.InvalidRequestError: Unknown MIME type)

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What you think the person in the image is doing?"},
                {
                    "type": "image_url",
                    "image_url": "https://img-s-msn-com.akamaized.net/tenant/amp/entityid/AA18Lnc8.img?w=1920&h=1080&q=60&m=2&f=jpg",
                },
            ],
        }
    ]

response_big = openai.ChatCompletion.create(
    model="vis-google/gemini-pro-vision",
    messages=messages,
    temperature=0.8,
    n=1,
    max_tokens=300,
)

#print("Response BIG:",response_big)
response = response_big["choices"][0]["message"]
print("Response:",response)

Вариант с загрузкой картинки из локального файла

import openai
import base64

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")


openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

base64_image = encode_image("Einstein.jpg")
messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What you think the person in the image is doing?"},
                {
                    "type": "image_url",
                    "image_url": f"data:image/jpeg;base64,{base64_image}",
                },
            ],
        }
    ]

response_big = openai.ChatCompletion.create(
    model="vis-google/gemini-pro-vision",
    messages=messages,
    temperature=0.8,
    n=1,
    max_tokens=300,
)

#print("Response BIG:",response_big)
response = response_big["choices"][0]["message"]
print("Response:",response)

Генерация изображения (openai=0.28.1)

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

response_big = openai.Image.create(
    model="dall-e-2",
    prompt="An astronaut riding the horse on the Moon.",
    n=1,
    size="1024x1024",
    quality="standard"
)

print(response_big)

Распознавание речи (openai=0.28.1)

import openai

openai.api_key = "sk-XXXXXXXXXXXXXXXX" # ваш ключ в VseGPT после регистрации

openai.api_base = "https://api.vsegpt.ru/v1"

with open("test_rec.mp3", "rb") as audio_file:
    transcript = openai.Audio.transcribe(
        file = audio_file,
        model = "stt-openai/whisper-1",
        response_format="text",
        language="ru",
    )
print(transcript.get("text"))

Генерация речи (Text-to-Speech) (openai=1.x)

from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="sk-XXXXXXXXXXXXXXXX", # ваш ключ в VseGPT после регистрации
    base_url="https://api.vsegpt.ru/v1",
)

speech_file_path = Path(__file__).parent / "speech.mp3"
response = client.audio.speech.create(
    model="tts-openai/tts-1",
    voice="nova", # поддерживаются голоса alloy, echo, fable, onyx, nova и shimmer
    input="Сегодня на улице очень жарко, не так ли?",
    # response_format="wav" # другой формат, при необходимости
)

response.write_to_file(speech_file_path)

Получение баланса (Python)

Получение баланса должно быть включено в настройках пользователя.

Также в настройках можно указать лимит средств, после которого API будет возвращать состояние 1 – yellow, предупреждение о возможно недостаточном количестве средств.

Возвращаемые данные:

{
 "status":"ok", # общий статус запроса
 "data":{
   "credits":"10.752448", # остаток на балансе
   "subscription_status":"ok", # статус подписки (должен быть ok - это означает, что подписка работает)
   "subscription_end":"2024-05-02 00:08:02" # формальное время окончания подписки, МСК
   "user_status":1, # статус пользователя 0 - green, 1 - yellow (меньше средств, чем указано в настройках), 2 - red (аккаунт неработоспособен). 
   "user_status_text":"Less than 500 credits on account. " # в случае, если status не 0 - причина.
}}

В принципе, достаточно отслеживать, чтобы user_status все время был 0. При любых ошибках и проблемах информация будет передана в поле user_status_text.

Пример запроса на Python

import requests
    import json
    response = requests.get(
        url="https://api.vsegpt.ru/v1/balance",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        },
    )

    # print(response.text)

    if response.status_code == 200:
        response_big = json.loads(response.text)
        if response_big.get("status") == "ok":
            credits = float(response_big.get("data").get("credits"))
        else:
            raise response_big.get("reason") # reason of error
    else:
        raise ValueError(str(response.status_code) + ": " + response.text)

Получение информации о доступных моделях

Обратитесь к URL https://api.vsegpt.ru/v1/models

Сторонние библиотеки и примеры на других языках (CURL, NodeJS)

Примеры для других языков программирования + CURL

Опенсорс примеры

Демо: телеграм-бот, отвечающий на вопросы

https://github.com/janvarev/Telegram-bot-vsegpt

Демо: RAG (поиск по серии документов с помощью эмбеддингов и векторной базы данных)

RAG – набор методов, направленных на то, чтобы
– а) выбирать из больших серий документов куски текста, соответствующих запросу пользователя
– б) добавлять эти релевантные куски в запрос к нейросети – чтобы нейросеть отвечала, исходя из реальной информации из документов.

Применяется в случае, когда у вас есть МНОГО документов, не влезающих в контекст и когда надо по ним отвечать на запросы пользователя.

Ниже приведен пример реализации с помощью векторной базы данных FAISS (работает на CPU, т.е. везде) и API VseGPT:
https://github.com/janvarev/demo_rag_vsegpt

Опенсорс: телеграм-бот Киберникто

Готовый к работе сложный телеграм-бот с множеством разных приемов для обработки входных сообщений.
Не демонстрационный
Поддерживается сторонним разработчиком, не VseGPT

https://github.com/solovieff/kibernikto

Ошибки API и их обработка

Общие принципы

Ошибка передается как код HTTP-запроса, а также во внутреннем JSON.

Общие принципы обработки кодов:

• 200 – все ОК 
• 4xx – что-то не ОК
• 504 – (EDGE_FUNCTION_INVOCATION_TIMEOUT) – сервер не смог ответить в нужное время. Попробуйте тупо переотправить запрос повторно. (Редко бывают периоды, когда сервера перегружены и таких ошибок бывает до 10%)
• 500 – ошибка сервера. Либо у нас всё плохо (маловероятно), либо вы некорректно сформировали запрос по API (очень вероятно)

Вебчат: Failed to fetch

Иногда вебчат не возвращает ошибку, а просто говорит “Failed to fetch” – что часто означает недоступность сервера API.

Пути решения:
1. Проверить, повторяется ли ошибка на другой модели. Если нет – значит, временная проблема именно с этой моделью; переключитесь пока на другую.
2. Проверьте, выключен ли VPN (наиболее частый случай). Часто коннект к VPN не пропускает запросы из вебчата.
3. Проверьте, повторяется ли ошибка в других браузерах (Chrome, Firefox). Если другие браузеры работают – значит, по каким-то причинам этот браузер или какое-то расширение не пропускают запросы.

Ошибка 400 (большинство обычных ошибок)

Основной код ошибки от нас.

Ошибка:
Expected maxTokens to be at least 1, received -15

Решение: такое возникает, когда ваш запрос превышает возможности обработки модели (выходит за размер её контекста).
Варианты решения:

• если вы долго ведете чат – начните новый чат! Чтобы нейросеть понимала контекст разговора, при запросе обрабатываются ВСЕ предыдущие сообщения чата как входные данные. Поэтому, если вы начинаете НОВУЮ ТЕМУ разговора, начинайте НОВЫЙ чат без истории диалога – это сэкономит вам массу средств.
• или перейдите на другую модель с более большим размером контекста

Ошибка:
{ "error": { "message": "max_tokens is too large: 10616. This model supports at most 4096 completion tokens, whereas you provided 10616.", "type": "invalid_request_error", "param": "max_tokens", "code": null } }

Решение: max_tokens (число токенов ожидаемой для генерации) для данной модели не может быть таким большим (даже если контекст у модели большой). Поменяйте его в настройках API-запроса или в чате

Ошибка: User with this API key not found

Решение: вы указали неверный или старый ключ API; пользователь с таким ключом не найден. Возьмите ваш ключ на https://vsegpt.ru/User/API

Ошибка: «Seems you use original OpenAI API key. This key will not work on this site; you need VseGPT API Key, you can get your own here: https://vsegpt.ru/User/API

Решение: вы используете оригинальный ключ API вместо нашего. Зайдите на https://vsegpt.ru/User/API и получите наш ключ.

Ошибка: This model is not available on your subscription plan. Please, upgrade your subscription plan to use it. Subscription plans: https://vsegpt.ru/Docs/Tariffs

Решение: Данная модель не доступна на вашем тарифном плане – измените тарифный план, чтобы получить к ней доступ. Список тарифных планов: https://vsegpt.ru/Docs/Tariffs

Ошибка:
{"error": {"message": "Potentially out of budget: 285->700, expected price 7.5825, but you have only 0.930400 on account. Pleae, add some money to balance to proceed: https://vsegpt.ru/User/Money", "code": 400} }

Решение: ошибка показывает, что ожидаемая стоимость запроса на данную модель превышает средства на вашем аккаунте. Пополните баланс или переключитесь на другую модель.

Ошибка:
InvalidRequestError: Exceeded soft user limit per query: 47972->700, expected price 11.0037, but your limit is 10.000. If you still want to process query, adjust limit in your settings on website: https://vsegpt.ru/User/SettingsModels

Решение: ошибка показывает, что ожидаемая стоимость запроса на данную модель превышает пользовательский лимит на 1 запрос на вашем аккаунте. Если вы по-прежнему хотите провести запрос, вы можете настроить ваш лимит по ссылке https://vsegpt.ru/User/SettingsModels

Ошибка 403

Ваш запрос был заблокирован из-за того, что он нарушает политику ToS модерации выбранной модели по какой-то тематике. Вам надо отредактировать его, чтобы он не нарушал, либо использовать модель без модерации.

Ошибка 429

Вы отправляете запросы слишком часто. Допускается отправка запросов с одного аккаунта не чаще 1 раза в 2 секунды (на тарифе FAST – больше)

(Также подобное поведение может быть у вышестоящих провайдеров для отдельных сетей с ограничением числа запросов в секунду)

Ошибка 500, 502 (EDGE_FUNCTION_INVOCATION_FAILED или INTERNAL_SERVER_ERROR или пусто)

Два варианта:

• Сервер временно недоступен, какие-то проблемы у нас (маловероятно)
• Вы некорректно отправляете API запрос. EDGE_FUNCTION_INVOCATION_FAILED возвращает наш вышестоящий провайдер, означает, что с вызовом API что-то не так, но что именно, сказать невозможно. Попробуйте отладить API-запрос.

Ошибка 504 (EDGE_FUNCTION_INVOCATION_TIMEOUT)

Она же: EDGE_FUNCTION_INVOCATION_TIMEOUT с разными комментариями

Означает, что вышестоящий провайдер (у которого мы берем доступ) не может обработать запрос из-за таймаута (т.е. скорее всего перегружены сервера с моделями или другая проблема)

Решается на стороне вышестоящего провайдера, вам ничего делать не нужно.

Если вы находитесь в чате – просто перегенерируйте сообщение, чаще всего запрос пройдет.

Если по API – то отправьте запрос повторно, чаще всего запрос пройдет.

Особенности реализации

Поддерживаемые endpoints

– chat/completions
– models (для получения информации о моделях)
– embeddings
– images/generations
– audio/transcriptions

Поддержка function calls

У нас добавлена поддержка function calling вызовов OpenAI – в том числе для части опенсорс моделей!
https://openai.com/blog/function-calling-and-other-api-updates
https://cookbook.openai.com/examples/how_to_call_functions_with_chat_models

Такой вызов просит OpenAI модель вывести json, соответствующий одной из предложенных функций. Например, можно подать на вход функцию “get_current_weather” – и выходом модели будет json “get_current_weather” с параметрами, соответствующими текущему пользовательскому текстовому запросу (см. примеры по ссылке)

Поддерживаются модели:

• OpenAI openai/gpt-3.5-turbo, gpt4, и, возможно другие (ответ будет в элементе function_call)
• jondurbin/airoboros-l2–70b (ответ будет в элементе content)

Также на практике и множество других моделей поддерживают function calls (Claude и пр.), но их поддержка не задекларирована, так что используйте на свой страх и риск. У автора работали anthropic/claude-instant-v1, openchat/openchat-7b, gryphe/mythomax-L2–13b и пр.

Пример вызова:

#
    prompt = "What is the weather like in Boston?"

    messages = []
    #messages.append({"role": "system", "content": system_text})
    messages.append({"role": "user", "content": prompt})

    response = openai.ChatCompletion.create(

        model="openai/gpt-3.5-turbo",
        # model="jondurbin/airoboros-l2-70b",
        messages =messages,
        temperature=0.9,
        n=1,
        max_tokens = 1500,
        stream=stream,
        functions=[
            {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        ]
    )

Поддержка tools

Аналогично предыдущему.

Tool calls также поддерживаются моделями Anthropic Claude 3 в совместимом формате (в non-stream режиме точно)

Пример вызова:

#
    prompt = "What is the weather like in Boston?"

    messages = []
    #messages.append({"role": "system", "content": system_text})
    messages.append({"role": "user", "content": prompt})

    response = openai.ChatCompletion.create(

        model="openai/gpt-3.5-turbo",
        messages =messages,
        temperature=0.9,
        n=1,
        max_tokens = 1500,
        stream=False,
        tools = [{
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA",
                        },
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                    },
                    "required": ["location"],
                },
            },
        }
        ]
    )

n=1

При генерации на сервисе, как правило, мы НЕ позволяем генерировать сразу несколько вариантов текста или изображений – это усложняет управление моделями.

Поэтому при запросе принудительно устанавливается n=1 для числа генераций.

Неуказанные max_tokens в chat/completions

Согласно стандарту, вам нужно указывать max_tokens в запросе. max_tokens определяет максимальное количество токенов ответа модели.

Но на практике ряд endpoint, в том числе часть наших провайдеров позволяют его не указывать. Это позволяет не заморачиваться с расчетом размера контекста модели и пр. – однако при этом могут возникать странные проблемы (например, была история с генерацией в ответе 250к пробелов от модели Google – просто потому, что не был указан max_tokens, а модель сама не остановила генерацию)

Мы считаем, что указывать max_tokens крайне желательно, но выбор остается за вами. Настроить поведение API при отсутствующем max_tokens можно на странице настроек