مروری در یک نگاه

این سند نقطه شروع مستندات توسعه‌دهندگان CLEVI است. اجزای Clevi-X-Platform، دو مدلی که می‌توان با API فراخوانی کرد، روش احراز هویت و قالب درخواست و پاسخ را یکجا مرور می‌کند. درخواست‌ها و پاسخ‌ها از قالب OpenAI Chat Completions پیروی می‌کنند؛ بنابراین برای اتصال، در OpenAI SDK موجود فقط دو مقدار base_url و api_key را تغییر دهید. فرایند دنبال‌کردن مراحل تا نخستین فراخوانی، بدون نصب، در سند Quick Start آمده است.

اجزای پلتفرم

Clevi-X-Platform مدل‌ها، عامل‌ها، پایگاه داده معنایی و هوش مصنوعی فیزیکی را در یک محیط اجرا قرار می‌دهد. در میان این موارد، چیزی که توسعه‌دهندگان اکنون مستقیماً از طریق HTTP فراخوانی می‌کنند، لایه مدل است. سایر لایه‌ها در داخل پلتفرم و کنسول اجرا می‌شوند و API عمومی تا محدوده نشان‌داده‌شده در جدول زیر در دسترس است.

مجموعه مدل‌ها

در فیلد model بدنه درخواست، یکی از دو نام زیر را عیناً وارد کنید. هر دو مدل از آدرس، احراز هویت و قالب درخواست یکسانی استفاده می‌کنند.

• cip-5.5-im
• cip-5.5-mm

cip-5.5-im

اسناد، تصاویر، نقشه‌ها و داده‌های کاری را بر اساس واحدهای معنایی به یکدیگر متصل می‌کند تا نتایج جست‌وجو و ساختار دانش ایجاد شود. از همین مدل برای تفسیر ورودی در مراحل برنامه‌ریزی و برنامه‌ریزی مجدد Physical AI نیز استفاده می‌شود. شناسه داخلی RB-IM است و در API فقط نام cip-5.5-im معتبر است.

cip-5.5-mm

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

انتخاب مدل

مدل‌های دیگر

این پلتفرم مدل‌های زیر را نیز شامل می‌شود. از آنجا که شکل استقرار و مسیر دسترسی آن‌ها متفاوت است، نام‌های API عمومی به‌صورت جداگانه اعلام می‌شوند.

اطلاعات پایه و احراز هویت

کلیدها در سطح workspace صادر می‌شوند و در هر درخواست، با پیشوند Bearer در هدر Authorization قرار می‌گیرند. با شش مقدار جدول زیر، تنظیمات لازم برای اولین فراخوانی تکمیل می‌شود.

sk-... در جدول‌ها و مثال‌ها محلی برای وارد کردن کلید صادرشده است. با قرار دادن آن در متغیر محیطی با دستور زیر، می‌توانید مثال‌های این سند را بدون تغییر کپی و اجرا کنید.

export CLEVI_API_KEY="sk-..."

POST /api/services/v1/aiservice/openai/v1/chat/completions

یک آرایه پیام و نام مدل را دریافت می‌کند و یک پیام تولیدشده توسط مدل را در آرایه choices بازمی‌گرداند. آدرس کامل https://platform.clevi.net/api/services/v1/aiservice/openai/v1/chat/completions است. messages باید حداقل شامل 1 شیء پیام باشد و هر شیء دارای role و content است.

curl https://platform.clevi.net/api/services/v1/aiservice/openai/v1/chat/completions \
  -H "Authorization: Bearer $CLEVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cip-5.5-mm",
    "messages": [
      {"role": "system", "content": "사내 문서를 요약하는 도우미로 답한다."},
      {"role": "user", "content": "이 API 의 인증 방식을 한 문장으로 설명해 줘."}
    ]
  }'

# pip install openai
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CLEVI_API_KEY"],
    base_url="https://platform.clevi.net/api/services/v1/aiservice/openai/v1",
)

completion = client.chat.completions.create(
    model="cip-5.5-mm",
    messages=[
        {"role": "system", "content": "사내 문서를 요약하는 도우미로 답한다."},
        {"role": "user", "content": "이 API 의 인증 방식을 한 문장으로 설명해 줘."},
    ],
)

print(completion.choices[0].message.content)

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CLEVI_API_KEY,
  baseURL: "https://platform.clevi.net/api/services/v1/aiservice/openai/v1",
});

const completion = await client.chat.completions.create({
  model: "cip-5.5-mm",
  messages: [
    { role: "system", content: "사내 문서를 요약하는 도우미로 답한다." },
    { role: "user", content: "이 API 의 인증 방식을 한 문장으로 설명해 줘." },
  ],
});

console.log(completion.choices[0].message.content);

{
  "id": "chatcmpl-7d21b4e0",
  "object": "chat.completion",
  "created": 1755500000,
  "model": "cip-5.5-mm",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Authorization 헤더에 Bearer 와 발급받은 API 키를 넣어 인증합니다."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 24,
    "total_tokens": 62
  }
}

فیلدهای پاسخ

پاسخ از شش فیلد در سطح بالا تشکیل شده است. متن تولیدشده در نخستین عنصر آرایه choices قرار دارد و تعداد توکن‌های استفاده‌شده در usage است.

خطا

درخواست‌های ناموفق علت را با کد وضعیت HTTP اعلام می‌کنند. ابتدا راهکارهای زیر را بررسی کنید و اگر همان کد تکرار شد، id پاسخ و زمان درخواست را ثبت کنید.

انواع استقرار

از یک مدل یکسان در دو حالت API ابری و نصب در محل استفاده می‌شود. قالب درخواست و روش احراز هویت در هر دو حالت یکسان است، اما آدرس و صفحه مدیریت کلید متفاوت است.

حاکمیت داده

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

• کنترل مبتنی بر مجوز — مجوزهای دسترسی و کلیدها در سطح فضای کاری تفکیک می‌شوند.
• فضاهای کاری ایزوله — داده‌ها بین فضاهای کاری با یکدیگر ترکیب نمی‌شوند.
• اتصال به داده‌های لحظه‌ای — داده‌های متصل به سیستم‌های خارجی در زمان جست‌وجو دریافت می‌شوند.
• نگهداری سوابق بر اساس فرایند — سوابق بر اساس هر کار اجراشده ثبت می‌شوند.

ترتیب شروع

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

1. در https://platform.clevi.net/account/login وارد شوید یا حسابی ایجاد کنید.
2. در https://clevi.app/cloud یک فضای کاری اضافه کنید.
3. در https://clevi.app/cloud/keys یک کلید ایجاد کنید و آن را در متغیرهای محیطی ذخیره کنید.
4. در https://clevi.app/cloud/playground پاسخ‌های cip-5.5-im و cip-5.5-mm را مقایسه کنید.
5. نمونه درخواست را از مستندات Quick Start کپی کنید و اولین فراخوانی را ارسال کنید.

ایجاد فضای کاری

ایجاد کلید API

باز کردن پلی‌گراند