Keural API

Panggil model yang didaftarkan dalam Keural dengan format OpenAI Chat Completions.

Base URL berbentuk https://<public API domain for each environment>/llm/v1. Domain API awam berbeza mengikut persekitaran, jadi semak dengan pentadbir.

Laluan embedding, penjanaan imej, suara, dan Responses API tidak disokong, dan API memulangkan 404.

Aliran penggunaanSalin pautan tajuk

PrasyaratSalin pautan tajuk

Menerbitkan kunci APISalin pautan tajuk

1. Dalam menu akaun, buka Tetapan → API. Dalam aplikasi desktop dan mudah alih, menu ini berada dalam kumpulan Alat.
2. Dalam tab API keys, pilih ruang kerja pemilik kunci (peribadi atau organisasi) dan Model ID.
3. Jika perlu, tetapkan Tarikh luput kunci baharu. Jika dibiarkan kosong, kunci sah sehingga dibatalkan.
4. Klik Terbitkan kunci, kemudian klik Salin kunci untuk menyalin kunci. Kunci penuh hanya dipaparkan sekali semasa diterbitkan dan tidak boleh dilihat semula selepas skrin ditutup.

• Kunci dipautkan kepada ruang kerja yang dipilih dan satu model. Penggunaan dikira atas nama orang yang menerbitkan kunci.
• Setiap ruang kerja dan model hanya boleh mempunyai satu kunci. Untuk kunci baharu, rotasi atau batalkan kunci sedia ada.
• Selepas diterbitkan semula, kunci sebelumnya serta-merta tidak boleh digunakan.
• Jika tiada model yang boleh diterbitkan, semak keterlihatan model, pelan, dan kebenaran API organisasi bersama pentadbir.

Kebenaran API ahli organisasiSalin pautan tajuk

Untuk pemilik dan pentadbir organisasi sahaja. Agar ahli boleh menerima kunci dalam ruang kerja organisasi, pentadbir mesti membenarkannya terlebih dahulu. Bagi ahli baharu dan sedia ada, akses disekat secara lalai.

Pengurusan organisasi → Organization API mengandungi tiga bahagian berikut. Jika menu ini tiada, ciri API dimatikan atau akaun anda tidak mempunyai kebenaran pengurusan organisasi.

Jika ahli keluar atau dikeluarkan daripada organisasi, kunci yang diterima melalui organisasi akan dibatalkan secara automatik.

Menyambung ke klienSalin pautan tajuk

Masukkan tiga nilai berikut dalam aplikasi yang serasi dengan OpenAI API (klien sembang, sambungan IDE, alat automasi, dan lain-lain).

1. Dalam tetapan aplikasi, tambah Sambungan serasi OpenAI (Connection).
2. Masukkan Base URL dan API Key, kemudian simpan.
3. Pilih model dalam senarai. Senarai hanya memaparkan satu model, iaitu model yang dipautkan kepada kunci.
4. Hantar mesej ringkas dan semak respons.

Format permintaan adalah seperti berikut.

Permintaan pertamaSalin pautan tajuk

export KEURAL_API_KEY='kunci_yang_diterbitkan'
export KEURAL_BASE_URL='https://<domain-api-awam-persekitaran>/llm/v1'
export MODEL_ID='model ID dari skrin penerbitan'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Helo.\"}]}"

Nilai model dalam badan permintaan mesti sama dengan model ID yang dipautkan kepada kunci. Jika ada awalan laluan seperti provider/model-ID, bahagian selepas / terakhir mesti sepadan. Jika tidak, API memulangkan 403. Dalam respons, model sentiasa berisi model ID kunci.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Helo."}],
)
print(res.choices[0].message.content)

Medan permintaan yang disokongSalin pautan tajuk

18 medan peringkat atas berikut sahaja diterima. Medan lain memulangkan 400. Medan pilihan yang bernilai null dianggap tidak dihantar.

MesejSalin pautan tajuk

• Mesej tool hanya membalas sekali untuk setiap id dalam tool_calls sebelumnya.
• Bahagian imej (image_url) hanya boleh dimasukkan dalam mesej user bagi model yang menerima imej. Gunakan alamat http atau https, atau data URI base64 format PNG, JPEG, GIF, atau WebP. detail ialah auto · low · high.

BadanSalin pautan tajuk

