واجهة رسائل Anthropic NEW

نظرة عامة

واجهة رسائل Anthropic هي تنسيق بديل للطلب والاستجابة للتفاعل مع نماذج LLM Resayil. بينما تظل نقطة النهاية المتوافقة مع OpenAI /v1/chat/completions مدعومة بالكامل، توفر واجهة الرسائل واجهة مألوفة للمطورين الذين يستخدمون بالفعل منظومة Anthropic.

لماذا تستخدم واجهة الرسائل؟

• توافق فوري: استخدم Anthropic SDK الرسمي لـ Python أو TypeScript بتغيير عنوان URL الأساسي فقط.
• نفس الخلفية: تتوجه كلا نقطتَي النهاية إلى نفس النماذج، وتستخدم نفس نظام الرصيد، وتشترك في نفس المصادقة.
• استدعاء أدوات منظم: تدعم واجهة الرسائل تنسيق استخدام الأدوات Anthropic لاستدعاء الوظائف.
• بث مع أحداث: أحداث مُرسَلة من الخادم مع كتل أحداث مُصنَّفة (message_start، content_block_delta، إلخ).

المصادقة

تقبل واجهة الرسائل نفس طرق المصادقة لجميع نقاط نهاية LLM Resayil. يمكنك استخدام الترويسة القياسية Authorization: Bearer أو ترويسة x-api-key بأسلوب Anthropic.

الخيار الأول: Bearer Token (قياسي)

Authorization: Bearer YOUR_API_KEY

الخيار الثاني: ترويسة x-api-key (بأسلوب Anthropic)

x-api-key: YOUR_API_KEY

كلتا الطريقتين متكافئتان. ترويسة x-api-key مدعومة للتوافق مع Anthropic SDK الرسمي الذي يرسل بيانات الاعتماد بهذه الطريقة افتراضيًا.

الاستخدام الأساسي

أرسل طلب POST إلى /v1/messages مع جسم JSON يحتوي على اختيار النموذج والرسائل.

نقطة النهاية

POST https://llmapi.resayil.io/v1/messages

طلب نصي بسيط

curl -X POST https://llmapi.resayil.io/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "mistral",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

الاستجابة

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ],
  "model": "mistral",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 14,
    "output_tokens": 9
  }
}

تنسيق الطلب

مواصفات جسم الطلب الكاملة لـ POST /v1/messages.

رسالة النظام

على عكس تنسيق OpenAI حيث تكون رسالة النظام برسالة ذات "role": "system"، يستخدم تنسيق Anthropic حقل system في المستوى الأعلى:

{
  "model": "mistral",
  "max_tokens": 1024,
  "system": "You are a helpful assistant who speaks formally.",
  "messages": [
    {"role": "user", "content": "Greet me."}
  ]
}

محادثة متعددة الأدوار

{
  "model": "llama3.1",
  "max_tokens": 2048,
  "messages": [
    {"role": "user", "content": "What is machine learning?"},
    {"role": "assistant", "content": "Machine learning is a subset of AI..."},
    {"role": "user", "content": "Can you give me a practical example?"}
  ]
}

تنسيق الاستجابة

تُعيد الاستجابات غير المتدفقة كائن رسالة كاملاً.

مثال على استجابة كاملة

{
  "id": "msg_01A2B3C4D5E6F7G8H9I0J1K2",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here is a Python function that calculates factorial:\n\n```python\ndef factorial(n):\n    if n <= 1:\n        return 1\n    return n * factorial(n - 1)\n```"
    }
  ],
  "model": "mistral",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 22,
    "output_tokens": 48
  }
}

البث المباشر

اضبط "stream": true لاستلام الاستجابة كتدفق من أحداث مُرسَلة من الخادم (SSE). كل حدث له نوع event وحمولة data.

طلب البث

curl -X POST https://llmapi.resayil.io/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "mistral",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Write a haiku about coding."}
    ]
  }'

أنواع الأحداث

مثال على استجابة البث

event: message_start
data: {"type":"message_start","message":{"id":"msg_01ABC","type":"message","role":"assistant","content":[],"model":"mistral","stop_reason":null,"usage":{"input_tokens":15,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type":"ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Lines"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" of"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" code"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}

استدعاء الأدوات

تدعم واجهة الرسائل استدعاء الأدوات (الوظائف) باستخدام تنسيق استخدام أدوات Anthropic. عرِّف الأدوات في طلبك، وقد يستجيب النموذج بكتلة محتوى tool_use.

الخطوة الأولى: تعريف الأدوات

{
  "model": "mistral",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather for a given location.",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City and country, e.g. London, UK"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "Temperature unit"
          }
        },
        "required": ["location"]
      }
    }
  ],
  "messages": [
    {"role": "user", "content": "What is the weather in Kuwait City?"}
  ]
}

الخطوة الثانية: معالجة استجابة tool_use

عندما يقرر النموذج استخدام أداة، تتضمن الاستجابة كتلة محتوى tool_use:

{
  "id": "msg_01XYZ",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01ABC",
      "name": "get_weather",
      "input": {
        "location": "Kuwait City, Kuwait",
        "unit": "celsius"
      }
    }
  ],
  "stop_reason": "tool_use",
  "usage": {"input_tokens": 85, "output_tokens": 42}
}

الخطوة الثالثة: إرسال نتيجة الأداة

نفِّذ الأداة من جانبك وأرسل النتيجة مرة أخرى:

