Developer guide

ፈጣን መጀመሪያ

ፈጣን መጀመሪያ

ይህ ሰነድ የCLEVI API ቁልፍ ከማውጣት ጀምሮ የመጀመሪያ ጥያቄዎን እስከመላክና ምላሽ እስከማግኘት ያለውን ሂደት ይሸፍናል። በአንድ አድራሻና በአንድ ቁልፍ cip-5.5-im እና cip-5.5-mmን ይጠራል፤ ጥያቄና ምላሹም የOpenAI Chat Completions ቅርጸትን ስለሚከተሉ፣ በሚጠቀሙበት OpenAI SDK ውስጥ base_url እና api_key የሚሉትን ሁለት እሴቶች ብቻ መቀየር ይበቃል። ለAnthropic SDK የሚሆነው መንገድና የኢምቤዲንግ እና የድምጽ መንገዶች የ API ጥሪ ማድረግ በሚለው ሰነድ ውስጥ ይገኛሉ።

API ቁልፍ ማውጣት

ቁልፉን ከCLEVI Cloud ኮንሶል የAPI ቁልፎች ገጽ ላይ ያውጡ። በዚያው ገጽ ቁልፉን ማስወገድና የአጠቃቀም ወሰኑን ማስተዳደር ይችላሉ። ከታች ያለውን ቅደም ተከተል በመከተል ለጥያቄዎች የሚጠቀሙበትን አንድ ቁልፍ ያገኛሉ።

  1. https://platform.clevi.net/account/login ላይ ይግቡ ወይም መለያ ይፍጠሩ።
  2. https://clevi.app/cloud ላይ የሥራ ቦታ ያክሉ።
  3. https://clevi.app/cloud/keys ይሂዱ።
  4. አዲስ ቁልፍ አውጥተው ዋጋውን ይቅዱ።
  5. የተቀዳውን ዋጋ በአካባቢ ተለዋዋጭ ውስጥ ያስቀምጡ።

በዚህ ሰነድ ምሳሌዎች ውስጥ ባለው sk-... ቦታ ያወጡትን ቁልፍ ያስገቡ። ከታች ባለው ትእዛዝ በአካባቢ ተለዋዋጭ ውስጥ ካስቀመጡት፣ ቀጣዮቹን ምሳሌዎች በቀጥታ ቀድተው ማስኬድ ይችላሉ።

export CLEVI_API_KEY="sk-..."

ሞዴል መምረጥ

በጥያቄው አካል ያለውን model መስክ ከታች ባሉት ስሞች በትክክል ይሙሉ። ሁለቱም ሞዴሎች ተመሳሳይ አድራሻና ተመሳሳይ የጥያቄ ቅርጸት ይጠቀማሉ፤ ጽሑፍና ምስሎችንም እንደ ግብዓት ይቀበላሉ።

  • cip-5.5-im
  • cip-5.5-mm
የሞዴል IDመጠንየግብዓት ገደብከፍተኛ ውጤትተስማሚ ሥራ
cip-5.5-im360B256K64Kዓላማና ወሰን ግልጽ የሆነ ሥራ። የምላሽ ፍጥነትና የማስኬጃ አቅምን ቅድሚያ ይሰጣል።
cip-5.5-mm800B512K64Kብዙ ምንጮችንና ሁኔታዎችን የሚያጣምር ውስብስብ ሥራ። ረጅም አውድ ትንተናና ባለብዙ ደረጃ ኤጀንቶች ላይ ይጠቀሙበታል።

በመለያዎ ላይ በትክክል ሊጠሩ የሚችሉ ሞዴሎችን የሚወስነው በፕሌይግራውንድ ያለው የሞዴሎች ዝርዝርና GET /models ምላሽ ነው። ሙሉ የሞዴሎች ዝርዝርና ለእያንዳንዱ ሞዴል የተፈቀዱ ጥሪዎች በሞዴሎች ሰነድ ውስጥ፣ የሚጠበቀው የሚቀነስ ክሬዲት መጠን ደግሞ በኮንሶሉ የአጠቃቀም ገጽ ላይ ይገኛል።

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

የመልዕክቶች ድርድርን እና የሞዴል ስምን ተቀብሎ፣ ሞዴሉ ያመነጨውን መልዕክት በchoices ድርድር ውስጥ አካቶ ይመልሳል። ሙሉ አድራሻው https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions ነው። የጥያቄው አካል application/json ሲሆን፣ ማረጋገጫው ደግሞ በAuthorization ራስጌ ውስጥ Bearer ቅድመ ቅጥያን ከቁልፉ ጋር በማስገባት ይከናወናል። ቁልፉን በX-API-Key ራስጌ መላክም ይቻላል፤ ሁለቱም ራስጌዎች ከተገለጹ ግን የX-API-Key ዋጋ ቅድሚያ ያገኛል።