Jika peraturan badan dilanggar, hasilnya 400 dan param ialah body.

PenstrimanSalin pautan tajuk

Tambahkan "stream": true dalam permintaan untuk menerima respons melalui SSE. Chunk dihantar sebagai acara data: ..., dan penstriman berakhir dengan data: [DONE]. Jika "stream_options": {"include_usage": true} ditambah, satu chunk penggunaan token dihantar sebelum [DONE].

Apabila include_usage diisi, setiap chunk mengandungi usage: null, dan chunk penggunaan terakhir mempunyai choices sebagai tatasusunan kosong. Respons bukan penstriman hanya mengandungi usage jika jumlah token input dan output telah disahkan.

ID respons berformat chatcmpl-<x-request-id>. Setiap respons menyertakan pengepala x-request-id.

Jika ralat berlaku semasa penstriman, acara data: yang mengandungi JSON ralat dihantar, kemudian sambungan ditutup tanpa [DONE]. Jika satu chunk melebihi 1 MiB atau respons melebihi 16 MiB, penstriman berakhir dengan 503.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Helo.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

Had penggunaanSalin pautan tajuk

Permintaan dihadkan mengikut pengguna, organisasi, dan model, berdasarkan bilangan permintaan serentak, permintaan seminit (RPM), dan token seminit (TPM). Nilai sebenar berbeza mengikut persekitaran.

Token seminit ditolak terlebih dahulu apabila permintaan diterima. Input dikira 1 token bagi setiap 4 aksara Inggeris dan 1 token bagi setiap aksara lain. Satu imej dikira sebagai 2,000 token. Output ditolak sebanyak max_tokens (maksimum 4,096), jadi jika hanya had output yang diperlukan ditetapkan, baki had akan lebih besar.

Mengurus kunciSalin pautan tajuk

Dalam Tetapan → API → API keys, status kunci yang diterbitkan dipaparkan (Sah · Tamat tempoh · Dibatalkan). Kunci boleh dirotasi atau dibatalkan dari sini.

Kunci ialah rentetan 51 aksara yang bermula dengan krl_llm_. Setiap ruang kerja hanya boleh mempunyai satu kunci, dan jika sudah ada, kunci dirotasi dan bukannya diterbitkan baharu. Tarikh luput hanya boleh ditetapkan selepas hari ini.

Menyemak penggunaanSalin pautan tajuk

Permintaan API dan penggunaan token boleh disemak di dua tempat.

Syarat carianSalin pautan tajuk

Tetapkan syarat, kemudian klik Cari. Untuk menyemak permintaan terbaru, klik Muat semula.

Nilai yang dipaparkan pada skrinSalin pautan tajuk

• Julat carian yang digunakan: julat yang benar-benar dicari. Jika masa dikosongkan atau melebihi 90 hari, julat yang diselaraskan oleh pelayan dipaparkan.
• Bilangan permintaan dan Token input · Token output · Jumlah token: hanya nilai yang disahkan dijumlahkan. Token yang belum disahkan dipaparkan sebagai Belum disahkan, bukan 0.
• Senarai permintaan: setiap permintaan dipaparkan dalam satu baris dengan masa permintaan, Model ID, status permintaan, serta token input, output, dan jumlah. Setiap halaman memaparkan 20 permintaan. Gunakan Sebelum dan Seterusnya untuk bertukar halaman.

Klik Butiran permintaan pada baris untuk melihat nilai berikut.

Permintaan penstriman direkodkan penggunaannya walaupun stream_options.include_usage tidak dimasukkan. Jika permintaan terputus di tengah jalan, statusnya mungkin kekal sebagai Disahkan sebahagian atau Belum disahkan.

Format ralatSalin pautan tajuk

Ralat dipulangkan dalam format yang serasi dengan OpenAI.

{
  "error": {
    "message": "Penerangan ralat yang boleh dibaca manusia",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type ditentukan oleh kod status, dan code membezakan punca.

Penyelesaian masalahSalin pautan tajuk

Jika masalah berterusan, hubungi pentadbir dengan maklumat berikut. Kandungan kunci dan prompt jangan dihantar.

• Masa berlaku
• Model ID yang digunakan
• Nama dan versi aplikasi klien
• x-request-id daripada pengepala respons
• Mesej ralat yang dipaparkan pada skrin