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 ቁልፎች ገጽ ላይ ያውጡ። በዚያው ገጽ ቁልፉን ማስወገድና የአጠቃቀም ወሰኑን ማስተዳደር ይችላሉ። ከታች ያለውን ቅደም ተከተል በመከተል ለጥያቄዎች የሚጠቀሙበትን አንድ ቁልፍ ያገኛሉ።
- https://platform.clevi.net/account/login ላይ ይግቡ ወይም መለያ ይፍጠሩ።
- https://clevi.app/cloud ላይ የሥራ ቦታ ያክሉ።
- https://clevi.app/cloud/keys ይሂዱ።
- አዲስ ቁልፍ አውጥተው ዋጋውን ይቅዱ።
- የተቀዳውን ዋጋ በአካባቢ ተለዋዋጭ ውስጥ ያስቀምጡ።
በዚህ ሰነድ ምሳሌዎች ውስጥ ባለው sk-... ቦታ ያወጡትን ቁልፍ ያስገቡ። ከታች ባለው ትእዛዝ በአካባቢ ተለዋዋጭ ውስጥ ካስቀመጡት፣ ቀጣዮቹን ምሳሌዎች በቀጥታ ቀድተው ማስኬድ ይችላሉ።
export CLEVI_API_KEY="sk-..."ሞዴል መምረጥ
በጥያቄው አካል ያለውን model መስክ ከታች ባሉት ስሞች በትክክል ይሙሉ። ሁለቱም ሞዴሎች ተመሳሳይ አድራሻና ተመሳሳይ የጥያቄ ቅርጸት ይጠቀማሉ፤ ጽሑፍና ምስሎችንም እንደ ግብዓት ይቀበላሉ።
- cip-5.5-im
- cip-5.5-mm
| የሞዴል ID | መጠን | የግብዓት ገደብ | ከፍተኛ ውጤት | ተስማሚ ሥራ |
|---|---|---|---|---|
| cip-5.5-im | 360B | 256K | 64K | ዓላማና ወሰን ግልጽ የሆነ ሥራ። የምላሽ ፍጥነትና የማስኬጃ አቅምን ቅድሚያ ይሰጣል። |
| cip-5.5-mm | 800B | 512K | 64K | ብዙ ምንጮችንና ሁኔታዎችን የሚያጣምር ውስብስብ ሥራ። ረጅም አውድ ትንተናና ባለብዙ ደረጃ ኤጀንቶች ላይ ይጠቀሙበታል። |
በመለያዎ ላይ በትክክል ሊጠሩ የሚችሉ ሞዴሎችን የሚወስነው በፕሌይግራውንድ ያለው የሞዴሎች ዝርዝርና 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 ዋጋ ቅድሚያ ያገኛል።
| ስም | ቅርጸት | አስፈላጊ | መግለጫ |
|---|---|---|---|
| model | string | አዎ | cip-5.5-im ወይም cip-5.5-mm |
| messages | array | አዎ | የውይይት መልዕክት ነገሮች ድርድር። ቢያንስ 1 መልዕክት |
| messages[].role | string | አዎ | ከsystem · user · assistant አንዱ |
| messages[].content | string | አዎ | የመልዕክቱ አካል |
| stream | boolean | አይ | true ከሆነ ምላሹን ወደ Server-Sent Events ክፍሎች በመከፋፈል ይቀበላል |
| max_tokens | integer | አይ | በምላሹ ውስጥ የሚመነጩ ከፍተኛው የቶከኖች ብዛት |
| temperature | number | አይ | ዋጋው ከፍ ባለ መጠን በተመሳሳይ ጥያቄ የተለያዩ ምላሾች የመጡበት ዕድል ይጨምራል |
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ን ይመዝግቡ።
| ኮድ | ትርጉም | መፍትሔ |
|---|---|---|
| 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 ተኳሃኝ መንገድ፣ የኢምቤዲንግና የድምጽ መንገዶች፣ የስትሪሚንግ ደንቦች
- የስህተት ኮዶች፦ ሙሉ የሁኔታ ኮዶች ሰንጠረዥ እና የዳግም ሙከራ ደንቦች
