Chat Completions

رابط سازگار با OpenAI دانا: پارامترها، streaming، هدرها و ساختار پاسخ

POST /v1/chat/completions رابط اصلی سازگار با OpenAI است. اگر کدی دارید که با openai SDK کار می‌کند، فقط base_url و کلید را عوض کنید.

POST https://api.dana.expert/v1/chat/completions

نمونه کامل

curl:

curl https://api.dana.expert/v1/chat/completions \
  -H "Authorization: Bearer $DANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dana-1",
    "messages": [
      {"role": "system", "content": "دستیار فارسی‌زبان هستید."},
      {"role": "user", "content": "پایتخت ایران کجاست؟"}
    ]
  }'

Python (openai SDK):

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DANA_API_KEY"],
    base_url="https://api.dana.expert/v1",
)

response = client.chat.completions.create(
    model="dana-1",
    messages=[
        {"role": "system", "content": "دستیار فارسی‌زبان هستید."},
        {"role": "user", "content": "پایتخت ایران کجاست؟"},
    ],
)
print(response.choices[0].message.content)

Node.js (openai SDK):

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DANA_API_KEY,
  baseURL: "https://api.dana.expert/v1",
});

const response = await client.chat.completions.create({
  model: "dana-1",
  messages: [
    { role: "system", content: "دستیار فارسی‌زبان هستید." },
    { role: "user", content: "پایتخت ایران کجاست؟" },
  ],
});
console.log(response.choices[0].message.content);

پارامترها

فقط دو پارامتر اجباری است:

پارامتر	نوع	توضیح
`model`	string	شناسه مدل، مثل `dana-1` یا `dana-1-fast`
`messages`	array	آرایه پیام‌های مکالمه

بقیه اختیاری‌اند:

پارامتر	نوع	توضیح
`stream`	boolean	پاسخ به شکل SSE؛ پیش‌فرض `false`
`max_tokens`	integer	سقف توکن خروجی
`max_completion_tokens`	integer	نام تازه‌تر همان `max_tokens`
`temperature`	number	تنوع خروجی، از ۰ تا ۲
`top_p`	number	nucleus sampling
`n`	integer	تعداد پاسخ‌های موازی
`stop`	string یا array	توالی‌های توقف
`seed`	integer	برای خروجی تکرارپذیرتر
`response_format`	object	مثلا حالت JSON
`tools`	array	تعریف ابزارها برای tool calling
`tool_choice`	string یا object	انتخاب اجباری یا خودکار ابزار
`parallel_tool_calls`	boolean	اجازه فراخوانی هم‌زمان چند ابزار
`frequency_penalty`	number	کم کردن تکرار واژه
`presence_penalty`	number	تشویق به موضوع تازه
`logprobs`	boolean	برگرداندن احتمال توکن‌ها
`top_logprobs`	integer	چند گزینه برتر در `logprobs`
`logit_bias`	object	دست بردن در شانس توکن‌های مشخص
`user`	string	شناسه کاربر نهایی برای پیگیری

پارامتری که در این فهرست نیست هم دور ریخته نمی‌شود؛ دانا آن را دست‌نخورده به موتور مدل می‌فرستد. سقف max_tokens هم یک حد بالای سمت سرور دارد و مقدار بزرگ‌تر تا همان حد کوتاه می‌شود.

ساختار پیام

{"role": "system", "content": "متن پیام"}

مقدار role یکی از system و user و assistant است.

هدرهای اختصاصی دانا

هدر	مقدار	کار
`X-Dana-Harness`	`none` یا `base` یا `agent`	پروفایل بهبود فارسی؛ پیش‌فرض `base`
`X-Dana-Effort`	`low` تا `max`	میزان تلاش مدل و سقف پیش‌فرض خروجی

مقدار نامعتبر روی هرکدام، 400 می‌گیرد.

Streaming

با "stream": true پاسخ به شکل رویدادهای SSE می‌آید:

curl https://api.dana.expert/v1/chat/completions \
  -H "Authorization: Bearer $DANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"dana-1","stream":true,"messages":[{"role":"user","content":"یک داستان کوتاه بگو"}]}'

هر رویداد یک خط data: است و جریان با [DONE] تمام می‌شود:

data: {"id":"chatcmpl-xyz","object":"chat.completion.chunk","choices":[{"delta":{"content":"یک"},"index":0}]}

data: [DONE]

آمار مصرف در رویداد پایانی جریان می‌آید، نه در تک‌تک تکه‌ها.

ساختار پاسخ

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "dana-1",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "تهران پایتخت ایران است."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 10,
    "total_tokens": 32
  }
}

مقدار finish_reason می‌گوید چرا تولید ایستاد. stop یعنی پاسخ کامل شد و length یعنی به سقف max_tokens خورده است. اگر پاسخ‌ها نصفه می‌مانند، سراغ همین فیلد بروید.

صفحه‌های مرتبط

شروع سریع - نخستین درخواست موفق
Messages - همین کار با رابط Anthropic
خطاها - هر کد خطا و راه‌حلش
قیمت و توکن - معنی usage