{
  "model": "mistral",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "What is the weather in Kuwait City?"},
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "id": "toolu_01ABC",
          "name": "get_weather",
          "input": {"location": "Kuwait City, Kuwait", "unit": "celsius"}
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01ABC",
          "content": "Currently 38C and sunny in Kuwait City."
        }
      ]
    }
  ]
}

معالجة الأخطاء

تتبع أخطاء واجهة الرسائل تنسيق أخطاء Anthropic:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: field required"
  }
}

مقارنة OpenAI و Anthropic: مقارنة نقاط النهاية

كلتا نقطتَي النهاية موجودتان على نفس الخلفية. فيما يلي مقارنة جنبًا إلى جنب:

أمثلة البرمجة

Python (Anthropic SDK)

ثبِّت Anthropic SDK الرسمي ووجِّهه إلى LLM Resayil:

pip install anthropic

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://llmapi.resayil.io/v1"
)

message = client.messages.create(
    model="mistral",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain quantum computing in simple terms."}
    ]
)

print(message.content[0].text)

Python (مع البث باستخدام Anthropic SDK)

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://llmapi.resayil.io/v1"
)

with client.messages.stream(
    model="mistral",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Write a short story about AI."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Node.js (Anthropic SDK)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://llmapi.resayil.io/v1'
});

const message = await client.messages.create({
  model: 'mistral',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'What are the benefits of TypeScript?' }
  ]
});

console.log(message.content[0].text);

cURL مع رسالة النظام

curl -X POST https://llmapi.resayil.io/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "llama3.1",
    "max_tokens": 2048,
    "system": "You are a senior software architect. Answer concisely.",
    "messages": [
      {"role": "user", "content": "When should I use microservices vs monolith?"}
    ]
  }'

الميزات المدعومة

ما هو مدعوم حاليًا وما هو غير مدعوم في تطبيق واجهة الرسائل لدينا:

دليل التكامل

إذا كنت تستخدم بالفعل Anthropic SDK، فإن التبديل إلى LLM Resayil يتطلب تغييرات طفيفة.

إعداد متغيرات البيئة

اضبط متغيرات البيئة التالية لتطبيقك:

ANTHROPIC_BASE_URL=https://llmapi.resayil.io/v1
ANTHROPIC_API_KEY=sk-your-llm-resayil-api-key

نظام الرصيد لمستخدمي Anthropic

يُخصَم الرصيد بطريقة متطابقة سواء استخدمت نقطة نهاية OpenAI أو Anthropic. استخدام الرموز المُبلَّغ عنه في الاستجابة (input_tokens و output_tokens) يُترجَم مباشرةً إلى استهلاك الرصيد بناءً على مستوى النموذج:

• النماذج الصغيرة (مثال: phi3): 0.5 رصيد لكل 1K رمز
• النماذج المتوسطة (مثال: mistral): 1.5 رصيد لكل 1K رمز
• النماذج الكبيرة (مثال: llama3.1): 3.0 رصيد لكل 1K رمز

تحقق من رصيدك على لوحة التحكم أو عبر توثيق الرصيد.

التبديل من Anthropic API الرسمي

إذا كنت تنقل مشروعك من Anthropic API الرسمي:

1. أنشئ حسابًا على LLM Resayil وولِّد مفتاح API.
2. غيِّر base_url إلى https://llmapi.resayil.io/v1.
3. استبدل مفتاح Anthropic API بمفتاح LLM Resayil API الخاص بك.
4. حدِّث model لأحد النماذج المتاحة (مثال: "mistral"، "llama3.1").
5. أزِل أي معاملات غير مدعومة (cache_control، كتل الصور).
6. اختبر تكاملك في بيئة التطوير على https://llmdev.resayil.io/v1.

استكشاف الأعطال

المشكلات الشائعة

الأسئلة الشائعة

هل يمكنني استخدام كلتا نقطتَي النهاية في نفس التطبيق؟

نعم. نقطتا نهاية OpenAI /v1/chat/completions و Anthropic /v1/messages متعايشتان بشكل مستقل. يمكنك استدعاء أيٍّ منهما باستخدام نفس مفتاح API. الرصيد مشترك بينهما.

هل أحتاج إلى مفتاح API منفصل لواجهة الرسائل؟

لا. مفتاح LLM Resayil API الحالي يعمل مع كلتا نقطتَي النهاية. لا يلزم أي تهيئة إضافية.

ما النماذج التي يمكنني استخدامها مع واجهة الرسائل؟

جميع النماذج المتاحة على LLM Resayil تعمل مع كلتا نقطتَي النهاية. أسماء النماذج هي نفسها (مثال: "mistral"، "llama3.1"). لاحظ أن أسماء نماذج Anthropic المحددة مثل "claude-3-sonnet" غير متاحة.

هل تكلفة الرصيد مختلفة؟

لا. يُحسَب الرصيد بطريقة متطابقة بغض النظر عن نقطة النهاية المستخدمة. نفس النموذج مع نفس عدد الرموز يكلف نفس الرصيد.

هل يمكنني إرسال صور أو ملفات PDF؟

ليس حاليًا. يُدعم فقط محتوى النصوص. سيُرفض إدخال الصور و PDF مع خطأ.

هل ترويسة anthropic-version مطلوبة؟

يُوصى بها لكنها ليست مطلوبة بالضرورة. إذا حُذفت، تستخدم واجهة API أحدث إصدار مدعوم. للاستخدام الإنتاجي، ثبِّتها على 2023-06-01 لسلوك متسق.