የጥያቄ መለኪያዎች
ስምቅርጸትአስፈላጊመግለጫ
modelstringአዎcip-5.5-im ወይም cip-5.5-mm
messagesarrayአዎየውይይት መልዕክት ነገሮች ድርድር። ቢያንስ 1 መልዕክት
messages[].rolestringአዎከsystem · user · assistant አንዱ
messages[].contentstringአዎየመልዕክቱ አካል
streambooleanአይtrue ከሆነ ምላሹን ወደ Server-Sent Events ክፍሎች በመከፋፈል ይቀበላል
max_tokensintegerአይበምላሹ ውስጥ የሚመነጩ ከፍተኛው የቶከኖች ብዛት
temperaturenumberአይዋጋው ከፍ ባለ መጠን በተመሳሳይ ጥያቄ የተለያዩ ምላሾች የመጡበት ዕድል ይጨምራል
curl https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
  -H "Authorization: Bearer $CLEVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cip-5.5-im",
    "messages": [
      {"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}
    ]
  }'
import os
import requests

url = "https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions"

response = requests.post(
    url,
    headers={"Authorization": f"Bearer {os.environ['CLEVI_API_KEY']}"},
    json={
        "model": "cip-5.5-im",
        "messages": [{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
    },
    timeout=60,
)

print(response.json()["choices"][0]["message"]["content"])
const url =
  "https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions";

const response = await fetch(url, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CLEVI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "cip-5.5-im",
    messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

ይህ የምላሽ ምሳሌ ነው። የid፣ created እና usage ዋጋዎች በእያንዳንዱ ጥያቄ ይለያያሉ።

{
  "id": "chatcmpl-3f0a9c72",
  "object": "chat.completion",
  "created": 1755500000,
  "model": "cip-5.5-im",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "CLEVI API는 주소 하나로 여러 모델을 호출하는 채팅 완료 API입니다."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 19,
    "total_tokens": 40
  }
}

በOpenAI SDK መጠቀም

የOpenAI SDK base_urlን ወደ https://platform.clevi.net/api/v2/aiservice/openai/v1 ይቀይሩ እና CLEVI ቁልፍዎን በapi_key ውስጥ ያስገቡ። የቀረውን የጥሪ ኮድ እንዳለ ይተዉት።

# 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/v2/aiservice/openai/v1",
)

completion = client.chat.completions.create(
    model="cip-5.5-mm",
    messages=[{"role": "user", "content": "CLEVI 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/v2/aiservice/openai/v1",
});

const completion = await client.chat.completions.create({
  model: "cip-5.5-mm",
  messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
});

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

በስትሪሚንግ መቀበል

በጥያቄው አካል ውስጥ streamን true ካደረጉ፣ አገልጋዩ በServer-Sent Events ምላሽ ይሰጣል። ከመጀመሪያው ክፍል ጋር Content-Type: text/event-stream፣ Cache-Control: no-cache፣ X-Accel-Buffering: no ራስጌዎች ይላካሉ፤ ከዚያም በእያንዳንዱ ክፍል data: መስመር ውስጥ chat.completion.chunk ነገር ይካተታል። የመጨረሻው መስመር data: [DONE] ነው። ከታች ያሉት የPython እና TypeScript ምሳሌዎች በቀደመው ክፍል የፈጠሩትን client እንደዚያው ይጠቀማሉ።

curl -N https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
  -H "Authorization: Bearer $CLEVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cip-5.5-im",
    "messages": [{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
    "stream": true
  }'
stream = client.chat.completions.create(
    model="cip-5.5-im",
    messages=[{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")
const stream = await client.chat.completions.create({
  model: "cip-5.5-im",
  messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

የክፍል ምሳሌ።

data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{"content":"CLEVI"},"finish_reason":null}]}

data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{"content":" API는"},"finish_reason":null}]}

data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

በዥረት ማስተላለፉ ወቅት ስህተት ከተፈጠረ፣ ተመሳሳዩ የስህተት JSON በአንድ data: መስመር ይመጣል፣ እንዲሁም የHTTP ሁኔታ ኮዱ ይቀየራል።

ስህተት

ያልተሳካ ጥያቄ ምክንያቱን በHTTP ሁኔታ ኮድ ያሳውቃል። ከupstream 4xx·5xx ከተመለሰ፣ ያ ኮድ በቀጥታ ይተላለፋል። በሚከተለው ሰንጠረዥ ያለውን መፍትሔ በመጀመሪያ ያረጋግጡ፤ ተመሳሳዩ ኮድ በተደጋጋሚ ከታየ፣ የጥያቄውን ሰዓት፣ የላኩትን አካል እና X-Request-Idን ይመዝግቡ።

የHTTP ሁኔታ ኮድ
ኮድትርጉምመፍትሔ
400የጥያቄው ይዘት በትክክለኛው ቅርጸት አይደለምmodel እና messages መኖራቸውን፣ JSON መዘጋቱን ያረጋግጡ
401ቁልፉ የለም ወይም ጊዜው ያለፈበት ወይም የተሰረዘ ቁልፍ ነውበAPI ቁልፍ ማያ ገጽ ላይ የቁልፉን ሁኔታ ያረጋግጡ፣ እና Authorization ራስጌው Bearer በሚል መጀመሩን ይፈትሹ
403የሞዴሉን የመዳረሻ ፈቃድ የለዎትም፣ የአጠቃቀም ገደቡን አልፈዋል፣ ወይም ክሬዲት በቂ አይደለምምክንያቱን ለማወቅ error.message ይመልከቱ። ገደቡን በአጠቃላይ እይታ ውስጥ ከተመደበው የአጠቃቀም ገደብ፣ ቀሪ ሂሳቡንና ዕቅዱን ደግሞ ከዕቅድ እና ክሬዲት ይመልከቱ
404ሞዴሉ የለም፣ ወይም በዚህ ቁልፍ መዳረስ አይችሉም፣ ወይም መንገዱ የለምየሞዴሉ ስም በGET /models ምላሽ ውስጥ መኖሩን፣ አድራሻውም /api/v2/aiservice/openai/v1/chat/completions በሚል መጨረሱን ያረጋግጡ
429ከላይኛው አቅራቢ የፍጥነት ገደብ ጥሏልRetry-After ራስጌ ካለ፣ በዚያ ጊዜ መጠን ይጠብቁ፤ ከሌለ የዳግም ሙከራ ልዩነቱን በእጥፍ እያሳደጉ እንደገና ይላኩ
5xxየጌትዌይ ወይም የላይኛው አቅራቢ ጊዜያዊ ስህተት ነውየዳግም ሙከራ ልዩነቱን በእጥፍ እያሳደጉ እንደገና ይላኩ፤ ችግሩ ከተደጋገመ በእገዛ እና አግኙን ገጽ በኩል X-Request-Id አስገብተው ያሳውቁ

402 አይመለስም። ክሬዲት ማነስና የአጠቃቀም ገደብ ማለፍ እንደ 403 ይመጣሉ። የስህተት ይዘቱ ከታች ባለው ቅርጸት ሲሆን፣ ምክንያቱ በerror.message ውስጥ ይገኛል።

{"error":{"message":"API key is required.","type":"invalid_request_error"}}

በጥያቄው ውስጥ X-Request-Id ራስጌ ካካተቱ፣ ሲያገኙን በዚያ ዋጋ እንከታተለዋለን። ካልላኩት ሰርቨሩ ይመድበዋል።

ቀጣይ ደረጃዎች

የሞዴል ስሞችንና መለኪያዎችን በመቀያየር ውጤቶችን የሚያወዳድሩት በፕሌይግራውንድ ውስጥ ነው። አዲስ ቁልፍ መፍጠር ወይም መሰረዝ የሚችሉት በAPI ቁልፍ ማያ ገጽ ላይ ነው። ቀጥሎ ሊያነቧቸው የሚገቡ ሰነዶች፦

  • ሞዴሎች፦ ሙሉ የሞዴሎች ዝርዝር፣ የእያንዳንዱ ሞዴል ዝርዝር መግለጫ እና የተፈቀዱ ጥሪዎች
  • API መጠቀም፦ Anthropic ተኳሃኝ መንገድ፣ የኢምቤዲንግና የድምጽ መንገዶች፣ የስትሪሚንግ ደንቦች
  • የስህተት ኮዶች፦ ሙሉ የሁኔታ ኮዶች ሰንጠረዥ እና የዳግም ሙከራ ደንቦች

ፕሌይግራውንድን ይክፈቱ

የAPI ቁልፎችን ያስተዳድሩ

CLEVI

ቋንቋ እና ክልል

მანქანურად ნათარგმნი ენები მონიშნულია. ხელმისაწვდომობა გამოქვეყნებულ საიტის პაკეტს შეესაბამება.

136 ቋንቋዎች

የሚመከር

1

ምስራቃዊ እስያ

7

ደቡብ ምስራቅ እስያ

11

ደቡባዊ እስያ

18

መካከለኛው እስያ

5

መካከለኛው ምስራቅ እና ካውካሰስ

10

ምዕራብ አውሮፓ እና ደቡባዊ አውሮፓ

16

ዩናይትድ ኪንግደም እና አየርላንድ

4

ሰሜናዊ አውሮፓ

10

መካከለኛው አውሮፓ እና ባልካን

14

ምስራቅ አውሮፓ

5

ምስራቅ አፍሪካ

8

ምዕራባዊ አፍሪካ እና መካከለኛው አፍሪካ

9

ደቡባዊ አፍሪካ

8

አሜሪካ

5

ኦሺያንያ

5