From 34438228f2e27da36f78499c082bdfb6f219e849 Mon Sep 17 00:00:00 2001 From: Ace Data Cloud Dev Date: Mon, 5 Oct 2026 13:24:11 +0000 Subject: [PATCH] sync: adapt to Backend changes through b78c6e54085b --- ar/guides/claude/claude_messages.mdx | 173 ++++++++--------- ar/guides/openai/openai_embeddings.mdx | 68 +++---- ar/guides/platform/wework_bot.mdx | 56 ++++++ de/guides/claude/claude_messages.mdx | 169 +++++++++-------- de/guides/openai/openai_embeddings.mdx | 54 +++--- de/guides/platform/wework_bot.mdx | 56 ++++++ docs.json | 15 ++ el/guides/claude/claude_messages.mdx | 189 ++++++++++--------- el/guides/openai/openai_embeddings.mdx | 58 +++--- el/guides/platform/wework_bot.mdx | 56 ++++++ en/guides/claude/claude_messages.mdx | 153 +++++++-------- en/guides/openai/openai_embeddings.mdx | 42 ++--- en/guides/platform/wework_bot.mdx | 56 ++++++ es/guides/claude/claude_messages.mdx | 171 ++++++++--------- es/guides/openai/openai_embeddings.mdx | 56 +++--- es/guides/platform/wework_bot.mdx | 56 ++++++ fi/guides/claude/claude_messages.mdx | 165 ++++++++-------- fi/guides/openai/openai_embeddings.mdx | 60 +++--- fi/guides/platform/wework_bot.mdx | 56 ++++++ fr/guides/claude/claude_messages.mdx | 181 +++++++++--------- fr/guides/openai/openai_embeddings.mdx | 62 +++--- fr/guides/platform/wework_bot.mdx | 56 ++++++ it/guides/claude/claude_messages.mdx | 151 +++++++-------- it/guides/openai/openai_embeddings.mdx | 50 ++--- it/guides/platform/wework_bot.mdx | 56 ++++++ ja/guides/claude/claude_messages.mdx | 179 +++++++++--------- ja/guides/openai/openai_embeddings.mdx | 58 +++--- ja/guides/platform/wework_bot.mdx | 56 ++++++ ko/guides/claude/claude_messages.mdx | 157 +++++++-------- ko/guides/openai/openai_embeddings.mdx | 56 +++--- ko/guides/platform/wework_bot.mdx | 56 ++++++ openapi/openai.json | 3 +- pl/guides/claude/claude_messages.mdx | 199 ++++++++++---------- pl/guides/openai/openai_embeddings.mdx | 64 +++---- pl/guides/platform/wework_bot.mdx | 56 ++++++ pt/guides/claude/claude_messages.mdx | 188 +++++++++--------- pt/guides/openai/openai_embeddings.mdx | 56 +++--- pt/guides/platform/wework_bot.mdx | 56 ++++++ ru/guides/claude/claude_messages.mdx | 165 ++++++++-------- ru/guides/openai/openai_embeddings.mdx | 58 +++--- ru/guides/platform/wework_bot.mdx | 56 ++++++ sr/guides/claude/claude_messages.mdx | 161 ++++++++-------- sr/guides/openai/openai_embeddings.mdx | 60 +++--- sr/guides/platform/wework_bot.mdx | 56 ++++++ sv/guides/claude/claude_messages.mdx | 163 ++++++++-------- sv/guides/openai/openai_embeddings.mdx | 62 +++--- sv/guides/platform/wework_bot.mdx | 56 ++++++ uk/guides/claude/claude_messages.mdx | 169 +++++++++-------- uk/guides/openai/openai_embeddings.mdx | 56 +++--- uk/guides/platform/wework_bot.mdx | 56 ++++++ zh-Hans/guides/claude/claude_messages.mdx | 3 + zh-Hans/guides/openai/openai_embeddings.mdx | 6 +- zh-Hans/guides/platform/wework_bot.mdx | 56 ++++++ zh-Hant/guides/claude/claude_messages.mdx | 57 +++--- zh-Hant/guides/openai/openai_embeddings.mdx | 56 +++--- zh-Hant/guides/platform/wework_bot.mdx | 56 ++++++ 56 files changed, 2939 insertions(+), 1862 deletions(-) create mode 100644 ar/guides/platform/wework_bot.mdx create mode 100644 de/guides/platform/wework_bot.mdx create mode 100644 el/guides/platform/wework_bot.mdx create mode 100644 en/guides/platform/wework_bot.mdx create mode 100644 es/guides/platform/wework_bot.mdx create mode 100644 fi/guides/platform/wework_bot.mdx create mode 100644 fr/guides/platform/wework_bot.mdx create mode 100644 it/guides/platform/wework_bot.mdx create mode 100644 ja/guides/platform/wework_bot.mdx create mode 100644 ko/guides/platform/wework_bot.mdx create mode 100644 pl/guides/platform/wework_bot.mdx create mode 100644 pt/guides/platform/wework_bot.mdx create mode 100644 ru/guides/platform/wework_bot.mdx create mode 100644 sr/guides/platform/wework_bot.mdx create mode 100644 sv/guides/platform/wework_bot.mdx create mode 100644 uk/guides/platform/wework_bot.mdx create mode 100644 zh-Hans/guides/platform/wework_bot.mdx create mode 100644 zh-Hant/guides/platform/wework_bot.mdx diff --git a/ar/guides/claude/claude_messages.mdx b/ar/guides/claude/claude_messages.mdx index 1d9ccee57..dd0b8601d 100644 --- a/ar/guides/claude/claude_messages.mdx +++ b/ar/guides/claude/claude_messages.mdx @@ -1,43 +1,44 @@ --- -title: "التقدم بطلب واستخدام Claude Messages API" +title: "التقديم واستخدام واجهة Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude هو نظام محادثة بالذكاء الاصطناعي قوي جدًا، فبمجرد إدخال نص توجيهي، يمكنه إنشاء ردود سلسة وطبيعية خلال ثوانٍ قليلة. Claude Messages API هو تنسيق API أصلي رسمي من Anthropic، ويختلف عن التنسيق المتوافق مع OpenAI (Chat Completion)، إذ يستخدم بنية طلب واستجابة خاصة بـ Anthropic، مما يتيح الاستفادة بشكل أفضل من قدرات Claude الفريدة، مثل إدخال المحتوى متعدد الوسائط، واستدعاء الأدوات، والتفكير العميق (Extended Thinking) وغيرها من الميزات المتقدمة. +يُعد Anthropic Claude نظام محادثة بالذكاء الاصطناعي قويًا للغاية، فما عليك سوى إدخال نص توجيهي ليُنشئ ردودًا سلسة وطبيعية في غضون ثوانٍ قليلة. تُعد Claude Messages API صيغة API أصلية رسمية من Anthropic، وتختلف عن الصيغة المتوافقة مع OpenAI (Chat Completion)، إذ تستخدم بنية طلبات واستجابات خاصة بـ Anthropic، مما يتيح الاستفادة بشكل أفضل من قدرات Claude الفريدة، مثل إدخال المحتوى متعدد الوسائط، واستدعاء الأدوات، والتفكير العميق (Extended Thinking) وغيرها من الميزات المتقدمة. -تقدم هذه الوثيقة بشكل أساسي سير عمل استخدام عمليات Claude Messages API، وباستخدامه يمكننا استدعاء وظائف المحادثة في Claude عبر واجهة أصلية متوافقة مع Anthropic الرسمية. +يقدم هذا المستند بشكل أساسي عملية استخدام عمليات Claude Messages API، وباستخدامها يمكننا استخدام واجهة أصلية متوافقة مع Anthropic الرسمية لاستدعاء وظائف محادثة Claude. ## عملية التقديم -لاستخدام Claude Messages API، انتقل أولًا إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. +لاستخدام Claude Messages API، انتقل أولاً إلى [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. ![](https://cdn.acedata.cloud/dvc3cg.jpg) إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية. -**يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقدم بطلب منفصل لكل خدمة.** سيُمنحك رصيد مجاني عند أول تقديم، ويمكنك تجربته مجانًا؛ وعندما لا يكون الرصيد كافيًا، يمكنك شحن الرصيد العام من [لوحة التحكم](https://platform.acedata.cloud/console/coin). +**يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة.** سيُمنحك رصيد مجاني عند أول تقديم، ويمكنك التجربة مجانًا؛ وعندما يكون الرصيد غير كافٍ، يمكنك شحن الرصيد العام من [وحدة التحكم](https://platform.acedata.cloud/console/coin). > 📘 الوثائق الكاملة: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## الاستخدام الأساسي -مسار طلب Claude Messages API هو `/v1/messages`، وهو متوافق مع Anthropic API الرسمي. نحتاج على الأقل إلى توفير ثلاث معاملات مطلوبة: +مسار طلب Claude Messages API هو `/v1/messages`، وهو متوافق مع Anthropic API الرسمية. نحتاج على الأقل إلى توفير ثلاث معاملات مطلوبة: -- `model`: اختر نموذج Claude الذي تريد استخدامه. لا يتوفر `claude-opus-5-5` إلا عبر Messages API، ويدعم سياقًا من مليون Token، وحدًا أقصى للإخراج يبلغ 128K Token، ويفعّل دائمًا التفكير التكيفي. أحدث نموذج رائد هو `claude-fable-5-1` (سياق مليون Token، وحد أقصى للإخراج 128K Token)؛ ولا يزال `claude-fable-5` السابق محفوظًا للتوافق. تمت إضافة `claude-sonnet-5-5` إلى سلسلة واجهات Messages الأصلية، ويدعم إدخال الصور والتفكير التكيفي؛ وأسعاره المرجعية الرسمية للإدخال والإخراج وقراءة التخزين المؤقت هي 2 و10 و0.20 دولار أمريكي لكل مليون Token على التوالي. -- `messages`: مصفوفة الرسائل المُدخلة، تحتوي كل رسالة على `role` (الدور) و`content` (المحتوى)، حيث يدعم `role` كلًا من `user` و`assistant`. -- `max_tokens`: الحد الأقصى لعدد token للإخراج، ويُستخدم لتقييد طول الرد الواحد. +- `model`: اختيار نموذج Claude المراد استخدامه. يتوفر `claude-opus-5-5` فقط عبر Messages API، ويدعم سياقًا من مليون Token، وحدًا أقصى للإخراج يبلغ 128K Token، ويفعّل دائمًا التفكير التكيفي. أحدث نموذج رائد هو `claude-fable-5-1` (سياق مليون Token، وحد أقصى للإخراج 128K Token)؛ ولا يزال `claude-fable-5` السابق محفوظًا للتوافق. انضم `claude-sonnet-5-5` إلى واجهات سلسلة Messages الأصلية، ويدعم إدخال الصور والتفكير التكيفي؛ وتبلغ الأسعار المرجعية الرسمية للإدخال والإخراج وقراءة التخزين المؤقت لكل مليون Token على التوالي 2 و10 و0.20 دولار أمريكي. +- `messages`: مصفوفة الرسائل المُدخلة، تحتوي كل رسالة على `role` (الدور) و`content` (المحتوى)، حيث يدعم `role` كلاً من `user` و`assistant`. +- `max_tokens`: الحد الأقصى لعدد Token في الإخراج، ويُستخدم لتقييد طول الرد الواحد. المعاملات الاختيارية الشائعة: - `system`: نص التوجيه النظامي، يُستخدم لتحديد سلوك النموذج ودوره. -- `temperature`: عشوائية التوليد، بين 0 و1، وكلما زادت القيمة أصبح الرد أكثر تشتتًا. -- `stream`: ما إذا كان سيتم استخدام استجابة متدفقة؛ تعيينه إلى `true` يتيح تأثير الإرجاع حرفًا بحرف. +- `temperature`: عشوائية التوليد، بين 0 و1، وكلما زادت القيمة أصبحت الردود أكثر تشتتًا. +- `stream`: ما إذا كان سيتم استخدام استجابة متدفقة، ويمكن ضبطه على `true` لتحقيق تأثير الإرجاع حرفًا بحرف. - `stop_sequences`: تسلسلات توقف مخصصة، سيتوقف النموذج عن التوليد عند مواجهة هذه النصوص. - `top_p`: معامل أخذ العينات النووي، ويتعاون مع temperature للتحكم في عشوائية التوليد. -- `top_k`: أخذ العينات فقط من بين أعلى K خيارات احتمالًا. -- `tools`: تعريفات الأدوات، تُستخدم للسماح للنموذج باستدعاء الدوال الخارجية. -- `tool_choice`: التحكم في كيفية استخدام النموذج للأدوات المقدمة. +- `top_k`: أخذ العينات فقط من بين K خيارات ذات أعلى احتمالية. +- `tools`: تعريفات الأدوات، تُستخدم للسماح للنموذج باستدعاء وظائف خارجية. +- `tool_choice`: التحكم في كيفية استخدام النموذج للأدوات المُقدمة. - `cache_control`: إنشاء نقطة توقف للتخزين المؤقت تلقائيًا عند آخر كتلة محتوى قابلة للتخزين المؤقت في الطلب؛ ويمكن أيضًا كتابته على كتلة محتوى محددة. +- `metadata`: كائن بيانات وصفية اختياري للطلب. `metadata.user_id` عبارة عن سلسلة نصية، ويمكن تمرير معرّف مستخدم مخصص من جهة المستدعي، مثل `{"user_id":"example-user-001"}`؛ ويُنصح باستخدام معرّف ثابت لا يحتوي على معلومات شخصية. وهو لا يحل محل مصادقة `Authorization`، ولا يحتاج إلى كتابته ضمن محتوى محادثة `messages`. ### مثال cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -بعد الاستدعاء، تكون النتيجة المرجعة كما يلي: +بعد الاستدعاء، تكون نتيجة الإرجاع كما يلي: ```json { @@ -106,25 +109,25 @@ print(response.json()) } ``` -وصف حقول النتيجة المرجعة: +شرح حقول نتيجة الإرجاع: +- `id`：المعرّف الفريد لهذه الرسالة. +- `type`：دائمًا `message`. +- `role`：دائمًا `assistant`. +- `content`：مصفوفة محتوى الرد، يحتوي كل عنصر على `type` (مثل `text`) والمحتوى المقابل. +- `model`：اسم النموذج الذي يعالج الطلب. +- `stop_reason`：سبب التوقف. تشمل القيم المستقرة `end_turn`، و`max_tokens`، و`stop_sequence`، و`tool_use`، و`pause_turn` (يمكن إعادة محتوى assistant الحالي كما هو للمتابعة)، و`refusal`، و`model_context_window_exceeded`. +- `stop_sequence`：إذا توقف بسبب تسلسل توقف مخصص، يعرض نص تسلسل التوقف المطابق. +- `stop_details`：عندما يكون `stop_reason` هو `refusal`، قد يتضمن فئة الرفض ووصفًا. +- `usage`：إحصاءات استخدام الـ token. `input_tokens` هي المدخلات غير المخزنة مؤقتًا؛ و`cache_creation_input_tokens` و`cache_read_input_tokens` هما كتابة وقراءة ذاكرة التخزين المؤقت على التوالي؛ و`output_tokens` هو إجمالي عدد رموز الإخراج. إذا تم إرجاع `output_tokens_details.thinking_tokens`، فإن هذه القيمة جزء من `output_tokens`، ولا تُضف مرة أخرى عند حساب الإجمالي أو التكلفة. قد تكون هذه التفاصيل `null` أو محذوفة عندما لا يكون هناك عدّ موثوق. +- `usage.cache_creation`：تفاصيل اختيارية لمهلة صلاحية كتابة ذاكرة التخزين المؤقت، تتضمن `ephemeral_5m_input_tokens` و`ephemeral_1h_input_tokens`. عند وجود الكائن، يساوي مجموع العنصرين `cache_creation_input_tokens`؛ وتعني الحقول التي تكون `null` أو محذوفة أنه لا يوجد تقسيم متاح لمهلة الصلاحية في الاستجابة الحالية، ولا يمكن تفسيرها على أنها `0`. +- `usage.cost`：قد تتضمن الاستجابات غير المتدفقة كائن استهلاك الرصيد المسجل بواسطة Ace Data Cloud، حيث تمثل `amount` الاستهلاك الفعلي لهذه المرة، و`currency` وحدة القياس، و`list_amount` المبلغ قبل الخصم (إن وجد). يبلغ السعر الأساسي الرسمي لقراءة ذاكرة التخزين المؤقت في Fable 5.1 مقدار $0.25/مليون Token، بينما تبلغ الأسعار الأساسية لكتابة ذاكرة التخزين المؤقت لمدة 5 دقائق وساعة واحدة $12.50 و$20/مليون Token على التوالي؛ وتُحوَّل الأسعار الفعلية للمنصة وفقًا لخصومات الباقة. -- `id`: المعرّف الفريد لهذه الرسالة. -- `type`: يكون دائمًا `message`. -- `role`: يكون دائمًا `assistant`. -- `content`: مصفوفة محتوى الرد، يحتوي كل عنصر على `type` (مثل `text`) والمحتوى المقابل. -- `model`: اسم النموذج الذي يعالج الطلب. -- `stop_reason`: سبب التوقف. تتضمن القيم المستقرة `end_turn` و`max_tokens` و`stop_sequence` و`tool_use` و`pause_turn` (يمكن إعادة محتوى assistant الحالي كما هو للمتابعة) و`refusal` و`model_context_window_exceeded`. -- `stop_sequence`: إذا توقف بسبب تسلسل توقف مخصص، يعرض نص تسلسل التوقف المطابق. -- `stop_details`: عندما يكون `stop_reason` هو `refusal`، قد يحتوي على فئة الرفض ووصفها. -- `usage`: إحصاءات استخدام token. يمثل `input_tokens` الإدخال غير المخزن مؤقتًا؛ ويمثل `cache_creation_input_tokens` و`cache_read_input_tokens` كتابة التخزين المؤقت وقراءته على التوالي؛ ويمثل `output_tokens` إجمالي عدد token للإخراج. إذا تم إرجاع `output_tokens_details.thinking_tokens`، فهذه القيمة مجموعة فرعية من `output_tokens`، ولا تُضف مرة أخرى عند احتساب الإجمالي أو التكلفة. قد يكون هذا التفصيل `null` أو محذوفًا عندما لا توجد إحصاءات موثوقة. -- `usage.cache_creation`: تفصيل اختياري لـ TTL لكتابة التخزين المؤقت، ويحتوي على `ephemeral_5m_input_tokens` و`ephemeral_1h_input_tokens`. عند وجود الكائن، يساوي مجموعهما `cache_creation_input_tokens`؛ وكون الحقل `null` أو محذوفًا يعني عدم وجود تفصيل TTL متاح في الاستجابة الحالية، ولا يمكن تفسيره على أنه `0`. -- `usage.cost`: قد تتضمن الاستجابة غير المتدفقة كائن استهلاك الرصيد المسجل بواسطة Ace Data Cloud، حيث يمثل `amount` الاستهلاك الفعلي لهذه المرة، ويمثل `currency` وحدة القياس، ويمثل `list_amount` المبلغ قبل الخصم (إن وُجد). سعر قراءة التخزين المؤقت الرسمي الأساسي لـ Fable 5.1 هو $0.25/مليون Token، وأسعار كتابة التخزين المؤقت الأساسية لمدة 5 دقائق وساعة واحدة هي $12.50 و$20/مليون Token على التوالي؛ ويُحوَّل السعر الفعلي للمنصة وفقًا لخصم الباقة. +## موجه النظام -## نص التوجيه النظامي - -يدعم Claude Messages API تعيين نص التوجيه النظامي عبر حقل `system`، ويُستخدم لتعريف سلوك النموذج ودوره وسياقه. +تدعم Claude Messages API تعيين موجه النظام عبر الحقل `system`، ويُستخدم لتعريف سلوك النموذج ودوره وسياقه. ### مثال Python + ```python import requests @@ -149,7 +152,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -من خلال تعيين مطالبة `system`، يمكن التحكم بدقة في دور Claude وطريقة سلوكه. +من خلال تعيين موجه `system`، يمكن التحكم بدقة في دور Claude وطريقة سلوكه. ## الاستجابة المتدفقة @@ -183,14 +186,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -تُعاد الاستجابة المتدفقة بتنسيق Server-Sent Events (SSE)، ويبدأ كل سطر بالبادئتين `event:` و`data:`. تشمل أنواع الأحداث المتدفقة: +تُرجع الاستجابة المتدفقة بتنسيق Server-Sent Events (SSE)، ويبدأ كل سطر بـ `event:` و`data:`. تشمل أنواع الأحداث المتدفقة: -- `message_start`: بداية الرسالة، وتتضمن المعلومات الأساسية للرسالة واسم النموذج. -- `content_block_start`: بداية كتلة المحتوى. -- `content_block_delta`: تحديث تزايدي لكتلة المحتوى، ويتضمن الجزء النصي المُنشأ حديثًا. -- `content_block_stop`: نهاية كتلة المحتوى. -- `message_delta`: تحديث تزايدي على مستوى الرسالة، ويتضمن `stop_reason` ومعلومات `usage` النهائية. يجب قراءة القيمة الموثوقة لـ `output_tokens_details.thinking_tokens` من آخر `message_delta.usage` فقط، ولا تجمعها عبر الأحداث. -- `message_stop`: نهاية الرسالة. +- `message_start`：بداية الرسالة، تتضمن المعلومات الأساسية للرسالة واسم النموذج. +- `content_block_start`：بداية كتلة المحتوى. +- `content_block_delta`：تحديث تدريجي لكتلة المحتوى، يتضمن مقطع النص المُنشأ حديثًا. +- `content_block_stop`：نهاية كتلة المحتوى. +- `message_delta`：تحديث تدريجي على مستوى الرسالة، يتضمن `stop_reason` ومعلومات `usage` النهائية. يجب قراءة القيمة الموثوقة لـ `output_tokens_details.thinking_tokens` من آخر `message_delta.usage` فقط، ولا تجمعها عبر الأحداث. +- `message_stop`：نهاية الرسالة. يكون تأثير الإخراج كما يلي: @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -كما يمكن ملاحظة أن حدث `content_block_delta` في الاستجابة المتدفقة يتضمن المحتوى النصي المُنشأ تدريجيًا، ويمكن الحصول على الرد الكامل من خلال ضم جميع `text_delta`. +يمكن ملاحظة أن حدث `content_block_delta` في الاستجابة المتدفقة يتضمن محتوى النص المُنشأ تدريجيًا، ويمكن الحصول على الرد الكامل من خلال دمج جميع `text_delta`. ### مثال JavaScript @@ -253,7 +256,7 @@ while (true) { ## المحادثات متعددة الجولات -إذا كنت تريد دمج وظيفة المحادثات متعددة الجولات، فيجب ترتيب الرسائل ذات دوري `user` و`assistant` بالتناوب في مصفوفة `messages`، وتمرير سجل المحادثات السابق معًا. +إذا كنت ترغب في دمج وظيفة المحادثات متعددة الجولات، فيجب ترتيب رسائل الأدوار `user` و`assistant` بالتناوب في مصفوفة `messages`، وتمرير سجل المحادثة السابق معًا. ### مثال Python @@ -283,7 +286,6 @@ print(response.json()) ``` تكون نتيجة الإرجاع كما يلي: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,11 +309,11 @@ print(response.json()) من خلال تمرير سجل المحادثة الكامل في `messages`، يمكن لـ Claude تقديم إجابات دقيقة بالاستناد إلى السياق. -## نموذج التفكير العميق +## نماذج التفكير العميق -إن thinking وthinking summary في Claude مفهومان مختلفان: يمكن للنموذج إجراء استدلال داخلي، لكن واجهة API لا تُرجع سلسلة التفكير الأصلية. عند الحاجة إلى عرض عملية الاستدلال، تُرجع واجهة API ملخصًا تمت معالجته. +إن thinking و thinking summary في Claude مفهومان مختلفان: يمكن للنموذج إجراء استدلال داخلي، لكن API لا يعيد سلسلة التفكير الأصلية. عند الحاجة إلى عرض عملية الاستدلال، فإن ما يعيده API هو ملخص مُعالَج. -يُنصح حاليًا باستخدام adaptive thinking للنماذج الحالية، والتحكم في إجمالي جهد الاستدلال عبر `output_config.effort`: +يوصى للنماذج الحالية باستخدام adaptive thinking، والتحكم في إجمالي جهد الاستدلال عبر `output_config.effort`: ```python import requests @@ -341,7 +343,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -تكون كتلة thinking في الاستجابة بالشكل التالي: +يكون شكل كتلة thinking في الاستجابة كما يلي: ```json { @@ -350,26 +352,27 @@ print(response.json()) "signature": "opaque-signature" } ``` -- يُرجع `display: "summarized"` ملخص تفكير مقروءًا؛ وهو ليس سلسلة التفكير الأصلية. -- يُرجع `display: "omitted"` القيمة `thinking: ""`، لكنه يحتفظ بـ `signature` معتمة لدعم المحادثات اللاحقة. -- يُعد `display: "updates"` وضع beta من Anthropic، ويتطلب تضمين `anthropic-beta: thinking-display-updates-2026-08-18`. التعريف الرسمي هو إخفاء نص الاستدلال وعرض تحديثات تقدم موجزة بين استدعاءات الأدوات. تمرر المنصة هذه المعلمة وترويسة طلب beta كما هي، ولن تعيد كتابتها قسرًا إلى `summarized`؛ ويعتمد محتوى الإخراج الفعلي على دعم النموذج المحدد. -- يتم تمرير `thinking` و`output_config` وeffort ومعلمات أخذ العينات وحقول الامتداد الجديدة كما هي. لا تحتفظ المنصة بتعدادات قيم أو قيود مجموعات مبرمجة مسبقًا حسب النموذج، ولا تعيد كتابة وضع thinking تلقائيًا؛ ويحدد النموذج المحدد ما إذا كان يقبل هذه المعلمات، وستُعاد أخطاء المعلمات التي يرجعها النموذج إلى العميل. + +- يعيد `display: "summarized"` ملخص تفكير قابلًا للقراءة؛ وهو ليس سلسلة التفكير الأصلية. +- يعيد `display: "omitted"` القيمة `thinking: ""`، لكنه يحتفظ بـ `signature` معتم لدعم المحادثات اللاحقة. +- `display: "updates"` هو وضع beta من Anthropic، ويتطلب تضمين `anthropic-beta: thinking-display-updates-2026-08-18`. التعريف الرسمي هو إخفاء نص الاستدلال وعرض تحديثات تقدم قصيرة بين استدعاءات الأدوات. تمرر المنصة هذه المعلمة وترويسة طلب beta بقيمتهما الأصلية، ولن تفرض إعادة كتابتهما إلى `summarized`؛ ويعتمد المحتوى الفعلي للمخرجات على دعم النموذج المختار. +- يتم تمرير `thinking` و`output_config` وeffort ومعلمات أخذ العينات وحقول الامتداد الجديدة بقيمها الأصلية. لا تحتفظ المنصة بتعدادات قيم مضمّنة في الشيفرة حسب النموذج أو قيود على التركيبات، ولا تعيد كتابة وضع thinking تلقائيًا؛ ويحدد النموذج المختار ما إذا كان يقبل هذه المعلمات، وتُعاد أخطاء المعلمات التي يعيدها النموذج إلى العميل. - القيمة الافتراضية لـ display في Fable 5.1 وFable 5 وOpus 5 وSonnet 5 وOpus 4.8 وOpus 4.7 هي `omitted`؛ بينما تستخدم Opus 4.6 وSonnet 4.6 والنماذج الأقدم التي تدعم thinking القيمة الافتراضية `summarized`. -- يؤثر Display فقط على محتوى الإرجاع وزمن تأخر البث، ولا يعطّل الاستدلال ولا يقلل من فوترة رموز thinking. -- ما إذا كان thinking مفعّلًا افتراضيًا وقيمة display الافتراضية هما مسألتان مستقلتان. يفعّل Opus 5 وSonnet 5 adaptive thinking افتراضيًا؛ وبالنسبة إلى Opus 5، فإن حذف `thinking` يعادل adaptive، وحذف `output_config.effort` يعادل `high`. تتطلب Opus 4.8 و4.7 و4.6 تفعيلًا صريحًا. -- يشترك thinking والنص النهائي في ميزانية إخراج `max_tokens`. عندما تكون الميزانية صغيرة جدًا، قد يستهلك thinking معظم الحصة، مما يجعل النص فارغًا أو مبتورًا؛ يرجى زيادة `max_tokens`، أو استخدام effort بقيمة `low` / `medium` للتحكم في استثمار الاستدلال. -- بالنسبة إلى النماذج التي تسمح بتعطيل thinking، يمكن تمرير `thinking: {"type":"disabled"}`. تعتمد الأوضاع الجديدة مثل `between_tools` ومجموعات effort على النموذج المحدد؛ ولا ترفض المنصة مسبقًا استنادًا إلى قواعد الإصدارات القديمة. -- يمكن تمرير ميزانية تفكير ثابتة عبر `budget_tokens`؛ تستخدم النماذج الجديدة عادةً `thinking.type=adaptive` و`output_config.effort`. يعتمد دعم الميزانية الثابتة أو تعطيل التفكير على القدرات الحالية للنموذج المحدد. -- في المحادثات متعددة الجولات واستدعاءات الأدوات، يجب إعادة تمرير كتلة thinking الكاملة وsignature التي يعيدها assistant كما هي؛ لا تعدّل signature أو تنشئها بنفسك. -- لا يعني تمرير المعلمات أن كل نموذج يدعم جميع الميزات. لا يزال التحويل مطلوبًا للاستدعاءات عبر البروتوكولات، ويحدد نموذج الخدمة الذي يعالج الطلب فعليًا نطاق دعم ومشكلات محتوى مثل `redacted_thinking`. +- يؤثر Display فقط في المحتوى المُعاد وتأخير البث، ولا يعطل الاستدلال ولا يقلل تكلفة رموز thinking. +- ما إذا كان thinking مفعّلًا افتراضيًا والقيمة الافتراضية لـ display مسألتان منفصلتان. يفعّل Opus 5 وSonnet 5 adaptive thinking افتراضيًا؛ وبالنسبة إلى Opus 5، فإن حذف `thinking` يعادل adaptive، وحذف `output_config.effort` يعادل `high`. وتتطلب Opus 4.8 و4.7 و4.6 تفعيلًا صريحًا. +- يشترك thinking والنص النهائي في ميزانية مخرجات `max_tokens`. عند انخفاض الميزانية كثيرًا، قد يستهلك thinking معظم الحصة، مما يجعل النص فارغًا أو مقتطعًا؛ يرجى زيادة `max_tokens`، أو استخدام effort بقيمة `low` / `medium` للتحكم في جهد الاستدلال. +- بالنسبة إلى النماذج التي تسمح بتعطيل thinking، يمكن تمرير `thinking: {"type":"disabled"}`. تعتمد الأوضاع الجديدة مثل `between_tools` وتركيبات effort على النموذج المختار؛ ولا ترفض المنصة مسبقًا بناءً على قواعد الطرازات القديمة. +- يمكن تمرير ميزانية تفكير ثابتة عبر `budget_tokens`؛ تستخدم النماذج الجديدة عادةً `thinking.type=adaptive` و`output_config.effort`. ويعتمد دعم الميزانية الثابتة أو تعطيل التفكير على الإمكانات الحالية للنموذج المختار. +- في المحادثات متعددة الجولات واستدعاءات الأدوات، يجب إعادة تمرير كتلة thinking الكاملة وsignature اللذين أعادهما assistant كما هما؛ لا تعدل signature ولا تنشئه بنفسك. +- لا يعني تمرير المعلمات أن كل نموذج يدعم جميع الميزات. لا تزال الاستدعاءات عبر البروتوكولات تتطلب التحويل، ويحدد نموذج الخدمة الذي يعالج الطلب فعليًا نطاق دعم محتوى مثل `redacted_thinking` والأخطاء المتعلقة به. -في طلبات البث، ينتج `summarized` ‏`thinking_delta`؛ ولا ينتج `omitted` ‏`thinking_delta`، بل يحتفظ فقط بدورة حياة كتلة thinking و`signature_delta`. +في طلبات البث، ينتج `summarized` قيمة `thinking_delta`؛ ولا ينتج `omitted` قيمة `thinking_delta`، بل يحتفظ فقط بدورة حياة كتلة thinking و`signature_delta`. ## نماذج الرؤية -يدعم Claude الإدخال متعدد الوسائط، ويمكنه معالجة النصوص والصور في الوقت نفسه. في Messages API، يمكن استخدام قدرات الرؤية عبر تعيين `content` بتنسيق مصفوفة وتمرير كتلة محتوى صورة. +يدعم Claude الإدخال متعدد الوسائط، ويمكنه معالجة النصوص والصور في الوقت نفسه. في Messages API، يمكن استخدام قدرات الرؤية عبر ضبط `content` على صيغة مصفوفة وتمرير كتلة محتوى صورة. -### استخدام الصور المشفرة بـ Base64 +### استخدام صور بترميز Base64 ```python import base64 @@ -383,7 +386,7 @@ headers = { "content-type": "application/json" } -# قراءة الصورة وترميزها +# 读取并编码图片 with open("image.png", "rb") as f: image_data = base64.standard_b64encode(f.read()).decode("utf-8") @@ -456,7 +459,6 @@ print(response.json()) ``` ### مثال cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -490,7 +492,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ ## المستندات وPDF -يستخدم PDF كتلة محتوى `document`، ويدعم مصدرين مستقرين هما Base64 وURL. يجب أن يستخدم مصدر Base64 القيمة `application/pdf`: +يستخدم PDF كتلة محتوى `document`، ويدعم مصدرين مستقرين هما Base64 وURL. يجب أن يستخدم مصدر Base64 `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -يُكتب مصدر URL بالشكل `{"type":"url","url":"https://example.com/report.pdf"}`. يدعم `document` أيضًا `text/plain` ومصدر `content` المكوّن من كتل text/image؛ وتشمل الحقول الاختيارية `title` و`context` و`citations`. يُعد مصدر `file_id` في Files API ميزة beta مستقلة، ولا يندرج ضمن العقد المستقر لهذه الواجهة. +يُكتب مصدر URL بالشكل `{"type":"url","url":"https://example.com/report.pdf"}`. يدعم `document` أيضًا `text/plain` ومصدر `content` المكوّن من كتل text/image؛ وتشمل الحقول الاختيارية `title` و`context` و`citations`. مصدر `file_id` الخاص بـ Files API هو وظيفة beta مستقلة، وليس ضمن العقد المستقر لهذه الواجهة. ## التخزين المؤقت للمطالبات -سيضع `cache_control` على المستوى الأعلى نقطة توقف التخزين المؤقت تلقائيًا في آخر كتلة قابلة للتخزين المؤقت: +يضع `cache_control` على المستوى الأعلى نقطة توقف التخزين المؤقت تلقائيًا على آخر كتلة قابلة للتخزين المؤقت: ```python payload = { @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -عند الحاجة إلى التحكم الدقيق في الموضع، يمكن أيضًا كتابة `cache_control` نفسه على كتل محتوى text أو image أو document أو tool_use أو tool_result، أو على تعريف الأداة. يدعم `ttl` القيمتين `5m` (الافتراضية) و`1h`؛ يرجى تحديد كتابة الكاش وإصابته من خلال `usage.cache_creation_input_tokens` و`usage.cache_read_input_tokens`. -عندما توفر الاستجابة `usage.cache_creation`، فإن `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. إذا كانت `cache_creation` تساوي `null` أو تم حذفها، فهذا يعني أن هناك فقط إجمالي كتابة الكاش، ولا يوجد تقسيم موثوق لـ TTL؛ في هذه الحالة، لا تتعامل مع أي bucket على أنه 0 معلوم، وتظل الفوترة والإجمالي خاضعين للحقل التجميعي. +عند الحاجة إلى تحكم دقيق في الموضع، يمكن أيضًا كتابة `cache_control` نفسه على كتل محتوى text وimage وdocument وtool_use وtool_result أو على تعريفات الأدوات. يدعم `ttl` القيمتين `5m` (الافتراضية) و`1h`؛ يُرجى تحديد كتابة التخزين المؤقت والإصابة به عبر `usage.cache_creation_input_tokens` و`usage.cache_read_input_tokens`. + +عندما توفر الاستجابة `usage.cache_creation`، فإن `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. إذا كانت `cache_creation` تساوي `null` أو تم حذفها، فهذا يعني وجود إجمالي كتابة التخزين المؤقت فقط، من دون تقسيم موثوق لـ TTL؛ في هذه الحالة، لا تعتبر أي bucket على أنها 0 معروفة، وتبقى الفوترة والإجمالي مستندين إلى الحقل aggregate. -مثال على نتيجة الإرجاع: +مثال على النتيجة المعادة: ```json { @@ -563,7 +566,7 @@ payload = { ## استدعاء الأدوات (Tool Use) -تدعم Claude Messages API أصلًا ميزة استدعاء الأدوات، مما يسمح للنموذج باستدعاء أدوات/دوال محددة مسبقًا من قبلك عند الحاجة. +تدعم Claude Messages API أصلًا وظيفة استدعاء الأدوات، مما يسمح للنموذج باستدعاء الأدوات/الدوال التي عرّفتها مسبقًا عند الحاجة. ### مثال Python @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -عندما يقرر النموذج استدعاء أداة، ستحتوي `content` في نتيجة الإرجاع على كتلة محتوى من نوع `tool_use`: +عندما يقرر النموذج استدعاء أداة، ستتضمن `content` في النتيجة المعادة كتلة محتوى من نوع `tool_use`: ```json { @@ -637,7 +640,7 @@ print(response.json()) } ``` -لاحظ أن `stop_reason` هو `tool_use`، مما يشير إلى أن النموذج يحتاج إلى استدعاء الأداة. بعد تلقي هذه النتيجة، تحتاج إلى تنفيذ دالة الأداة وإعادة النتيجة إلى النموذج في شكل `tool_result`: +لاحظ أن `stop_reason` هي `tool_use`، مما يشير إلى أن النموذج يحتاج إلى استدعاء الأداة. بعد تلقي هذه النتيجة، تحتاج إلى تنفيذ دالة الأداة وإعادة النتيجة إلى النموذج على هيئة `tool_result`: ```python payload = { @@ -685,34 +688,33 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -سيُنشئ النموذج، بناءً على النتيجة التي تُرجعها الأداة، ردًا نهائيًا باللغة الطبيعية. +سينشئ النموذج، استنادًا إلى النتيجة التي تعيدها الأداة، ردًا نهائيًا باللغة الطبيعية. ## الفرق عن Chat Completion API -توفر Ace Data Cloud في الوقت نفسه تنسيقي Claude API، والفروقات الرئيسية بينهما كما يلي: +توفر Ace Data Cloud صيغتين من Claude API في الوقت نفسه، والفروقات الرئيسية بينهما كما يلي: -يمثل `usage.input_tokens` في Messages API الإدخال غير المخزن مؤقتًا فقط، بينما يُعد `cache_read_input_tokens` و`cache_creation_input_tokens` حاويتين مستقلتين للفوترة؛ وتُحسب الثلاثة بشكل منفصل وفقًا للأسعار المقابلة. - -| الميزة | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +تمثل `usage.input_tokens` في Messages API المدخلات غير المخزنة مؤقتًا فقط، بينما يُعد `cache_read_input_tokens` و`cache_creation_input_tokens` قسمي فوترة مستقلين؛ وسيُحسب الثلاثة كلٌّ منها وفق السعر المقابل. +| الميزة | واجهة برمجة تطبيقات Messages (`/v1/messages`) | واجهة برمجة تطبيقات Chat Completion (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| التنسيق | التنسيق الأصلي لـ Anthropic | تنسيق متوافق مع OpenAI | -| موجّه النظام | حقل `system` مستقل | يُمرر عبر `role: "system"` في `messages` | +| التنسيق | تنسيق Anthropic الأصلي | تنسيق متوافق مع OpenAI | +| موجه النظام | حقل `system` مستقل | يُمرَّر عبر `role: "system"` ضمن `messages` | | بنية الاستجابة | مصفوفة `content` (تدعم أنواعًا متعددة) | مصفوفة `choices` (تتضمن `message`) | -| البث | أحداث SSE (أنواع أحداث متعددة) | سطور SSE `data` | -| التفكير المتعمق | `thinking` الأصلي و`output_config.effort` | سياسة النموذج الافتراضية والمعلمات المتوافقة | +| تنسيق البث | أحداث SSE (أنواع أحداث متعددة) | أسطر SSE `data` | +| التفكير العميق | `thinking` الأصلي و`output_config.effort` | الاستراتيجية الافتراضية للنموذج والمعلمات المتوافقة | | استدعاء الأدوات | `tools` الأصلي + `input_schema` | تنسيق `tools` المتوافق مع OpenAI | | إحصاءات Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -إذا كان نظامك متصلًا بالفعل بواجهة API بتنسيق OpenAI، يمكنك استخدام Chat Completion API للتبديل بسلاسة. إذا كنت بحاجة إلى استخدام جميع القدرات الأصلية لـ Claude، فيُوصى باستخدام Messages API. +إذا كان نظامك قد تكامل بالفعل مع واجهة برمجة تطبيقات بتنسيق OpenAI، فيمكنك استخدام واجهة برمجة تطبيقات Chat Completion للتبديل بسلاسة. إذا كنت بحاجة إلى استخدام جميع الإمكانات الأصلية لـ Claude، فيوصى باستخدام واجهة برمجة تطبيقات Messages. ## معالجة الأخطاء -تستخدم استجابات الأخطاء للواجهة العامة envelope الخاص بمنصة Ace Data Cloud: يُعد `error.code` رمز خطأ ثابتًا، و`error.message` وصفًا، ويُستخدم `trace_id` لتتبع الطلب. تتضمن حالات HTTP الشائعة ما يلي: +تستخدم استجابات الأخطاء للواجهات العامة envelope لمنصة Ace Data Cloud: يمثل `error.code` رمز خطأ ثابتًا، ويمثل `error.message` وصفًا، ويُستخدم `trace_id` لتتبّع الطلبات. تشمل حالات HTTP الشائعة ما يلي: - `400`: معلمات الطلب أو محتوى البروتوكول غير صالح. - `401`: رمز التفويض غير صالح أو مفقود أو منتهي الصلاحية. -- `403`: الوصول محظور، أو الرصيد غير كافٍ، أو الحصة مقيدة. -- `404`: واجهة API أو النموذج غير موجود. +- `403`: الوصول محظور، أو الرصيد غير كافٍ، أو الحصة مقيّدة. +- `404`: واجهة برمجة التطبيقات أو النموذج غير موجود. - `413`: جسم الطلب كبير جدًا. - `429`: عدد كبير جدًا من الطلبات. - `500` / `503` / `504`: خطأ في الخدمة، أو عدم توفر مؤقت، أو انتهاء مهلة المعالجة. @@ -729,7 +731,8 @@ print(response.json()) } ``` -بنية الخطأ هذه هي عقد وقت التشغيل الخاص بـ Ace Data Cloud، ولا تعادل envelope الخطأ الرسمي لـ Anthropic؛ يرجى المعالجة وفقًا لحالة HTTP و`error.code`. +بنية الخطأ هذه هي عقد وقت التشغيل لـ Ace Data Cloud، ولا تعادل envelope الخطأ الرسمي لـ Anthropic؛ يُرجى التعامل معها وفقًا لحالة HTTP و`error.code`. ## الخلاصة -من خلال هذا المستند، تعرّفت بالفعل على كيفية استخدام Claude Messages API لاستدعاء وظائف المحادثة في Claude بصيغة Anthropic الأصلية. يدعم Messages API ميزات غنية مثل المحادثات الأساسية، ومطالبات النظام، والاستجابات المتدفقة، والمحادثات متعددة الجولات، والتفكير العميق، والفهم البصري، وملفات PDF، والتخزين المؤقت للمطالبات، واستدعاء الأدوات. إذا كانت لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا. + +من خلال هذا المستند، أصبحت تعرف كيفية استخدام واجهة برمجة تطبيقات Claude Messages لاستدعاء وظائف المحادثة في Claude بتنسيق Anthropic الأصلي. تدعم واجهة برمجة تطبيقات Messages ميزات غنية مثل المحادثة الأساسية، وموجهات النظام، والاستجابات المتدفقة، والمحادثات متعددة الجولات، والتفكير العميق، والفهم البصري، وPDF، والتخزين المؤقت للموجهات، واستدعاء الأدوات. إذا كانت لديك أي أسئلة، فيُرجى الاتصال بفريق الدعم الفني لدينا في أي وقت. diff --git a/ar/guides/openai/openai_embeddings.mdx b/ar/guides/openai/openai_embeddings.mdx index 872ae15e4..7825d8ba5 100644 --- a/ar/guides/openai/openai_embeddings.mdx +++ b/ar/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API 申请及使用" +title: "التقديم واستخدام واجهة OpenAI Embeddings API" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI 词向量服务，用于生成表示输入文本的词向量结果。 +خدمة متجهات الكلمات من OpenAI، تُستخدم لإنشاء نتائج متجهات الكلمات التي تمثل النص المُدخل. -本文档主要介绍 OpenAI Embeddings API 操作的使用流程，利用它我们可以创建表示输入文本的嵌入向量。。 +يقدم هذا المستند بشكل أساسي عملية استخدام واجهة OpenAI Embeddings API، وباستخدامها يمكننا إنشاء متجهات تضمين تمثل النص المُدخل。。 -## 申请流程 +## عملية التقديم -要使用 OpenAI Embeddings API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 获取您的 API Token，留作备用。 +لاستخدام واجهة OpenAI Embeddings API، انتقل أولاً إلى [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。 +إذا لم تقم بتسجيل الدخول أو التسجيل بعد، فسيتم تلقائيًا الانتقال إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية. -**一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。** 首次申请会赠送免费额度，可免费体验；额度不足时可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用余额。 +**يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة.** سيُمنح رصيد مجاني عند التقديم لأول مرة، ويمكنك التجربة مجانًا؛ وعندما يكون الرصيد غير كافٍ، يمكنك شحن الرصيد العام في [وحدة التحكم](https://platform.acedata.cloud/console/coin). -> 📘 完整文档：[OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) +> 📘 المستند الكامل: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## 基本使用 +## الاستخدام الأساسي -接下来就可以在界面上填写对应的内容，如图所示： +بعد ذلك، يمكنك ملء المحتوى المقابل في الواجهة، كما هو موضح في الصورة:

-在第一次使用该接口时，我们至少需要填写三个内容，一个是 `authorization`，直接在下拉列表里面选择即可。另一个参数是 `model`， `model` 就是我们选择使用 OpenAI 官网模型类别，这里我们主要有 3 种模型，详情可以看我们提供的模型。最后一个参数是`input`，`input` 是我们需要转换的词向量文本。 +عند استخدام هذه الواجهة لأول مرة، نحتاج إلى ملء ثلاثة محتويات على الأقل، أحدها هو `authorization`، ويمكنك اختياره مباشرةً من القائمة المنسدلة. المعلمة الأخرى هي `model`، و`model` هي فئة النموذج من الموقع الرسمي لـ OpenAI التي نختار استخدامها، والنماذج المتاحة حاليًا هي `text-embedding-3-small` و`text-embedding-3-large`. تم إيقاف توفير `text-embedding-ada-002`؛ وإذا كانت فهارس المتجهات الحالية تستخدم هذا النموذج القديم، فلا يمكن خلط متجهات النموذج الجديد مباشرةً، ويجب إعادة إنشاء الفهرس. المعلمة الأخيرة هي `input`، و`input` هو نص متجهات الكلمات الذي نحتاج إلى تحويله. -同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。 +في الوقت نفسه، يمكنك ملاحظة وجود إنشاء لرمز الاستدعاء المقابل على الجانب الأيمن، ويمكنك نسخ الرمز وتشغيله مباشرةً، أو يمكنك النقر مباشرةً على زر «Try» للاختبار. -可选参数： +المعلمات الاختيارية: -- `dimensions`：裁剪向量维度，默认输出完整维度。 -- `encoding_format`：返回格式，可选 `float` 或 `base64`。 +- `dimensions`: اقتطاع أبعاد المتجه، ويكون الإخراج الافتراضي بالأبعاد الكاملة. +- `encoding_format`: تنسيق الإرجاع، ويمكن أن يكون `float` أو `base64`.

-Python 样例调用代码： +رمز استدعاء نموذجي بلغة Python: ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -调用之后，我们发现返回结果如下： +بعد الاستدعاء، نجد أن النتيجة المُرجعة كما يلي: ```json { @@ -97,7 +97,7 @@ print(response.text) ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,25 +105,25 @@ print(response.text) } ``` -返回结果一共有多个字段，介绍如下： +تحتوي النتيجة المُرجعة على عدة حقول، ويُقدَّم شرحها كما يلي: -- `model`，此次文本转词向量所采用的模型。 -- `usage`，此次文本转词向量所使用的token信息。 -- `data`，文本转化后的词向量结果。 +- `model`، النموذج المُستخدم في تحويل هذا النص إلى متجهات كلمات. +- `usage`، معلومات token المستخدمة في تحويل هذا النص إلى متجهات كلمات. +- `data`، نتيجة متجهات الكلمات بعد تحويل النص. -其中 `data` 是包含了文本对应的词向量的具体信息，它里面的 `embedding` 是生成的词向量具体结果。 +من بينها، يحتوي `data` على المعلومات التفصيلية لمتجهات الكلمات المقابلة للنص، ويكون `embedding` داخله هو النتيجة التفصيلية لمتجهات الكلمات المُنشأة. -## 错误处理 +## معالجة الأخطاء -在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如： +عند استدعاء API، إذا واجهت خطأً، فسيُرجع API رمز الخطأ والمعلومات المقابلة. على سبيل المثال: -- `400 token_mismatched`：请求错误，可能是由于缺少或无效的参数。 -- `400 api_not_implemented`：请求错误，可能是由于缺少或无效的参数。 -- `401 invalid_token`：未授权，授权令牌无效或缺失。 -- `429 too_many_requests`：请求过多，您已超出速率限制。 -- `500 api_error`：内部服务器错误，服务器出现问题。 +- `400 token_mismatched`: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة. +- `400 api_not_implemented`: طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة. +- `401 invalid_token`: غير مصرح، رمز التفويض غير صالح أو مفقود. +- `429 too_many_requests`: عدد كبير جدًا من الطلبات، لقد تجاوزت حد المعدل. +- `500 api_error`: خطأ داخلي في الخادم، حدث خطأ ما على الخادم. -### 错误响应示例 +### مثال على استجابة الخطأ ```json { @@ -136,6 +136,6 @@ print(response.text) } ``` -## 结论 +## الخلاصة -通过本文档，您已经了解了如何使用 OpenAI Embeddings API 轻松使用官方 OpenAI 的词向量生成的功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。 +من خلال هذا المستند، أصبحت تعرف بالفعل كيفية استخدام واجهة OpenAI Embeddings API لاستخدام ميزة إنشاء متجهات الكلمات الرسمية من OpenAI بسهولة. نأمل أن يساعدك هذا المستند على الربط واستخدام API بشكل أفضل. إذا كانت لديك أي أسئلة، فيُرجى التواصل مع فريق الدعم الفني لدينا في أي وقت. diff --git a/ar/guides/platform/wework_bot.mdx b/ar/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..450591586 --- /dev/null +++ b/ar/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "روبوت WeCom" +description: "Platform API guide - Ace Data Cloud" +--- + +انشر مثيل حساب WeCom خاص بك، وسجّل الدخول عبر مسح رمز QR باستخدام WeCom على الهاتف، واقرأ الحساب وجهات الاتصال والمحادثات والرسائل المتزامنة محليًا عبر REST API أو MCP. يمثّل المثيل حساب WeCom عاديًا، ولا يتطلب خادمًا خاصًا أو إعداد نطاق بريد إلكتروني للشركة. + +الحالة الحالية Alpha. اكتملت مصادقة حقيقية لقراءة الحساب والمحادثات؛ واكتمل قبول حقيقي لإرسال النصوص من صاحب الحساب وقراءة الأحداث المرتجعة؛ ولا تزال عمليات جهات الاتصال الأخرى والمجموعات واستعادة المثيلات الجديدة تتطلب قبولًا في بيئة النشر. إرسال الوسائط والرد بالاقتباس و@ الفعلية وإدارة أعضاء المجموعة وإيصالات التسليم غير متاحة بعد. يُرجى الاعتماد على القيمة المرجعة من `/api/capabilities` الخاصة بالمثيل. + +## النشر وتسجيل الدخول + +فعّل الخدمة ضمن تصنيف Deployment واختر باقة مدة المثيل. بعد النشر، افتح صفحة الإدارة وامسح الرمز باستخدام WeCom الخاص بصاحب الحساب؛ إذا كان تأكيد الهاتف أو خطوات تسجيل دخول أخرى مطلوبة، فافتح سطح المكتب البعيد وأدخل كلمة مرور سطح المكتب لذلك المثيل. بيانات اعتماد API وكلمة مرور سطح المكتب منفصلتان. تُحفظ بيانات تسجيل الدخول على قرص المثيل، وتؤدي إعادة إنشاء الحاوية إلى الاحتفاظ بالقرص؛ وحذف القرص سيحذف الجلسة المحلية. + +يتم احتساب رسوم كل مثيل بشكل مستقل، ويعمل وفق المدة المشتراة. لا تُفرض رسوم منفصلة لكل رسالة على استدعاءات REST / MCP، ويُرجى الرجوع إلى صفحة الباقة لمعرفة السعر الفعلي. تعتمد المرجعية الافتراضية الحالية على باقة مدة روبوت WeChat، ويجب تأكيد التسعير بالاقتران مع موارد التشغيل قبل الإتاحة النهائية. + +## API وMCP + +استخدم عنوان API للمثيل في صفحة الإدارة، وتحمل جميع واجهات الحساب `Authorization: Bearer <رمز API للمثيل>`. هذه المسارات تخص مثيلًا مخصصًا وليست بوابة API مشتركة. عنوان MCP هو عنوان المثيل مضافًا إليه `/mcp/`، ويستخدم رمز Bearer نفسه. + +| الواجهة | الوظيفة | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`،`GET /api/auth/status` | ما إذا كان الحساب جاهزًا وقائمة القدرات | +| `GET /api/auth/qr` | PNG Base64 لرمز QR الحالي لتسجيل الدخول | +| `GET /api/account` | الحساب الحالي | +| `GET /api/contacts?kind=all` | الزملاء الداخليون وجهات الاتصال الخارجية، ويمكن تحديد internal / external | +| `GET /api/conversations` | المحادثات المحلية، مع الاحتفاظ بمعرّف المحادثة الأصلي | +| `GET /api/messages` | الرسائل المتزامنة محليًا؛ معاملات conversation_id وafter_rowid وlimit | +| `POST /api/search` | البحث في جهات الاتصال والمحادثات والنصوص المحلية | +| `POST /api/messages` | مهمة إرسال نصية غير متزامنة، ويجب توفير Idempotency-Key | +| `POST /api/messages/send` | نقطة إدخال الإرسال نفسها، تدعم هدفًا واحدًا أو أهدافًا متعددة | +| `GET /api/groups/{conversation_id}` | معلومات المجموعة وأعضاؤها المتزامنون محليًا | +| `GET /api/tasks` | المهام الأخيرة ونتائج كل هدف | +| `GET /api/tasks/{id}` | الاستعلام عن نتيجة الإرسال | +| `POST /api/tasks/{id}/cancel` | إلغاء مهمة لم تبدأ بعد | +| `POST /api/runtime/pause`،`POST /api/runtime/resume` | إيقاف الأتمتة مؤقتًا؛ والاستئناف بعد تحقق صاحب الحساب | +| `GET /api/diagnostics`،`GET /api/diagnostics/screenshot` | حالة المثيل والشاشة الحالية، وكلاهما يتطلب مصادقة | +| `GET /api/events?after=0` | أحداث الرسائل ذات المؤشر القابل للاستئناف | +| `WS /ws` | تدفق أحداث الرسائل، مصادقة Bearer | + +تتضمن حمولة الإرسال `target` و`type: "text"` و`text`. يقبل `target` معرّف المحادثة أو معرّف جهة الاتصال أو معرّف مستخدم المؤسسة أو الاسم الكامل الفريد؛ وتُفضّل المعرّفات؛ وإذا ظل اسم العرض غير قادر على تحديد موقع فريد، فسيرفض المثيل العملية ولن يخمّن الكائن. ستُفتح محادثة جهة الاتصال التي لا توجد لها محادثة محلية عبر العميل أولًا، ثم يُتحقق من معرّف المحادثة الفعلي قبل الإرسال. رأس الطلب `Idempotency-Key` يتكون من 8–128 حرفًا أو رقمًا أو `_.:-`. يجب أن تعيد الطلبات المتكررة للعملية نفسها استخدام المفتاح نفسه وجسم الطلب نفسه. + +استبدل `target` بمصفوفة `targets` للإرسال تسلسليًا إلى 1–50 هدفًا محددًا بوضوح. لا يمكن توفير كليهما في الوقت نفسه. يجب أن تكمل جميع الأهداف تحليل الهوية أولًا، وسيتم رفض الأسماء المستعارة المختلفة التي تشير إلى الكائن نفسه. بعد فشل أحد الأهداف، يتوقف الإرسال اللاحق، وتُسجّل نتيجة المهمة لكل عنصر على أنها `succeeded` أو `failed` أو `unknown` أو `not_attempted`؛ لا تعامل النجاح الجزئي على أنه نجاح كامل. لا تزال هذه العملية تتطلب قبولًا حقيقيًا لجهات اتصال محددة في بيئة النشر. + +قد تكون المهام في حالات queued أو running أو submitting أو succeeded أو failed أو unknown أو cancelled. تعني `succeeded` أنه بعد الإرسال تم العثور على النص المطابق ومعرّف رسالة الخادم في سجل المحادثة المقابل، وتظل `delivered` بقيمة null، ولا يعني ذلك أن الطرف الآخر قد استلمها. تعني unknown أن النتيجة غير واضحة، لذا تحقّق من السجلات التاريخية ولا تكرر الإرسال باستخدام مفتاح جديد. لا يعيد المثيل إرسال المهام المتقطعة تلقائيًا. + +لا يتضمن السجل إلا المحتوى الذي قام العميل بمزامنته بالفعل، ولا يمكن ضمان اكتمال السجل كله. قد تُرجع الرسائل غير النصية نوع unknown، ولم يُتح تنزيل المرفقات بعد. تحتفظ الأحداث بأحدث 10,000 سجل، وتشير `gap` إلى أن المؤشر قد تجاوز نافذة الاحتفاظ. لا يعيد الاتصال الأول تشغيل السجل القديم باعتباره رسائل جديدة. + +يمكن استخدام `server_accepted` و`server_id` في سجل الرسائل للتحقق مما إذا كان الخادم قد قبل الرسالة المحلية؛ وعند وجود سجل محلي فقط دون معرّف خادم، لا يمكن اعتبار الإرسال ناجحًا. لا تمثل هذه الحقول ما إذا كان المستلم قد استلم أو قرأ الرسالة. يحتفظ سجل الأحداث بالحالة عند إنشائها، ويجب استخدام واجهة سجل الرسائل للاستعلام عن حالة التأكيد الحالية. + +## الحساب وبيانات الاعتماد + +سجّل الدخول فقط إلى الحسابات التي يملك صاحبها صلاحية تشغيلها. اضبط رمز API في التطبيقات الموثوقة؛ إذ يمكنه الوصول إلى بيانات حساب ذلك المثيل. لا تنشر كلمة المرور أو رمز QR أو لقطات شاشة الدردشة في أماكن عامة. سيؤدي إيقاف المثيل مؤقتًا إلى مقاطعة الأحداث في الوقت الفعلي. بعد تسجيل خروج الحساب أو إزالة الجهاز من الهاتف، يلزم تسجيل الدخول مجددًا. + +يدعم إدخال النص الحالي سطرًا واحدًا فقط، وسيتم رفض فواصل الأسطر صراحةً قبل الإرسال. عندما يطلب العميل تحققًا أمنيًا أو تسجيل دخول مجددًا، يجب أن يكمله صاحب الحساب عبر سطح المكتب البعيد؛ ولن يتجاوز المثيل التحقق. قد تُرجع المهام بعد انقطاع التحقق unknown، لذا استعلم عن سجل الرسائل أولًا، ولا تعاود الإرسال بمفتاح تكرار جديد. + +عند اكتشاف مطالبة تحقق أمني أو تسجيل خروج الحساب أو تغييره، ستتوقف قائمة انتظار الأتمتة مؤقتًا بشكل دائم. بعد إكمال تحقق الهاتف، يمكنك متابعة المهام التي لم تُنفذ بعد عبر «الاستئناف بعد التحقق» في وحدة تحكم المثيل؛ ولن تُعاد المهام التي تم إرسالها بالفعل لكن نتيجتها غير مؤكدة. قد يؤدي العمل العادي عن بُعد أيضًا إلى تشغيل التحقق الأمني في WeCom. إن نافذة الـ24 ساعة بعد التحقق التي توضحها التعليمات الرسمية لعدم القفل مجددًا لا تعني أنه تم إلغاء الكشف، ولا تعني أن المثيل يستطيع ضمان التشغيل طويل الأمد دون مراقبة. diff --git a/de/guides/claude/claude_messages.mdx b/de/guides/claude/claude_messages.mdx index 7f154030d..9450e50c1 100644 --- a/de/guides/claude/claude_messages.mdx +++ b/de/guides/claude/claude_messages.mdx @@ -3,41 +3,42 @@ title: "Beantragung und Nutzung der Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude ist ein sehr leistungsstarkes KI-Dialogsystem, das durch die Eingabe eines Prompts innerhalb weniger Sekunden flüssige und natürliche Antworten generieren kann. Die Claude Messages API ist das offizielle native API-Format von Anthropic. Im Gegensatz zum mit OpenAI kompatiblen Format (Chat Completion) verwendet sie die eigene Anfrage- und Antwortstruktur von Anthropic und kann die einzigartigen Fähigkeiten von Claude besser nutzen, wie multimodale Inhaltseingaben, Tool-Aufrufe, erweitertes Denken (Extended Thinking) und andere fortgeschrittene Funktionen. +Anthropic Claude ist ein sehr leistungsstarkes KI-Dialogsystem, das nach der Eingabe eines Prompt-Worts innerhalb weniger Sekunden flüssige und natürliche Antworten generieren kann. Die Claude Messages API ist das offizielle native API-Format von Anthropic. Anders als das mit OpenAI kompatible Format (Chat Completion) verwendet sie die eigene Anfrage- und Antwortstruktur von Anthropic und kann die einzigartigen Fähigkeiten von Claude besser nutzen, wie multimodale Inhaltseingaben, Tool-Aufrufe, Deep Thinking (Extended Thinking) und andere erweiterte Funktionen. -Dieses Dokument stellt hauptsächlich den Nutzungsprozess der Claude Messages API vor. Damit können wir die Dialogfunktionen von Claude über eine native Schnittstelle aufrufen, die mit der offiziellen Schnittstelle von Anthropic übereinstimmt. +Dieses Dokument stellt hauptsächlich den Nutzungsablauf der Claude Messages API vor. Mit ihr können wir die Dialogfunktionen von Claude über eine native Schnittstelle aufrufen, die mit der offiziellen von Anthropic übereinstimmt. ## Beantragungsprozess -Um die Claude Messages API zu verwenden, rufen Sie zunächst die [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) auf, um Ihr API-Token zu erhalten und es für später aufzubewahren. +Um die Claude Messages API zu verwenden, rufen Sie zunächst die [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) auf, um Ihr API-Token zu erhalten, und bewahren Sie es als Reserve auf. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Falls Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück. -**Ein API-Token kann alle Plattformdienste aufrufen; es ist nicht erforderlich, für jeden Dienst separat einen Antrag zu stellen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben zur kostenlosen Nutzung; bei unzureichendem Guthaben können Sie in der [Konsole](https://platform.acedata.cloud/console/coin) ein allgemeines Guthaben aufladen. +**Ein API-Token kann alle Plattformdienste aufrufen; es ist nicht erforderlich, jeden Dienst einzeln zu beantragen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben und können den Dienst kostenlos testen; bei unzureichendem Guthaben können Sie in der [Konsole](https://platform.acedata.cloud/console/coin) ein allgemeines Guthaben aufladen. > 📘 Vollständige Dokumentation: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) -## Grundlegende Nutzung +## Grundlegende Verwendung -Der Anfragepfad der Claude Messages API lautet `/v1/messages` und entspricht der offiziellen API von Anthropic. Wir müssen mindestens drei Pflichtparameter bereitstellen: +Der Anfragepfad der Claude Messages API lautet `/v1/messages` und stimmt mit der offiziellen API von Anthropic überein. Wir müssen mindestens drei Pflichtparameter bereitstellen: -- `model`: Wählt das zu verwendende Claude-Modell aus. `claude-opus-5-5` wird nur über die Messages API bereitgestellt, unterstützt 1 Million Token Kontext, maximal 128K Ausgabe-Token und aktiviert stets adaptives Denken. Das neueste Flaggschiff ist `claude-fable-5-1` (1 Million Token Kontext, maximal 128K Ausgabe-Token); das ursprüngliche `claude-fable-5` bleibt weiterhin kompatibel verfügbar. `claude-sonnet-5-5` wurde zur nativen Messages-Serienschnittstelle hinzugefügt und unterstützt Bildeingaben und adaptives Denken; die offiziellen Referenzpreise für Eingabe, Ausgabe und Cache-Lesen betragen jeweils 2, 10 und 0,20 US-Dollar pro Million Token. -- `messages`: Das Array der eingegebenen Nachrichten. Jede Nachricht enthält `role` (Rolle) und `content` (Inhalt), wobei `role` `user` und `assistant` unterstützt. -- `max_tokens`: Die maximale Anzahl an Ausgabe-Token, die zur Begrenzung der Länge einer einzelnen Antwort verwendet wird. +- `model`: Wählen Sie das zu verwendende Claude-Modell aus. `claude-opus-5-5` wird nur über die Messages API bereitgestellt, unterstützt 1 Million Token Kontext, maximal 128K Ausgabe-Token und aktiviert stets adaptives Denken. Das neueste Flaggschiff ist `claude-fable-5-1` (1 Million Token Kontext, maximal 128K Ausgabe-Token); das ursprüngliche `claude-fable-5` bleibt weiterhin kompatibel verfügbar. `claude-sonnet-5-5` wurde zur nativen Messages-Serienschnittstelle hinzugefügt und unterstützt Bildeingaben sowie adaptives Denken; die offiziellen Referenzpreise für Eingabe, Ausgabe und Cache-Lesen betragen jeweils 2, 10 und 0,20 US-Dollar pro Million Token. +- `messages`: Das Array der eingegebenen Nachrichten, wobei jede Nachricht `role` (Rolle) und `content` (Inhalt) enthält und `role` `user` und `assistant` unterstützt. +- `max_tokens`: Die maximale Anzahl der Ausgabe-Token, um die Länge einer einzelnen Antwort zu begrenzen. Häufig verwendete optionale Parameter: -- `system`: System-Prompt, der zur Festlegung des Verhaltens und der Rolle des Modells verwendet wird. -- `temperature`: Zufälligkeit der Generierung, zwischen 0 und 1; je größer der Wert, desto stärker streuen die Antworten. +- `system`: System-Prompt, der zum Festlegen des Verhaltens und der Rolle des Modells verwendet wird. +- `temperature`: Generierungszufälligkeit, zwischen 0 und 1; je größer der Wert, desto stärker streuen die Antworten. - `stream`: Ob Streaming-Antworten verwendet werden; bei Einstellung auf `true` kann ein Effekt der zeichenweisen Rückgabe erzielt werden. - `stop_sequences`: Benutzerdefinierte Stoppsequenzen; das Modell beendet die Generierung, wenn es auf diese Texte trifft. -- `top_p`: Parameter für Nucleus Sampling, der zusammen mit temperature die Zufälligkeit der Generierung steuert. +- `top_p`: Parameter für Nukleus-Sampling, der zusammen mit temperature die Zufälligkeit der Generierung steuert. - `top_k`: Es wird nur aus den K Optionen mit der höchsten Wahrscheinlichkeit gesampelt. -- `tools`: Tool-Definitionen, die es dem Modell ermöglichen, externe Funktionen aufzurufen. +- `tools`: Tool-Definitionen, die verwendet werden, damit das Modell externe Funktionen aufruft. - `tool_choice`: Steuert, wie das Modell die bereitgestellten Tools verwendet. -- `cache_control`: Erstellt automatisch einen Cache-Unterbrechungspunkt beim letzten zwischenspeicherbaren Inhaltsblock der Anfrage; kann auch in einen konkreten Inhaltsblock geschrieben werden. +- `cache_control`: Erstellt automatisch einen Cache-Haltepunkt beim letzten cachefähigen Inhaltsblock der Anfrage; kann auch auf einen konkreten Inhaltsblock geschrieben werden. +- `metadata`: Optionales Anfrage-Metadatenobjekt. `metadata.user_id` ist eine Zeichenfolge und kann eine vom Aufrufer benutzerdefinierte Benutzerkennung übergeben, beispielsweise `{"user_id":"example-user-001"}`; es wird empfohlen, eine stabile Kennung ohne personenbezogene Informationen zu verwenden. Sie ersetzt nicht die `Authorization`-Authentifizierung und muss auch nicht in den Dialoginhalt von `messages` geschrieben werden. ### cURL-Beispiel @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -107,24 +110,24 @@ Nach dem Aufruf lautet das Rückgabeergebnis wie folgt: ``` Erläuterung der Felder des Rückgabeergebnisses: - -- `id`: Eindeutiger Bezeichner dieser Nachricht. +- `id`: Die eindeutige Kennung dieser Nachricht. - `type`: Immer `message`. - `role`: Immer `assistant`. -- `content`: Array mit Antwortinhalten; jedes Element enthält `type` (wie `text`) und den entsprechenden Inhalt. -- `model`: Name des Modells, das die Anfrage verarbeitet. -- `stop_reason`: Grund für das Beenden. Stabile Werte umfassen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (der aktuelle assistant-Inhalt kann unverändert zurückgesendet werden, um fortzufahren), `refusal` und `model_context_window_exceeded`. -- `stop_sequence`: Wenn aufgrund einer benutzerdefinierten Stoppsequenz beendet wurde, wird der übereinstimmende Text der Stoppsequenz angezeigt. +- `content`: Ein Array mit Antwortinhalten, wobei jedes Element `type` (z. B. `text`) und den entsprechenden Inhalt enthält. +- `model`: Der Name des Modells, das die Anfrage verarbeitet. +- `stop_reason`: Der Grund für das Beenden. Stabile Werte umfassen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (der aktuelle Assistant-Inhalt kann unverändert zurückgegeben werden, um fortzufahren), `refusal` und `model_context_window_exceeded`. +- `stop_sequence`: Wenn aufgrund einer benutzerdefinierten Stoppsequenz beendet wurde, wird der Text der übereinstimmenden Stoppsequenz angezeigt. - `stop_details`: Wenn `stop_reason` `refusal` ist, kann dies die Ablehnungskategorie und eine Erläuterung enthalten. -- `usage`: Token-Nutzungsstatistik. `input_tokens` sind nicht zwischengespeicherte Eingaben; `cache_creation_input_tokens` und `cache_read_input_tokens` stehen jeweils für Cache-Schreiben und -Lesen; `output_tokens` ist die Gesamtzahl der Ausgabe-Token. Falls `output_tokens_details.thinking_tokens` zurückgegeben wird, ist dieser Wert eine Teilmenge von `output_tokens`; bei der Berechnung der Gesamtmenge oder der Kosten darf er nicht erneut addiert werden. Diese Detailangabe kann `null` sein oder weggelassen werden, wenn keine maßgebliche Zählung vorhanden ist. -- `usage.cache_creation`: Optionale TTL-Details für Cache-Schreibvorgänge, einschließlich `ephemeral_5m_input_tokens` und `ephemeral_1h_input_tokens`. Wenn das Objekt vorhanden ist, entspricht die Summe beider Werte `cache_creation_input_tokens`; ein Feldwert von `null` oder ein fehlendes Feld bedeutet, dass die aktuelle Antwort keine verfügbare TTL-Aufschlüsselung enthält und nicht als `0` interpretiert werden darf. -- `usage.cost`: Nicht-streamende Antworten können ein von Ace Data Cloud erfasstes Objekt zum Guthabenverbrauch enthalten, wobei `amount` der tatsächlich verbrauchte Betrag dieser Anfrage ist, `currency` die Abrechnungseinheit und `list_amount` der Betrag vor Rabatt (falls vorhanden). Der offizielle Grundpreis für das Lesen des Fable-5.1-Cache beträgt $0.25/Million Token; die Grundpreise für Cache-Schreibvorgänge mit 5 Minuten bzw. 1 Stunde betragen $12.50 bzw. $20/Million Token; die tatsächlichen Plattformpreise werden entsprechend den Planrabatten umgerechnet. +- `usage`: Statistiken zur Token-Nutzung. `input_tokens` sind nicht zwischengespeicherte Eingaben; `cache_creation_input_tokens` und `cache_read_input_tokens` stehen jeweils für Cache-Schreibvorgänge und -Lesevorgänge; `output_tokens` ist die Gesamtzahl der Ausgabe-Token. Wenn `output_tokens_details.thinking_tokens` zurückgegeben wird, ist dieser Wert eine Teilmenge von `output_tokens` und darf bei der Berechnung der Gesamtsumme oder der Kosten nicht erneut hinzugefügt werden. Wenn für diese Detailangabe keine maßgebliche Zählung vorliegt, kann sie `null` sein oder weggelassen werden. +- `usage.cache_creation`: Optionale TTL-Details für Cache-Schreibvorgänge, einschließlich `ephemeral_5m_input_tokens` und `ephemeral_1h_input_tokens`. Wenn das Objekt vorhanden ist, entspricht die Summe beider Werte `cache_creation_input_tokens`; ein Feld mit `null` oder ein weggelassenes Feld bedeutet, dass für die aktuelle Antwort keine verfügbare TTL-Aufschlüsselung vorliegt und nicht als `0` interpretiert werden kann. +- `usage.cost`: Nicht-streamende Antworten können ein von Ace Data Cloud erfasstes Objekt zum Kreditverbrauch enthalten, wobei `amount` der tatsächlich bei diesem Vorgang verbrauchte Betrag, `currency` die Maßeinheit und `list_amount` der Betrag vor Rabatt (falls vorhanden) ist. Der offizielle Grundpreis für Cache-Lesevorgänge von Fable 5.1 beträgt 0,25 $/Million Token, und die Grundpreise für Cache-Schreibvorgänge mit 5 Minuten bzw. 1 Stunde betragen 12,50 $ bzw. 20 $/Million Token; die tatsächlichen Plattformpreise werden anhand des Tarifrabatts umgerechnet. ## System-Prompt -Die Claude Messages API unterstützt die Festlegung eines System-Prompts über das Feld `system`, um das Verhalten, die Rolle und den Kontext des Modells zu definieren. +Die Claude Messages API unterstützt das Festlegen eines System-Prompts über das Feld `system`, um das Verhalten, die Rolle und den Kontext des Modells zu definieren. ### Python-Beispiel + ```python import requests @@ -139,7 +142,7 @@ headers = { payload = { "model": "claude-sonnet-4-20250514", "max_tokens": 1024, - "system": "Du bist ein professioneller chinesischer Übersetzungsassistent. Bitte übersetze die englische Eingabe des Benutzers ins Chinesische.", + "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。", "messages": [ {"role": "user", "content": "The quick brown fox jumps over the lazy dog."} ] @@ -151,9 +154,9 @@ print(response.json()) Durch das Festlegen des `system`-Prompts können die Rolle und das Verhalten von Claude präzise gesteuert werden. -## Streaming-Antworten +## Streamende Antworten -Diese Schnittstelle unterstützt auch Streaming-Antworten. Setzen Sie den Parameter `stream` auf `true`, um eine schrittweise Rückgabe zu erhalten, was sich hervorragend für die zeichenweise Anzeige auf Webseiten eignet. +Diese Schnittstelle unterstützt auch streamende Antworten. Setzen Sie den Parameter `stream` auf `true`, um eine schrittweise Rückgabe zu erhalten, was sich hervorragend für die zeichenweise Anzeige auf Webseiten eignet. ### Python-Beispiel @@ -183,14 +186,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Streaming-Antworten werden im Server-Sent Events (SSE)-Format zurückgegeben, wobei jede Zeile mit `event:` und `data:` beginnt. Zu den Streaming-Ereignistypen gehören: +Streamende Antworten werden im Server-Sent Events (SSE)-Format zurückgegeben, wobei jede Zeile mit `event:` und `data:` beginnt. Die Typen der Streaming-Ereignisse umfassen: -- `message_start`: Nachricht beginnt und enthält grundlegende Informationen über die Nachricht sowie den Modellnamen. -- `content_block_start`: Inhaltsblock beginnt. -- `content_block_delta`: Inkrementelle Aktualisierung des Inhaltsblocks, enthält neu generierte Textfragmente. -- `content_block_stop`: Inhaltsblock endet. -- `message_delta`: Inkrementelle Aktualisierung auf Nachrichtenebene, enthält `stop_reason` und die endgültigen `usage`-Informationen. Der maßgebliche Wert von `output_tokens_details.thinking_tokens` sollte nur aus dem letzten `message_delta.usage` gelesen und nicht ereignisübergreifend addiert werden. -- `message_stop`: Nachricht endet. +- `message_start`: Die Nachricht beginnt und enthält grundlegende Informationen zur Nachricht sowie den Modellnamen. +- `content_block_start`: Der Inhaltsblock beginnt. +- `content_block_delta`: Inkrementelle Aktualisierung des Inhaltsblocks, die neu generierte Textfragmente enthält. +- `content_block_stop`: Der Inhaltsblock endet. +- `message_delta`: Inkrementelle Aktualisierung auf Nachrichtenebene, die `stop_reason` und die endgültigen `usage`-Informationen enthält. Der maßgebliche Wert von `output_tokens_details.thinking_tokens` sollte nur aus dem letzten `message_delta.usage` gelesen und nicht ereignisübergreifend addiert werden. +- `message_stop`: Die Nachricht endet. Die Ausgabe sieht wie folgt aus: @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Wie zu sehen ist, enthält das Ereignis `content_block_delta` in der Streaming-Antwort den schrittweise generierten Textinhalt. Durch das Zusammenfügen aller `text_delta` kann die vollständige Antwort erhalten werden. +Wie man sehen kann, enthalten die `content_block_delta`-Ereignisse in streamenden Antworten schrittweise generierte Textinhalte. Durch das Zusammenfügen aller `text_delta` kann die vollständige Antwort erhalten werden. ### JavaScript-Beispiel @@ -253,7 +256,7 @@ while (true) { ## Mehrturn-Dialoge -Wenn Sie die Funktion für Mehrturn-Dialoge integrieren möchten, müssen Sie Nachrichten mit den Rollen `user` und `assistant` abwechselnd im Array `messages` anordnen und den bisherigen Dialogverlauf gemeinsam übergeben. +Wenn Sie eine Mehrturn-Dialogfunktion anbinden möchten, müssen Sie Nachrichten mit den Rollen `user` und `assistant` abwechselnd im Array `messages` anordnen und den bisherigen Dialogverlauf gemeinsam übermitteln. ### Python-Beispiel @@ -283,7 +286,6 @@ print(response.json()) ``` Das Rückgabeergebnis lautet wie folgt: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,11 +307,11 @@ Das Rückgabeergebnis lautet wie folgt: } ``` -Durch die Übergabe des vollständigen Dialogverlaufs in `messages` kann Claude unter Berücksichtigung des Kontexts präzise antworten. +Durch die Übergabe des vollständigen Gesprächsverlaufs in `messages` kann Claude den Kontext für präzise Antworten nutzen. -## Modelle für tiefes Denken +## Tiefdenkende Modelle -Claudes thinking und thinking summary sind zwei unterschiedliche Konzepte: Das Modell kann interne Schlussfolgerungen durchführen, aber die API gibt keine originale Gedankenkette zurück. Wenn der Denkprozess angezeigt werden soll, gibt die API eine aufbereitete Zusammenfassung zurück. +Claudes thinking und thinking summary sind zwei unterschiedliche Konzepte: Das Modell kann intern Schlussfolgerungen ziehen, aber die API gibt nicht die ursprüngliche Gedankenkette zurück. Wenn der Denkprozess angezeigt werden muss, gibt die API eine verarbeitete Zusammenfassung zurück. Für aktuelle Modelle wird empfohlen, adaptive thinking zu verwenden und den gesamten Schlussfolgerungsaufwand über `output_config.effort` zu steuern: @@ -350,24 +352,25 @@ Der thinking-Block in der Antwort sieht wie folgt aus: "signature": "opaque-signature" } ``` -- `display: "summarized"` gibt eine lesbare Zusammenfassung der Überlegungen zurück; sie ist nicht die ursprüngliche Gedankenkette. -- `display: "omitted"` gibt `thinking: ""` zurück, behält jedoch die intransparente `signature` zur Unterstützung nachfolgender Gespräche bei. -- `display: "updates"` ist der Beta-Modus von Anthropic und erfordert `anthropic-beta: thinking-display-updates-2026-08-18`. Die offizielle Definition ist, den Text der Schlussfolgerungen auszublenden und kurze Fortschrittsaktualisierungen zwischen Tool-Aufrufen anzuzeigen. Die Plattform leitet diesen Parameter und den Beta-Request-Header unverändert weiter und schreibt ihn nicht zwangsweise in `summarized` um; der tatsächliche Ausgabeinhalt hängt von der Unterstützung des ausgewählten Modells ab. -- `thinking`, `output_config`, effort, Sampling-Parameter sowie neue Erweiterungsfelder werden unverändert weitergeleitet. Die Plattform verwaltet keine fest im Code hinterlegten Werteaufzählungen oder Kombinationsbeschränkungen pro Modell und schreibt Thinking-Modi nicht automatisch um; ob diese Parameter akzeptiert werden, entscheidet das ausgewählte Modell, und vom Modell zurückgegebene Parameterfehler werden an den Client weitergeleitet. -- Der Standardwert von display für Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 und Opus 4.7 ist `omitted`; Opus 4.6, Sonnet 4.6 und frühere Modelle mit Thinking-Unterstützung verwenden standardmäßig `summarized`. -- Display beeinflusst nur den Rückgabeinhalt und die Streaming-Latenz, deaktiviert das Schlussfolgern nicht und reduziert auch nicht die Abrechnung von Thinking-Token. -- Ob Thinking standardmäßig aktiviert ist und der Standardwert von display sind zwei unabhängige Fragen. Opus 5 und Sonnet 5 aktivieren adaptive thinking standardmäßig; bei Opus 5 entspricht das Weglassen von `thinking` adaptive, und das Weglassen von `output_config.effort` entspricht `high`. Opus 4.8, 4.7 und 4.6 müssen explizit aktiviert werden. -- Thinking und der endgültige Text teilen sich das Ausgabebudget von `max_tokens`. Bei einem zu kleinen Budget kann Thinking den Großteil des Kontingents belegen, sodass der Text leer bleibt oder abgeschnitten wird; erhöhen Sie bitte `max_tokens` oder verwenden Sie `low` / `medium` effort, um den Schlussfolgerungsaufwand zu steuern. -- Für Modelle, bei denen Thinking deaktiviert werden darf, kann `thinking: {"type":"disabled"}` übergeben werden. Neue Modi wie `between_tools` sowie effort-Kombinationen hängen vom ausgewählten Modell ab; die Plattform lehnt sie nicht vorab anhand alter Modellregeln ab. -- Ein festes Thinking-Budget kann über `budget_tokens` übergeben werden; neue Modelle verwenden normalerweise `thinking.type=adaptive` und `output_config.effort`. Ob ein festes Budget oder das Deaktivieren von Thinking unterstützt wird, richtet sich nach den aktuellen Fähigkeiten des ausgewählten Modells. -- Bei mehrteiligen Gesprächen und Tool-Aufrufen sollten der vollständige vom Assistant zurückgegebene Thinking-Block sowie die signature unverändert zurückgegeben werden; ändern oder erzeugen Sie die signature nicht selbst. -- Die Parameterweiterleitung bedeutet nicht, dass jedes Modell alle Funktionen unterstützt. Protokollübergreifende Aufrufe müssen weiterhin konvertiert werden; der Unterstützungsumfang und Fehler für Inhalte wie `redacted_thinking` werden vom Modelldienst bestimmt, der die Anfrage tatsächlich verarbeitet. - -Bei Streaming-Anfragen erzeugt `summarized` `thinking_delta`; `omitted` erzeugt kein `thinking_delta`, sondern behält nur den Lebenszyklus des Thinking-Blocks und `signature_delta` bei. + +- `display: "summarized"` gibt eine lesbare Denkzusammenfassung zurück; sie ist nicht die ursprüngliche Gedankenkette. +- `display: "omitted"` gibt `thinking: ""` zurück, behält jedoch die undurchsichtige `signature` zur Unterstützung nachfolgender Gespräche bei. +- `display: "updates"` ist der Beta-Modus von Anthropic und erfordert `anthropic-beta: thinking-display-updates-2026-08-18`. Die offizielle Definition lautet, dass der Text der versteckten Schlussfolgerungen ausgeblendet und kurze Fortschrittsaktualisierungen zwischen Tool-Aufrufen angezeigt werden. Die Plattform leitet diesen Parameter und den Beta-Anfrage-Header unverändert weiter und schreibt ihn nicht zwangsweise in `summarized` um; der tatsächliche Ausgabeinhalt hängt von der Unterstützung des ausgewählten Modells ab. +- `thinking`, `output_config`, effort, Sampling-Parameter und neue Erweiterungsfelder werden unverändert weitergeleitet. Die Plattform pflegt keine hartcodierten Werteaufzählungen oder Kombinationsbeschränkungen nach Modell und schreibt den thinking-Modus auch nicht automatisch um; ob diese Parameter akzeptiert werden, wird vom ausgewählten Modell bestimmt, und vom Modell zurückgegebene Parameterfehler werden an den Client weitergeleitet. +- Der Standardwert für display bei Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 und Opus 4.7 ist `omitted`; Opus 4.6, Sonnet 4.6 und frühere Modelle mit thinking-Unterstützung verwenden standardmäßig `summarized`. +- Display beeinflusst nur den Rückgabeinhalt und die Streaming-Latenz, deaktiviert die Schlussfolgerungen nicht und reduziert auch nicht die Abrechnung von thinking-Tokens. +- Ob thinking standardmäßig aktiviert ist und welcher display-Standardwert verwendet wird, sind zwei unabhängige Fragen. Opus 5 und Sonnet 5 aktivieren adaptive thinking standardmäßig; bei Opus 5 entspricht das Weglassen von `thinking` adaptive, und das Weglassen von `output_config.effort` entspricht `high`. Opus 4.8, 4.7 und 4.6 müssen explizit aktiviert werden. +- Thinking und der endgültige Text teilen sich das Ausgabe-Budget von `max_tokens`. Bei einem zu kleinen Budget kann thinking den Großteil des Kontingents verbrauchen, sodass der Text leer bleibt oder abgeschnitten wird; erhöhen Sie bitte `max_tokens` oder verwenden Sie `low` / `medium` effort, um den Schlussfolgerungsaufwand zu steuern. +- Für Modelle, bei denen thinking deaktiviert werden darf, kann `thinking: {"type":"disabled"}` übergeben werden. Neue Modi wie `between_tools` sowie effort-Kombinationen hängen vom ausgewählten Modell ab; die Plattform lehnt sie nicht vorab anhand alter Modellregeln ab. +- Ein festes Denkbudget kann über `budget_tokens` übergeben werden; neue Modelle verwenden üblicherweise `thinking.type=adaptive` und `output_config.effort`. Ob ein festes Budget oder das Deaktivieren des Denkens unterstützt wird, richtet sich nach den aktuellen Fähigkeiten des ausgewählten Modells. +- Bei mehrteiligen Gesprächen und Tool-Aufrufen sollten der vollständige thinking-Block und die signature, die vom assistant zurückgegeben wurden, unverändert zurückgesendet werden; ändern oder erzeugen Sie die signature nicht selbst. +- Die Parameterweiterleitung bedeutet nicht, dass jedes Modell alle Funktionen unterstützt. Protokollübergreifende Aufrufe müssen weiterhin konvertiert werden, und der Unterstützungsumfang sowie Fehler bei Inhalten wie `redacted_thinking` werden vom Modellservice bestimmt, der die Anfrage tatsächlich verarbeitet. + +In Streaming-Anfragen erzeugt `summarized` `thinking_delta`; `omitted` erzeugt kein `thinking_delta`, sondern behält nur den Lebenszyklus des thinking-Blocks und `signature_delta` bei. ## Visuelle Modelle -Claude unterstützt multimodale Eingaben und kann Text und Bilder gleichzeitig verarbeiten. In der Messages API können visuelle Fähigkeiten verwendet werden, indem `content` als Array festgelegt und ein Bildinhaltsblock übergeben wird. +Claude unterstützt multimodale Eingaben und kann Text und Bilder gleichzeitig verarbeiten. In der Messages API können visuelle Fähigkeiten verwendet werden, indem `content` auf ein Array-Format gesetzt und Bildinhaltsblöcke übergeben werden. ### Verwendung von Base64-kodierten Bildern @@ -456,7 +459,6 @@ print(response.json()) ``` ### cURL-Beispiel - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -490,7 +492,7 @@ Zu den unterstützten Bildformaten gehören: `image/jpeg`, `image/png`, `image/g ## Dokumente und PDF -PDF verwendet den `document`-Inhaltsblock und unterstützt die beiden stabilen Quellen Base64 und URL. Die Base64-Quelle muss `application/pdf` verwenden: +PDF verwendet den Inhaltsblock `document` und unterstützt zwei stabile Quellen: Base64 und URL. Die Base64-Quelle muss `application/pdf` verwenden: ```python import base64 @@ -523,7 +525,7 @@ Die URL-Quelle wird als `{"type":"url","url":"https://example.com/report.pdf"}` ## Prompt-Caching -Das oberste `cache_control` platziert den Cache-Haltepunkt automatisch beim letzten cachebaren Block: +Das oberste `cache_control` platziert den Cache-Unterbrechungspunkt automatisch auf dem letzten zwischenspeicherbaren Block: ```python payload = { @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Wenn eine präzise Positionssteuerung erforderlich ist, kann dasselbe `cache_control` auch auf text-, image-, document-, tool_use-, tool_result-Inhaltsblöcke oder Tool-Definitionen geschrieben werden. `ttl` unterstützt `5m` (Standard) und `1h`; bitte verwenden Sie `usage.cache_creation_input_tokens` und `usage.cache_read_input_tokens`, um Cache-Schreibvorgänge und Treffer zu bestimmen. -Wenn die Antwort `usage.cache_creation` bereitstellt, gilt `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Wenn `cache_creation` `null` ist oder ausgelassen wird, bedeutet dies, dass nur die Gesamtmenge der Cache-Schreibvorgänge vorliegt und keine maßgebliche TTL-Aufschlüsselung vorhanden ist; behandeln Sie in diesem Fall keinen Bucket als bekanntes 0, die Abrechnung und Gesamtmenge richten sich weiterhin nach dem aggregierten Feld. +Wenn eine präzise Positionskontrolle erforderlich ist, kann dasselbe `cache_control` auch auf text-, image-, document-, tool_use-, tool_result-Inhaltsblöcke oder Werkzeugdefinitionen geschrieben werden. `ttl` unterstützt `5m` (Standard) und `1h`; bestimmen Sie Cache-Schreibvorgänge und Treffer über `usage.cache_creation_input_tokens` und `usage.cache_read_input_tokens`. + +Wenn die Antwort `usage.cache_creation` bereitstellt, gilt `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Wenn `cache_creation` `null` ist oder ausgelassen wird, bedeutet dies, dass nur die Gesamtmenge der Cache-Schreibvorgänge und keine verlässliche TTL-Aufschlüsselung vorhanden ist; behandeln Sie in diesem Fall keinen Bucket als bekannten Wert von 0, Abrechnung und Gesamtmenge richten sich weiterhin nach dem aggregierten Feld. -Beispiel für ein Rückgabeergebnis: +Beispiel eines Rückgabeergebnisses: ```json { @@ -561,9 +564,9 @@ Beispiel für ein Rückgabeergebnis: } ``` -## Tool-Aufruf (Tool Use) +## Werkzeugaufrufe (Tool Use) -Die Claude Messages API unterstützt nativ Tool-Aufrufe und ermöglicht es dem Modell, bei Bedarf Ihre vordefinierten Tools/Funktionen aufzurufen. +Die Claude Messages API unterstützt nativ Werkzeugaufrufe und ermöglicht dem Modell, bei Bedarf Ihre vordefinierten Werkzeuge/Funktionen aufzurufen. ### Python-Beispiel @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Wenn das Modell entscheidet, ein Tool aufzurufen, enthält `content` im Rückgabeergebnis einen Inhaltsblock vom Typ `tool_use`: +Wenn das Modell entscheidet, ein Werkzeug aufzurufen, enthält `content` im Rückgabeergebnis einen Inhaltsblock vom Typ `tool_use`: ```json { @@ -637,7 +640,7 @@ Wenn das Modell entscheidet, ein Tool aufzurufen, enthält `content` im Rückgab } ``` -Beachten Sie, dass `stop_reason` `tool_use` ist, was bedeutet, dass das Modell ein Tool aufrufen muss. Nach Erhalt dieses Ergebnisses müssen Sie die Tool-Funktion ausführen und das Ergebnis in Form von `tool_result` an das Modell zurücksenden: +Beachten Sie, dass `stop_reason` `tool_use` ist, was bedeutet, dass das Modell ein Werkzeug aufrufen muss. Nach Erhalt dieses Ergebnisses müssen Sie die Werkzeugfunktion ausführen und das Ergebnis in Form von `tool_result` an das Modell zurückgeben: ```python payload = { @@ -685,37 +688,36 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Das Modell generiert auf Grundlage des vom Tool zurückgegebenen Ergebnisses die endgültige Antwort in natürlicher Sprache. +Das Modell generiert auf Grundlage des vom Werkzeug zurückgegebenen Ergebnisses eine abschließende Antwort in natürlicher Sprache. ## Unterschiede zur Chat Completion API -Ace Data Cloud bietet gleichzeitig zwei Claude-API-Formate an; die wesentlichen Unterschiede zwischen beiden sind wie folgt: +Ace Data Cloud bietet gleichzeitig zwei Claude-API-Formate an, deren Hauptunterschiede wie folgt sind: -`usage.input_tokens` der Messages API steht nur für nicht zwischengespeicherte Eingaben, während `cache_read_input_tokens` und `cache_creation_input_tokens` unabhängige Abrechnungs-Buckets sind; alle drei werden jeweils zu den entsprechenden Preisen berechnet. - -| Merkmal | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +`usage.input_tokens` der Messages API steht nur für nicht zwischengespeicherte Eingaben, während `cache_read_input_tokens` und `cache_creation_input_tokens` eigenständige Abrechnungs-Buckets sind; alle drei werden jeweils nach den entsprechenden Preisen berechnet. +| Funktion | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Format | Anthropic-natives Format | OpenAI-kompatibles Format | -| System-Prompt | Eigenständiges Feld `system` | Übergabe über `role: "system"` in `messages` | +| System-Prompt | Eigenständiges `system`-Feld | Über `role: "system"` in `messages` übergeben | | Antwortstruktur | `content`-Array (unterstützt mehrere Typen) | `choices`-Array (enthält `message`) | | Streaming-Format | SSE-Ereignisse (mehrere Ereignistypen) | SSE-`data`-Zeilen | -| Tiefes Nachdenken | Natives `thinking` und `output_config.effort` | Standardstrategie des Modells und Kompatibilitätsparameter | -| Tool-Aufruf | Natives `tools` + `input_schema` | OpenAI-kompatibles `tools`-Format | -| Token-Statistik | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | +| Tiefes Denken | Natives `thinking` und `output_config.effort` | Standardstrategie des Modells und Kompatibilitätsparameter | +| Tool-Aufrufe | Natives `tools` + `input_schema` | OpenAI-kompatibles `tools`-Format | +| Token-Statistiken | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Wenn Ihr System bereits eine API im OpenAI-Format integriert hat, können Sie die Chat Completion API für einen nahtlosen Wechsel verwenden. Wenn Sie alle nativen Funktionen von Claude nutzen müssen, wird die Messages API empfohlen. +Wenn Ihr System bereits eine API im OpenAI-Format integriert hat, können Sie die Chat Completion API für einen nahtlosen Wechsel verwenden. Wenn Sie alle nativen Fähigkeiten von Claude nutzen müssen, wird die Messages API empfohlen. ## Fehlerbehandlung -Die Fehlerantworten der öffentlichen Schnittstelle verwenden den Ace Data Cloud Plattform-Envelope: `error.code` ist ein stabiler Fehlercode, `error.message` ist eine Beschreibung und `trace_id` wird zur Fehleranalyse von Anfragen verwendet. Häufige HTTP-Status sind: +Die Fehlerantworten der öffentlichen Schnittstelle verwenden das Ace Data Cloud-Plattform-Envelope: `error.code` ist ein stabiler Fehlercode, `error.message` ist eine Beschreibung, und `trace_id` wird zur Untersuchung von Anfragen verwendet. Häufige HTTP-Statuswerte umfassen: -- `400`: Anfrageparameter oder Protokollinhalt ungültig. -- `401`: Autorisierungstoken ungültig, fehlt oder ist abgelaufen. -- `403`: Zugriff verboten, unzureichendes Guthaben oder begrenztes Kontingent. +- `400`: Anforderungsparameter oder Protokollinhalt sind ungültig. +- `401`: Das Autorisierungstoken ist ungültig, fehlt oder ist abgelaufen. +- `403`: Zugriff verweigert, unzureichendes Guthaben oder eingeschränkte Quote. - `404`: API oder Modell existiert nicht. -- `413`: Anfragekörper zu groß. +- `413`: Anfragekörper ist zu groß. - `429`: Zu viele Anfragen. -- `500` / `503` / `504`: Dienstfehler, vorübergehend nicht verfügbar oder Verarbeitungszeitüberschreitung. +- `500` / `503` / `504`: Dienstfehler, vorübergehend nicht verfügbar oder Verarbeitungs-Timeout. ### Beispiel für eine Fehlerantwort @@ -729,7 +731,8 @@ Die Fehlerantworten der öffentlichen Schnittstelle verwenden den Ace Data Cloud } ``` -Diese Fehlerstruktur ist der Laufzeitvertrag von Ace Data Cloud und entspricht nicht dem offiziellen Fehler-Envelope von Anthropic; bitte behandeln Sie sie anhand des HTTP-Status und von `error.code`. +Diese Fehlerstruktur ist der Laufzeitvertrag von Ace Data Cloud und entspricht nicht dem offiziellen Anthropic-Fehler-Envelope; bitte behandeln Sie sie anhand des HTTP-Status und von `error.code`. ## Fazit -Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Claude Messages API verwenden, um die Konversationsfunktionen von Claude im Anthropic-nativen Format aufzurufen. Die Messages API unterstützt umfangreiche Funktionen wie grundlegende Konversationen, System-Prompts, Streaming-Antworten, mehrstufige Konversationen, tiefgreifendes Denken, visuelles Verständnis, PDFs, Prompt-Caching und Tool-Aufrufe. Bei Fragen können Sie sich jederzeit an unser technisches Support-Team wenden. + +Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Konversationsfunktionen von Claude über die Claude Messages API im Anthropic-nativen Format aufrufen können. Die Messages API unterstützt umfangreiche Funktionen wie grundlegende Konversationen, System-Prompts, Streaming-Antworten, mehrstufige Konversationen, tiefes Denken, visuelles Verständnis, PDFs, Prompt-Caching und Tool-Aufrufe. Bei Fragen können Sie sich jederzeit an unser technisches Support-Team wenden. diff --git a/de/guides/openai/openai_embeddings.mdx b/de/guides/openai/openai_embeddings.mdx index de3e534b9..5f68c1c49 100644 --- a/de/guides/openai/openai_embeddings.mdx +++ b/de/guides/openai/openai_embeddings.mdx @@ -1,37 +1,37 @@ --- -title: "OpenAI Embeddings API Antrag und Nutzung" +title: "Beantragung und Nutzung der OpenAI Embeddings API" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI Wortvektor-Dienst, um Wortvektor-Ergebnisse zu generieren, die den eingegebenen Text darstellen. +OpenAI-Wortvektordienst, der zum Generieren von Wortvektorergebnissen verwendet wird, welche den eingegebenen Text darstellen. -Dieses Dokument beschreibt hauptsächlich den Ablauf der Nutzung der OpenAI Embeddings API, mit der wir Einbettungsvektoren erstellen können, die den eingegebenen Text darstellen. +Dieses Dokument stellt hauptsächlich den Nutzungsprozess der OpenAI Embeddings API vor. Mit ihr können wir Einbettungsvektoren erstellen, die den eingegebenen Text darstellen。。 -## Antragsprozess +## Beantragungsprozess -Um die OpenAI Embeddings API zu nutzen, müssen Sie zunächst im [Ace Data Cloud Dashboard](https://platform.acedata.cloud/console/applications) Ihr API-Token abrufen und für später aufbewahren. +Um die OpenAI Embeddings API zu verwenden, rufen Sie zunächst die [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) auf, um Ihren API-Token zu erhalten, und bewahren Sie ihn zur späteren Verwendung auf. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, die Sie zur Registrierung und Anmeldung einlädt. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet. +Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, auf der Sie zur Registrierung und Anmeldung eingeladen werden. Nach Abschluss kehren Sie automatisch zu dieser Seite zurück. -**Ein API-Token reicht aus, um alle Dienste der Plattform zu nutzen, es ist nicht erforderlich, für jeden Dienst separat einen Antrag zu stellen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent nicht ausreicht, können Sie im [Dashboard](https://platform.acedata.cloud/console/coin) Ihr allgemeines Guthaben aufladen. +**Ein API-Token kann alle Dienste der Plattform aufrufen; es ist nicht erforderlich, für jeden Dienst einzeln einen Antrag zu stellen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben, das Sie zum kostenlosen Ausprobieren verwenden können; bei unzureichendem Guthaben können Sie in der [Konsole](https://platform.acedata.cloud/console/coin) ein allgemeines Guthaben aufladen. > 📘 Vollständige Dokumentation: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## Grundlegende Nutzung +## Grundlegende Verwendung -Als Nächstes können Sie im Interface die entsprechenden Inhalte ausfüllen, wie im Bild gezeigt: +Als Nächstes können Sie die entsprechenden Inhalte in der Benutzeroberfläche ausfüllen, wie in der Abbildung gezeigt:

-Bei der ersten Nutzung dieser Schnittstelle müssen wir mindestens drei Inhalte ausfüllen: einer ist `authorization`, den Sie einfach aus der Dropdown-Liste auswählen können. Ein weiterer Parameter ist `model`, `model` ist die Modellkategorie, die wir von der OpenAI-Website auswählen. Hier haben wir hauptsächlich 3 Modelle, die Details können Sie in den von uns bereitgestellten Modellen einsehen. Der letzte Parameter ist `input`, `input` ist der Text, den wir in einen Wortvektor umwandeln möchten. +Bei der ersten Verwendung dieser Schnittstelle müssen wir mindestens drei Inhalte ausfüllen. Einer davon ist `authorization`, den Sie direkt in der Auswahlliste auswählen können. Ein weiterer Parameter ist `model`; `model` ist die Modellkategorie der offiziellen OpenAI-Website, die wir zur Verwendung auswählen. Die derzeit verfügbaren Modelle sind `text-embedding-3-small` und `text-embedding-3-large`. `text-embedding-ada-002` wird nicht mehr angeboten; wenn bestehende Vektorindizes dieses alte Modell verwenden, können die Vektoren neuer Modelle nicht direkt gemischt verwendet werden, und der Index muss neu erstellt werden. Der letzte Parameter ist `input`; `input` ist der Text, dessen Wortvektoren wir umwandeln müssen. -Gleichzeitig können Sie auf der rechten Seite den entsprechenden Code zur Durchführung der Anfrage sehen, den Sie kopieren und direkt ausführen können, oder Sie können einfach auf die Schaltfläche „Try“ klicken, um einen Test durchzuführen. +Gleichzeitig können Sie beachten, dass auf der rechten Seite entsprechender generierter Aufrufcode vorhanden ist. Sie können den Code kopieren und direkt ausführen oder direkt auf die Schaltfläche „Try“ klicken, um ihn zu testen. Optionale Parameter: -- `dimensions`: Zuschneiden der Vektordimensionen, standardmäßig wird die vollständige Dimension ausgegeben. +- `dimensions`: Schneidet die Vektordimension zu, standardmäßig wird die vollständige Dimension ausgegeben. - `encoding_format`: Rückgabeformat, wahlweise `float` oder `base64`.

@@ -50,8 +50,8 @@ headers = { } payload = { - "input": "Das Essen war köstlich und der Kellner...", - "model": "text-embedding-ada-002", + "input": "The food was delicious and the waiter...", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -97,7 +97,7 @@ Nach dem Aufruf stellen wir fest, dass das Rückgabeergebnis wie folgt aussieht: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -107,23 +107,23 @@ Nach dem Aufruf stellen wir fest, dass das Rückgabeergebnis wie folgt aussieht: Das Rückgabeergebnis enthält mehrere Felder, die wie folgt beschrieben werden: -- `model`, das Modell, das für die Umwandlung des Textes in einen Wortvektor verwendet wurde. -- `usage`, die Token-Informationen, die für die Umwandlung des Textes in einen Wortvektor verwendet wurden. -- `data`, das Ergebnis des umgewandelten Wortvektors. +- `model`, das Modell, das bei dieser Umwandlung von Text in Wortvektoren verwendet wurde. +- `usage`, die Token-Informationen, die bei dieser Umwandlung von Text in Wortvektoren verwendet wurden. +- `data`, das Ergebnis der Wortvektoren nach der Textumwandlung. -Dabei enthält `data` die spezifischen Informationen über den entsprechenden Wortvektor des Textes, wobei `embedding` das spezifische Ergebnis des generierten Wortvektors ist. +Dabei enthält `data` die spezifischen Informationen zu den Wortvektoren, die dem Text entsprechen, und das darin enthaltene `embedding` ist das konkrete Ergebnis der generierten Wortvektoren. ## Fehlerbehandlung -Wenn beim Aufruf der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die Informationen zurück. Zum Beispiel: +Wenn bei der Aufrufung der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die entsprechende Information zurück. Zum Beispiel: -- `400 token_mismatched`: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter. -- `400 api_not_implemented`: Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter. -- `401 invalid_token`: Unbefugt, ungültiges oder fehlendes Autorisierungstoken. -- `429 too_many_requests`: Zu viele Anfragen, Sie haben das Rate-Limit überschritten. -- `500 api_error`: Interner Serverfehler, etwas ist auf dem Server schiefgelaufen. +- `400 token_mismatched`: Bad request, möglicherweise aufgrund fehlender oder ungültiger Parameter. +- `400 api_not_implemented`: Bad request, möglicherweise aufgrund fehlender oder ungültiger Parameter. +- `401 invalid_token`: Nicht autorisiert, ungültiger oder fehlender Autorisierungs-Token. +- `429 too_many_requests`: Zu viele Anfragen, Sie haben das Ratenlimit überschritten. +- `500 api_error`: Interner Serverfehler, auf dem Server ist etwas schiefgelaufen. -### Fehlerantwortbeispiel +### Beispiel einer Fehlerantwort ```json { @@ -138,4 +138,4 @@ Wenn beim Aufruf der API ein Fehler auftritt, gibt die API den entsprechenden Fe ## Fazit -Durch dieses Dokument haben Sie gelernt, wie Sie die OpenAI Embeddings API einfach nutzen können, um die Funktion zur Generierung von Wortvektoren von OpenAI zu verwenden. Wir hoffen, dass dieses Dokument Ihnen hilft, die API besser zu integrieren und zu nutzen. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team. +Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Funktion zur Generierung von Wortvektoren des offiziellen OpenAI mithilfe der OpenAI Embeddings API einfach verwenden können. Wir hoffen, dass dieses Dokument Ihnen dabei hilft, diese API besser anzubinden und zu verwenden. Falls Sie Fragen haben, kontaktieren Sie jederzeit unser technisches Supportteam. diff --git a/de/guides/platform/wework_bot.mdx b/de/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..5c1aca479 --- /dev/null +++ b/de/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "WeCom-Roboter" +description: "Platform API guide - Ace Data Cloud" +--- + +Stellen Sie eine Instanz Ihres eigenen WeCom-Kontos bereit, melden Sie sich durch Scannen mit WeCom auf dem Mobiltelefon an und lesen Sie Konto, Kontakte, Unterhaltungen und lokal synchronisierte Nachrichten über REST API oder MCP. Die Instanz entspricht einem normalen WeCom-Konto und erfordert weder einen privaten Server noch eine Konfiguration einer Unternehmens-E-Mail-Domain. + +Derzeit Alpha. Das Auslesen des Kontos hat die Validierung echter Unterhaltungen abgeschlossen; das Senden eigener Texte und das Zurücklesen von Ereignissen haben die echte Abnahme abgeschlossen; andere Kontakte, Gruppenoperationen und die Wiederherstellung neuer Instanzen müssen noch einer Abnahme der Bereitstellungsumgebung unterzogen werden. Das Senden von Medien, Antworten mit Zitaten, echtes @, Gruppenmitgliederverwaltung und Zustellbestätigungen sind noch nicht verfügbar. Maßgeblich ist der Rückgabewert von `/api/capabilities` der Instanz. + +## Bereitstellung und Anmeldung + +Aktivieren Sie den Dienst in der Kategorie Deployment und wählen Sie ein Laufzeitpaket für die Instanz. Öffnen Sie nach der Bereitstellung die Verwaltungsseite und scannen Sie mit WeCom des Kontoinhabers; falls eine Bestätigung auf dem Mobiltelefon oder andere Anmeldeschritte erforderlich sind, öffnen Sie den Remote-Desktop und geben Sie das Desktop-Passwort dieser Instanz ein. API-Anmeldedaten und Desktop-Passwort sind unabhängig. Die Anmeldedaten werden auf dem Instanzdatenträger gespeichert; beim Neuerstellen des Containers bleibt der Datenträger erhalten; beim Löschen des Datenträgers wird die lokale Sitzung gelöscht. + +Jede Instanz wird separat abgerechnet und läuft entsprechend der bereits gekauften Laufzeit. REST-/MCP-Aufrufe werden nicht zusätzlich pro Nachricht berechnet, der tatsächliche Preis richtet sich nach der Paketseite. Derzeit wird standardmäßig auf die Laufzeitpakete des WeChat-Roboters verwiesen; vor der endgültigen Freigabe muss die Preisgestaltung zusammen mit den Betriebsressourcen bestätigt werden. + +## API und MCP + +Verwenden Sie die Instanz-API-Adresse auf der Verwaltungsseite; alle Kontoschnittstellen führen `Authorization: Bearer ` mit. Diese Pfade gehören zu einer dedizierten Instanz und sind kein gemeinsames API-Gateway. Die MCP-Adresse ist die Instanzadresse mit angehängtem `/mcp/` und verwendet dasselbe Bearer-Token. + +| Schnittstelle | Funktion | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`, `GET /api/auth/status` | Ob das Konto bereit ist und die Fähigkeitsliste | +| `GET /api/auth/qr` | PNG-Base64 des aktuellen Anmelde-QR-Codes | +| `GET /api/account` | Aktuelles Konto | +| `GET /api/contacts?kind=all` | Interne Kollegen und externe Kontakte, internal / external kann angegeben werden | +| `GET /api/conversations` | Lokale Unterhaltungen, ursprüngliche Unterhaltungs-ID bleibt erhalten | +| `GET /api/messages` | Lokal synchronisierte Nachrichten; Parameter conversation_id, after_rowid, limit | +| `POST /api/search` | Suche nach Kontakten, Unterhaltungen und lokalem Text | +| `POST /api/messages` | Asynchrone Aufgabe zum Senden von Text, Idempotency-Key muss angegeben werden | +| `POST /api/messages/send` | Derselbe Sendeendpunkt, unterstützt ein oder mehrere Ziele | +| `GET /api/groups/{conversation_id}` | Lokal synchronisierte Gruppeninformationen und Mitglieder | +| `GET /api/tasks` | Letzte Aufgaben und Ergebnisse je Ziel | +| `GET /api/tasks/{id}` | Sendeergebnis abfragen | +| `POST /api/tasks/{id}/cancel` | Noch nicht gestartete Aufgabe abbrechen | +| `POST /api/runtime/pause`, `POST /api/runtime/resume` | Automatisierung pausieren; nach eigener Verifizierung fortsetzen | +| `GET /api/diagnostics`, `GET /api/diagnostics/screenshot` | Instanzstatus und aktueller Bildschirm, beide erfordern Authentifizierung | +| `GET /api/events?after=0` | Nachrichtenereignisse mit fortsetzbarem Cursor | +| `WS /ws` | Nachrichtenereignis-Stream, Bearer-Authentifizierung | + +Der Sendetext enthält `target`, `type: "text"` und `text`. `target` akzeptiert Unterhaltungs-ID, Kontakt-ID, Unternehmensbenutzer-ID oder einen eindeutigen vollständigen Namen; IDs werden bevorzugt verwendet; falls der Anzeigename weiterhin keine eindeutige Zuordnung ermöglicht, lehnt die Instanz die Operation ab und errät kein Objekt. Kontakte ohne lokale Unterhaltung öffnen zunächst über den Client eine Unterhaltung und senden erst nach Abgleich der tatsächlichen Unterhaltungs-ID. Der Anforderungsheader `Idempotency-Key` besteht aus 8–128 Buchstaben, Ziffern oder `_.:-`. Wiederholte Anfragen für dieselbe Operation müssen denselben Schlüssel und denselben Anforderungstext wiederverwenden. + +Durch Ersetzen von `target` durch das Array `targets` kann seriell an 1–50 eindeutig angegebene Ziele gesendet werden. Beide können nicht gleichzeitig bereitgestellt werden. Alle Ziele schließen zunächst die Identitätsauflösung ab; unterschiedliche Aliase, die auf dasselbe Objekt zeigen, werden abgelehnt. Nach dem Fehlschlagen eines Ziels werden nachfolgende Sendungen gestoppt, und das Aufgabenergebnis zeichnet für jedes Element `succeeded`, `failed`, `unknown` oder `not_attempted` auf; behandeln Sie einen Teilerfolg nicht als vollständigen Erfolg. Dieser Ablauf muss in der Bereitstellungsumgebung noch mit angegebenen Kontakten echt abgenommen werden. + +Aufgaben können sich in queued, running, submitting, succeeded, failed, unknown oder cancelled befinden. `succeeded` bedeutet, dass nach dem Absenden in den entsprechenden Unterhaltungsaufzeichnungen der exakte Text und die Servernachrichten-ID gefunden wurden; `delivered` ist weiterhin null und bedeutet nicht, dass die andere Seite ihn erhalten hat. unknown bedeutet, dass das Ergebnis unklar ist; prüfen Sie den Verlauf und senden Sie nicht mit einem neuen Schlüssel erneut. Die Instanz sendet unterbrochene Aufgaben nicht automatisch erneut. + +Der Verlauf enthält nur Inhalte, die der Client bereits synchronisiert hat, und kann nicht den gesamten Verlauf garantieren. Nicht-Textnachrichten können als Typ unknown zurückgegeben werden, der Anhang-Download ist noch nicht verfügbar. Ereignisse bewahren die letzten 10.000 Einträge auf, `gap` bedeutet, dass der Cursor das Aufbewahrungsfenster überschritten hat. Die erste Verbindung spielt alten Verlauf nicht als neue Nachrichten erneut ab. + +`server_accepted` und `server_id` im Nachrichtenverlauf können verwendet werden, um zu überprüfen, ob der Server lokale Nachrichten akzeptiert hat; wenn nur ein lokaler Eintrag ohne Server-ID erscheint, kann der Versand nicht als erfolgreich angesehen werden. Diese Felder bedeuten nicht, dass der Empfänger die Nachricht erhalten oder gelesen hat. Ereignisaufzeichnungen bewahren den Status zum Zeitpunkt der Erzeugung auf; verwenden Sie zur Abfrage des aktuellen Bestätigungsstatus die Nachrichtenverlaufschnittstelle. + +## Konto und Anmeldedaten + +Melden Sie sich nur bei Konten an, zu deren Bedienung Sie berechtigt sind. Konfigurieren Sie das API-Token in vertrauenswürdigen Anwendungen; es kann auf die Kontodaten dieser Instanz zugreifen. Veröffentlichen Sie keine Passwörter, QR-Codes oder Chat-Screenshots an öffentlichen Orten. Das Pausieren der Instanz unterbricht Echtzeitereignisse. Nach einer Kontoabmeldung oder dem Entfernen des Geräts auf dem Mobiltelefon ist eine erneute Anmeldung erforderlich. + +Die aktuelle Texteingabe unterstützt nur eine Zeile; Zeilenumbrüche werden vor dem Senden ausdrücklich abgelehnt. Wenn der Client eine Sicherheitsverifizierung oder erneute Anmeldung verlangt, sollte der Kontoinhaber diese im Remote-Desktop abschließen; die Instanz umgeht keine Verifizierung. Aufgaben nach einer Unterbrechung der Verifizierung können unknown zurückgeben; fragen Sie zuerst die Nachrichtenaufzeichnungen ab und senden Sie nicht mit einem neuen Idempotenzschlüssel erneut. + +Wenn Sicherheitsverifizierungsaufforderungen, Kontoabmeldung oder Änderungen erkannt werden, wird die Automatisierungswarteschlange dauerhaft pausiert. Nach Abschluss der Mobiltelefonverifizierung können noch nicht ausgeführte Aufgaben über „Nach Verifizierung fortsetzen“ in der Instanzkonsole weitergeführt werden; bereits übermittelte Aufgaben mit unklarem Ergebnis werden nicht erneut gesendet. Auch normale Remote-Arbeit kann eine WeCom-Sicherheitsverifizierung auslösen. Das offiziell beschriebene 24-Stunden-Fenster nach der Verifizierung ohne erneute Sperrung bedeutet nicht, dass die Erkennung bereits aufgehoben wurde, und bedeutet auch nicht, dass die Instanz einen langfristig unbeaufsichtigten Betrieb garantieren kann. diff --git a/docs.json b/docs.json index a07269721..72b26598f 100644 --- a/docs.json +++ b/docs.json @@ -454,6 +454,7 @@ "zh-Hans/guides/platform/visual_studio_freeair", "zh-Hans/guides/platform/visual_studio_inferpal", "zh-Hans/guides/platform/visual_studio_lmlocal", + "zh-Hans/guides/platform/wework_bot", "zh-Hans/guides/platform/whatsapp_bot", "zh-Hans/guides/platform/x402", "zh-Hans/guides/platform/x402_e2e_troubleshooting", @@ -1189,6 +1190,7 @@ "en/guides/platform/visual_studio_freeair", "en/guides/platform/visual_studio_inferpal", "en/guides/platform/visual_studio_lmlocal", + "en/guides/platform/wework_bot", "en/guides/platform/whatsapp_bot", "en/guides/platform/x402", "en/guides/platform/x402_e2e_troubleshooting", @@ -1916,6 +1918,7 @@ "zh-Hant/guides/platform/visual_studio_freeair", "zh-Hant/guides/platform/visual_studio_inferpal", "zh-Hant/guides/platform/visual_studio_lmlocal", + "zh-Hant/guides/platform/wework_bot", "zh-Hant/guides/platform/whatsapp_bot", "zh-Hant/guides/platform/x402", "zh-Hant/guides/platform/x402_e2e_troubleshooting", @@ -2621,6 +2624,7 @@ "ja/guides/platform/visual_studio_freeair", "ja/guides/platform/visual_studio_inferpal", "ja/guides/platform/visual_studio_lmlocal", + "ja/guides/platform/wework_bot", "ja/guides/platform/whatsapp_bot", "ja/guides/platform/x402", "ja/guides/platform/x402_e2e_troubleshooting", @@ -3326,6 +3330,7 @@ "ko/guides/platform/visual_studio_freeair", "ko/guides/platform/visual_studio_inferpal", "ko/guides/platform/visual_studio_lmlocal", + "ko/guides/platform/wework_bot", "ko/guides/platform/whatsapp_bot", "ko/guides/platform/x402", "ko/guides/platform/x402_e2e_troubleshooting", @@ -4031,6 +4036,7 @@ "es/guides/platform/visual_studio_freeair", "es/guides/platform/visual_studio_inferpal", "es/guides/platform/visual_studio_lmlocal", + "es/guides/platform/wework_bot", "es/guides/platform/whatsapp_bot", "es/guides/platform/x402", "es/guides/platform/x402_e2e_troubleshooting", @@ -4736,6 +4742,7 @@ "fr/guides/platform/visual_studio_freeair", "fr/guides/platform/visual_studio_inferpal", "fr/guides/platform/visual_studio_lmlocal", + "fr/guides/platform/wework_bot", "fr/guides/platform/whatsapp_bot", "fr/guides/platform/x402", "fr/guides/platform/x402_e2e_troubleshooting", @@ -5441,6 +5448,7 @@ "de/guides/platform/visual_studio_freeair", "de/guides/platform/visual_studio_inferpal", "de/guides/platform/visual_studio_lmlocal", + "de/guides/platform/wework_bot", "de/guides/platform/whatsapp_bot", "de/guides/platform/x402", "de/guides/platform/x402_e2e_troubleshooting", @@ -6146,6 +6154,7 @@ "pt/guides/platform/visual_studio_freeair", "pt/guides/platform/visual_studio_inferpal", "pt/guides/platform/visual_studio_lmlocal", + "pt/guides/platform/wework_bot", "pt/guides/platform/whatsapp_bot", "pt/guides/platform/x402", "pt/guides/platform/x402_e2e_troubleshooting", @@ -6851,6 +6860,7 @@ "ru/guides/platform/visual_studio_freeair", "ru/guides/platform/visual_studio_inferpal", "ru/guides/platform/visual_studio_lmlocal", + "ru/guides/platform/wework_bot", "ru/guides/platform/whatsapp_bot", "ru/guides/platform/x402", "ru/guides/platform/x402_e2e_troubleshooting", @@ -7556,6 +7566,7 @@ "ar/guides/platform/visual_studio_freeair", "ar/guides/platform/visual_studio_inferpal", "ar/guides/platform/visual_studio_lmlocal", + "ar/guides/platform/wework_bot", "ar/guides/platform/whatsapp_bot", "ar/guides/platform/x402", "ar/guides/platform/x402_e2e_troubleshooting", @@ -8261,6 +8272,7 @@ "it/guides/platform/visual_studio_freeair", "it/guides/platform/visual_studio_inferpal", "it/guides/platform/visual_studio_lmlocal", + "it/guides/platform/wework_bot", "it/guides/platform/whatsapp_bot", "it/guides/platform/x402", "it/guides/platform/x402_e2e_troubleshooting", @@ -8966,6 +8978,7 @@ "sv/guides/platform/visual_studio_freeair", "sv/guides/platform/visual_studio_inferpal", "sv/guides/platform/visual_studio_lmlocal", + "sv/guides/platform/wework_bot", "sv/guides/platform/whatsapp_bot", "sv/guides/platform/x402", "sv/guides/platform/x402_e2e_troubleshooting", @@ -9671,6 +9684,7 @@ "uk/guides/platform/visual_studio_freeair", "uk/guides/platform/visual_studio_inferpal", "uk/guides/platform/visual_studio_lmlocal", + "uk/guides/platform/wework_bot", "uk/guides/platform/whatsapp_bot", "uk/guides/platform/x402", "uk/guides/platform/x402_e2e_troubleshooting", @@ -10376,6 +10390,7 @@ "pl/guides/platform/visual_studio_freeair", "pl/guides/platform/visual_studio_inferpal", "pl/guides/platform/visual_studio_lmlocal", + "pl/guides/platform/wework_bot", "pl/guides/platform/whatsapp_bot", "pl/guides/platform/x402", "pl/guides/platform/x402_e2e_troubleshooting", diff --git a/el/guides/claude/claude_messages.mdx b/el/guides/claude/claude_messages.mdx index 1e73363ab..5fdc28fab 100644 --- a/el/guides/claude/claude_messages.mdx +++ b/el/guides/claude/claude_messages.mdx @@ -3,41 +3,42 @@ title: "Αίτηση και χρήση του Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Το Anthropic Claude είναι ένα πολύ ισχυρό σύστημα συνομιλίας AI· αρκεί να εισαγάγετε ένα prompt και μπορεί να δημιουργήσει ομαλές και φυσικές απαντήσεις μέσα σε λίγα δευτερόλεπτα. Το Claude Messages API είναι η εγγενής μορφή API που παρέχεται επίσημα από την Anthropic. Σε αντίθεση με τη μορφή συμβατή με OpenAI (Chat Completion), χρησιμοποιεί τη δική του δομή αιτημάτων και αποκρίσεων της Anthropic, επιτρέποντας την καλύτερη αξιοποίηση των μοναδικών δυνατοτήτων του Claude, όπως η πολυτροπική εισαγωγή περιεχομένου, η κλήση εργαλείων, η εκτεταμένη σκέψη (Extended Thinking) και άλλες προηγμένες δυνατότητες. +Το Anthropic Claude είναι ένα πολύ ισχυρό σύστημα συνομιλίας AI, το οποίο μπορεί να δημιουργήσει ομαλές και φυσικές απαντήσεις μέσα σε λίγα δευτερόλεπτα, αρκεί να εισαχθεί ένα prompt. Το Claude Messages API είναι η επίσημη εγγενής μορφή API της Anthropic. Σε αντίθεση με τη μορφή συμβατή με OpenAI (Chat Completion), χρησιμοποιεί τη δική του δομή αιτημάτων και αποκρίσεων της Anthropic, επιτρέποντας την καλύτερη αξιοποίηση των μοναδικών δυνατοτήτων του Claude, όπως η πολυτροπική εισαγωγή περιεχομένου, η κλήση εργαλείων, η βαθιά σκέψη (Extended Thinking) και άλλα προηγμένα χαρακτηριστικά. -Το παρόν έγγραφο παρουσιάζει κυρίως τη διαδικασία χρήσης των λειτουργιών του Claude Messages API. Μέσω αυτού, μπορούμε να χρησιμοποιήσουμε το εγγενές interface που είναι ίδιο με το επίσημο της Anthropic για να καλέσουμε τη λειτουργία συνομιλίας του Claude. +Αυτό το έγγραφο παρουσιάζει κυρίως τη διαδικασία χρήσης των λειτουργιών του Claude Messages API. Με αυτό μπορούμε να χρησιμοποιήσουμε εγγενείς διεπαφές συνεπείς με τις επίσημες της Anthropic για να καλέσουμε τις λειτουργίες συνομιλίας του Claude. ## Διαδικασία αίτησης -Για να χρησιμοποιήσετε το Claude Messages API, αποκτήστε αρχικά το API Token σας από την [κονσόλα Ace Data Cloud](https://platform.acedata.cloud/console/applications) και κρατήστε το για μελλοντική χρήση. +Για να χρησιμοποιήσετε το Claude Messages API, μεταβείτε πρώτα στην [κονσόλα Ace Data Cloud](https://platform.acedata.cloud/console/applications) για να αποκτήσετε το API Token σας και κρατήστε το για μελλοντική χρήση. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Αν δεν έχετε ακόμη συνδεθεί ή εγγραφεί, θα μεταφερθείτε αυτόματα στη σελίδα σύνδεσης για να εγγραφείτε και να συνδεθείτε. Μετά την ολοκλήρωση, θα επιστρέψετε αυτόματα στην τρέχουσα σελίδα. +Αν δεν έχετε συνδεθεί ή εγγραφεί ακόμη, θα ανακατευθυνθείτε αυτόματα στη σελίδα σύνδεσης, όπου θα σας προσκληθεί να εγγραφείτε και να συνδεθείτε. Μετά την ολοκλήρωση, θα επιστρέψετε αυτόματα στην τρέχουσα σελίδα. -**Ένα API Token αρκεί για την κλήση όλων των υπηρεσιών της πλατφόρμας· δεν χρειάζεται ξεχωριστή αίτηση για κάθε υπηρεσία.** Η πρώτη αίτηση προσφέρει δωρεάν πίστωση για δωρεάν δοκιμή· όταν η πίστωση δεν επαρκεί, μπορείτε να επαναφορτίσετε το γενικό υπόλοιπο από την [κονσόλα](https://platform.acedata.cloud/console/coin). +**Ένα API Token αρκεί για την κλήση όλων των υπηρεσιών της πλατφόρμας, χωρίς να χρειάζεται ξεχωριστή αίτηση για κάθε υπηρεσία.** Η πρώτη αίτηση προσφέρει δωρεάν πίστωση για δωρεάν δοκιμή· όταν η πίστωση δεν επαρκεί, μπορείτε να φορτίσετε γενικό υπόλοιπο στην [κονσόλα](https://platform.acedata.cloud/console/coin). > 📘 Πλήρης τεκμηρίωση: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Βασική χρήση -Η διαδρομή αιτήματος του Claude Messages API είναι `/v1/messages`, σε συμφωνία με το επίσημο API της Anthropic. Πρέπει να παρέχουμε τουλάχιστον τρεις υποχρεωτικές παραμέτρους: +Η διαδρομή αιτήματος του Claude Messages API είναι `/v1/messages`, συνεπής με το επίσημο API της Anthropic. Πρέπει να παρέχουμε τουλάχιστον τρεις υποχρεωτικές παραμέτρους: -- `model`: Επιλέξτε το μοντέλο Claude που θα χρησιμοποιηθεί. Το `claude-opus-5-5` παρέχεται μόνο μέσω του Messages API, υποστηρίζει πλαίσιο 1 εκατομμυρίου Token, μέγιστη έξοδο 128K Token και ενεργοποιεί πάντα την προσαρμοστική σκέψη. Το νεότερο κορυφαίο μοντέλο είναι το `claude-fable-5-1` (πλαίσιο 1 εκατομμυρίου Token, μέγιστη έξοδος 128K Token)· το προηγούμενο `claude-fable-5` εξακολουθεί να διατηρείται για συμβατότητα. Το `claude-sonnet-5-5` έχει προστεθεί στη σειρά εγγενών interfaces Messages, υποστηρίζοντας εισαγωγή εικόνας και προσαρμοστική σκέψη· οι επίσημες τιμές αναφοράς για είσοδο, έξοδο και ανάγνωση cache είναι αντίστοιχα 2, 10 και 0,20 δολάρια ανά εκατομμύριο Token. -- `messages`: Ο πίνακας των εισαγόμενων μηνυμάτων, όπου κάθε μήνυμα περιλαμβάνει `role` (ρόλος) και `content` (περιεχόμενο), ενώ το `role` υποστηρίζει `user` και `assistant`. +- `model`: Επιλέγει το μοντέλο Claude που θα χρησιμοποιηθεί. Το `claude-opus-5-5` παρέχεται μόνο μέσω του Messages API, υποστηρίζει περιβάλλον 1 εκατομμυρίου Token, μέγιστη έξοδο 128K Token και ενεργοποιεί πάντα την προσαρμοστική σκέψη. Το νεότερο κορυφαίο μοντέλο είναι το `claude-fable-5-1` (περιβάλλον 1 εκατομμυρίου Token, μέγιστη έξοδος 128K Token)· το προηγούμενο `claude-fable-5` παραμένει συμβατό. Το `claude-sonnet-5-5` έχει προστεθεί στη σειρά εγγενών διεπαφών Messages, υποστηρίζει εισαγωγή εικόνων και προσαρμοστική σκέψη· οι επίσημες τιμές αναφοράς για είσοδο, έξοδο και ανάγνωση cache είναι αντίστοιχα 2, 10 και 0,20 δολάρια ανά εκατομμύριο Token. +- `messages`: Ο πίνακας εισαγόμενων μηνυμάτων. Κάθε μήνυμα περιλαμβάνει `role` (ρόλος) και `content` (περιεχόμενο), όπου το `role` υποστηρίζει `user` και `assistant`. - `max_tokens`: Ο μέγιστος αριθμός token εξόδου, που χρησιμοποιείται για τον περιορισμό του μήκους μιας μεμονωμένης απάντησης. Συνήθεις προαιρετικές παράμετροι: -- `system`: Prompt συστήματος, που χρησιμοποιείται για τον καθορισμό της συμπεριφοράς και του ρόλου του μοντέλου. -- `temperature`: Τυχαιότητα δημιουργίας, μεταξύ 0-1· όσο μεγαλύτερη είναι η τιμή, τόσο πιο αποκλίνουσες είναι οι απαντήσεις. -- `stream`: Αν θα χρησιμοποιηθεί απόκριση ροής· ορίζοντας `true` μπορεί να επιτευχθεί εφέ επιστροφής χαρακτήρα προς χαρακτήρα. -- `stop_sequences`: Προσαρμοσμένες ακολουθίες διακοπής· το μοντέλο σταματά τη δημιουργία όταν συναντήσει αυτά τα κείμενα. -- `top_p`: Παράμετρος δειγματοληψίας πυρήνα, που ελέγχει την τυχαιότητα της δημιουργίας σε συνδυασμό με το temperature. +- `system`: Το system prompt, που χρησιμοποιείται για τον καθορισμό της συμπεριφοράς και του ρόλου του μοντέλου. +- `temperature`: Η τυχαιότητα παραγωγής, μεταξύ 0 και 1· όσο μεγαλύτερη είναι η τιμή, τόσο πιο αποκλίνουσες είναι οι απαντήσεις. +- `stream`: Αν θα χρησιμοποιηθεί ροϊκή απόκριση· ορίζοντας `true` μπορεί να επιτευχθεί εφέ επιστροφής χαρακτήρα προς χαρακτήρα. +- `stop_sequences`: Προσαρμοσμένες ακολουθίες διακοπής· το μοντέλο σταματά την παραγωγή όταν συναντά αυτά τα κείμενα. +- `top_p`: Παράμετρος δειγματοληψίας πυρήνα, που ελέγχει την τυχαιότητα της παραγωγής σε συνδυασμό με το temperature. - `top_k`: Δειγματοληψία μόνο από τις K επιλογές με την υψηλότερη πιθανότητα. -- `tools`: Ορισμοί εργαλείων, που χρησιμοποιούνται ώστε το μοντέλο να καλεί εξωτερικές συναρτήσεις. -- `tool_choice`: Ελέγχει τον τρόπο με τον οποίο το μοντέλο χρησιμοποιεί τα παρεχόμενα εργαλεία. -- `cache_control`: Δημιουργεί αυτόματα σημείο διακοπής cache στο τελευταίο αποθηκεύσιμο μπλοκ περιεχομένου του αιτήματος· μπορεί επίσης να γραφτεί σε συγκεκριμένο μπλοκ περιεχομένου. +- `tools`: Ορισμοί εργαλείων, που χρησιμοποιούνται για να επιτρέπουν στο μοντέλο να καλεί εξωτερικές συναρτήσεις. +- `tool_choice`: Ελέγχει πώς το μοντέλο χρησιμοποιεί τα παρεχόμενα εργαλεία. +- `cache_control`: Δημιουργεί αυτόματα σημείο διακοπής cache στο τελευταίο μπλοκ περιεχομένου που μπορεί να αποθηκευτεί προσωρινά στο αίτημα· μπορεί επίσης να γραφτεί σε συγκεκριμένο μπλοκ περιεχομένου. +- `metadata`: Προαιρετικό αντικείμενο μεταδεδομένων αιτήματος. Το `metadata.user_id` είναι συμβολοσειρά και μπορεί να μεταφέρει προσαρμοσμένο αναγνωριστικό χρήστη του καλούντος, για παράδειγμα `{"user_id":"example-user-001"}`· συνιστάται η χρήση σταθερού αναγνωριστικού που δεν περιέχει προσωπικές πληροφορίες. Δεν αντικαθιστά την ταυτοποίηση `Authorization`, ούτε χρειάζεται να γραφτεί στο περιεχόμενο συνομιλίας `messages`. ### Παράδειγμα cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Μετά την κλήση, το αποτέλεσμα επιστροφής είναι το ακόλουθο: +Μετά την κλήση, το αποτέλεσμα επιστροφής είναι το εξής: ```json { @@ -106,25 +109,25 @@ print(response.json()) } ``` -Επεξήγηση πεδίων αποτελέσματος επιστροφής: +Επεξήγηση των πεδίων του αποτελέσματος επιστροφής: +- `id`：Το μοναδικό αναγνωριστικό του τρέχοντος μηνύματος. +- `type`：Πάντα `message`. +- `role`：Πάντα `assistant`. +- `content`：Πίνακας περιεχομένου απάντησης, όπου κάθε στοιχείο περιλαμβάνει `type` (όπως `text`) και το αντίστοιχο περιεχόμενο. +- `model`：Το όνομα του μοντέλου που επεξεργάζεται το αίτημα. +- `stop_reason`：Ο λόγος διακοπής. Οι σταθερές τιμές περιλαμβάνουν `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (μπορείτε να επιστρέψετε αυτούσιο το τρέχον περιεχόμενο του assistant για να συνεχίσετε), `refusal` και `model_context_window_exceeded`. +- `stop_sequence`：Αν η διακοπή οφείλεται σε προσαρμοσμένη ακολουθία διακοπής, εμφανίζει το κείμενο της ακολουθίας διακοπής που αντιστοιχίστηκε. +- `stop_details`：Όταν το `stop_reason` είναι `refusal`, μπορεί να περιλαμβάνει την κατηγορία και την περιγραφή της άρνησης. +- `usage`：Στατιστικά χρήσης token. Το `input_tokens` είναι η μη αποθηκευμένη στην προσωρινή μνήμη είσοδος· τα `cache_creation_input_tokens` και `cache_read_input_tokens` είναι αντίστοιχα η εγγραφή και η ανάγνωση της προσωρινής μνήμης· το `output_tokens` είναι ο συνολικός αριθμός token εξόδου. Αν επιστρέφεται το `output_tokens_details.thinking_tokens`, αυτή η τιμή είναι υποσύνολο του `output_tokens` και δεν πρέπει να προστεθεί ξανά κατά τον υπολογισμό του συνόλου ή του κόστους. Όταν αυτή η ανάλυση δεν έχει επίσημη καταμέτρηση, μπορεί να είναι `null` ή να παραλείπεται. +- `usage.cache_creation`：Προαιρετικές λεπτομέρειες TTL εγγραφής προσωρινής μνήμης, που περιλαμβάνουν `ephemeral_5m_input_tokens` και `ephemeral_1h_input_tokens`. Όταν το αντικείμενο υπάρχει, το άθροισμα των δύο ισούται με `cache_creation_input_tokens`· όταν τα πεδία είναι `null` ή παραλείπονται, σημαίνει ότι η τρέχουσα απόκριση δεν διαθέτει χρησιμοποιήσιμη ανάλυση TTL και δεν πρέπει να ερμηνεύεται ως `0`. +- `usage.cost`：Οι μη ροϊκές αποκρίσεις μπορεί να περιλαμβάνουν ένα αντικείμενο κατανάλωσης πιστώσεων που καταγράφεται από το Ace Data Cloud, όπου το `amount` είναι η πραγματική κατανάλωση αυτής της φοράς, το `currency` είναι η μονάδα μέτρησης και το `list_amount` είναι το ποσό πριν από την έκπτωση (εάν υπάρχει). Η επίσημη βασική τιμή για ανάγνωση προσωρινής μνήμης του Fable 5.1 είναι $0.25/εκατομμύριο Token, ενώ οι βασικές τιμές εγγραφής προσωρινής μνήμης για 5 λεπτά και 1 ώρα είναι αντίστοιχα $12.50 και $20/εκατομμύριο Token· η πραγματική τιμή της πλατφόρμας μετατρέπεται σύμφωνα με την έκπτωση του προγράμματος. -- `id`: Το μοναδικό αναγνωριστικό του τρέχοντος μηνύματος. -- `type`: Πάντα `message`. -- `role`: Πάντα `assistant`. -- `content`: Πίνακας περιεχομένου απάντησης· κάθε στοιχείο περιλαμβάνει `type` (όπως `text`) και το αντίστοιχο περιεχόμενο. -- `model`: Το όνομα του μοντέλου που επεξεργάζεται το αίτημα. -- `stop_reason`: Αιτία διακοπής. Οι σταθερές τιμές περιλαμβάνουν `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (μπορείτε να επιστρέψετε αυτούσιο το τρέχον περιεχόμενο του assistant για να συνεχίσετε), `refusal` και `model_context_window_exceeded`. -- `stop_sequence`: Αν σταμάτησε λόγω προσαρμοσμένης ακολουθίας διακοπής, εμφανίζει το κείμενο της ακολουθίας διακοπής που αντιστοιχίστηκε. -- `stop_details`: Όταν το `stop_reason` είναι `refusal`, μπορεί να περιλαμβάνει κατηγορία άρνησης και επεξήγηση. -- `usage`: Στατιστικά χρήσης token. Το `input_tokens` είναι η μη αποθηκευμένη είσοδος cache· τα `cache_creation_input_tokens` και `cache_read_input_tokens` είναι αντίστοιχα εγγραφή και ανάγνωση cache· το `output_tokens` είναι ο συνολικός αριθμός token εξόδου. Εάν επιστρέφεται το `output_tokens_details.thinking_tokens`, αυτή η τιμή είναι υποσύνολο του `output_tokens` και δεν πρέπει να προστεθεί ξανά κατά τον υπολογισμό του συνόλου ή της χρέωσης. Αυτή η ανάλυση μπορεί να είναι `null` ή να παραλείπεται όταν δεν υπάρχει έγκυρη καταμέτρηση. -- `usage.cache_creation`: Προαιρετική ανάλυση TTL εγγραφής cache, που περιλαμβάνει `ephemeral_5m_input_tokens` και `ephemeral_1h_input_tokens`. Όταν το αντικείμενο υπάρχει, το άθροισμα των δύο ισούται με `cache_creation_input_tokens`· όταν το πεδίο είναι `null` ή παραλείπεται, σημαίνει ότι η τρέχουσα απόκριση δεν διαθέτει ανάλυση TTL και δεν πρέπει να ερμηνεύεται ως `0`. -- `usage.cost`: Οι μη ροϊκές αποκρίσεις μπορεί να περιλαμβάνουν το αντικείμενο κατανάλωσης πίστωσης που καταγράφεται από το Ace Data Cloud, όπου το `amount` είναι η πραγματική κατανάλωση αυτής της φοράς, το `currency` είναι η μονάδα μέτρησης και το `list_amount` είναι το ποσό πριν από την έκπτωση (εάν υπάρχει). Η επίσημη βασική τιμή ανάγνωσης cache του Fable 5.1 είναι $0.25/εκατομμύριο Token, ενώ οι βασικές τιμές εγγραφής cache για 5 λεπτά και 1 ώρα είναι αντίστοιχα $12.50 και $20/εκατομμύριο Token· η πραγματική τιμή της πλατφόρμας υπολογίζεται με βάση την έκπτωση του πακέτου. +## Προτροπή συστήματος -## Prompt συστήματος - -Το Claude Messages API υποστηρίζει τον καθορισμό prompt συστήματος μέσω του πεδίου `system`, για τον ορισμό της συμπεριφοράς, του ρόλου και του πλαισίου του μοντέλου. +Το Claude Messages API υποστηρίζει τον ορισμό προτροπών συστήματος μέσω του πεδίου `system`, για τον καθορισμό της συμπεριφοράς, του ρόλου και του πλαισίου του μοντέλου. ### Παράδειγμα Python + ```python import requests @@ -149,11 +152,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Με τον ορισμό της προτροπής `system`, μπορείτε να ελέγχετε με ακρίβεια τον ρόλο και τον τρόπο συμπεριφοράς του Claude. +Με τη ρύθμιση της προτροπής `system`, μπορείτε να ελέγξετε με ακρίβεια τον ρόλο και τον τρόπο συμπεριφοράς του Claude. ## Ροϊκές αποκρίσεις -Αυτή η διεπαφή υποστηρίζει επίσης ροϊκές αποκρίσεις. Ορίστε την παράμετρο `stream` σε `true` για να λαμβάνετε σταδιακά επιστρεφόμενα αποτελέσματα, κάτι που είναι ιδιαίτερα κατάλληλο για την υλοποίηση εμφάνισης χαρακτήρα προς χαρακτήρα σε ιστοσελίδες. +Η διεπαφή υποστηρίζει επίσης ροϊκές αποκρίσεις· ορίστε την παράμετρο `stream` σε `true` για να λάβετε σταδιακή επιστροφή, κάτι που είναι ιδιαίτερα κατάλληλο για την υλοποίηση εμφάνισης χαρακτήρα προς χαρακτήρα σε ιστοσελίδες. ### Παράδειγμα Python @@ -183,16 +186,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Οι ροϊκές αποκρίσεις επιστρέφονται σε μορφή Server-Sent Events (SSE), με κάθε γραμμή να έχει ως πρόθεμα `event:` και `data:`. Οι τύποι ροϊκών συμβάντων περιλαμβάνουν: +Οι ροϊκές αποκρίσεις επιστρέφονται σε μορφή Server-Sent Events (SSE), με κάθε γραμμή να έχει το πρόθεμα `event:` και `data:`. Οι τύποι ροϊκών συμβάντων περιλαμβάνουν: -- `message_start`: Έναρξη μηνύματος, περιλαμβάνει τις βασικές πληροφορίες του μηνύματος και το όνομα του μοντέλου. -- `content_block_start`: Έναρξη μπλοκ περιεχομένου. -- `content_block_delta`: Αυξητική ενημέρωση μπλοκ περιεχομένου, περιλαμβάνει το νέο παραγόμενο τμήμα κειμένου. -- `content_block_stop`: Λήξη μπλοκ περιεχομένου. -- `message_delta`: Αυξητική ενημέρωση σε επίπεδο μηνύματος, περιλαμβάνει τις πληροφορίες `stop_reason` και τις τελικές πληροφορίες `usage`. Η έγκυρη τιμή του `output_tokens_details.thinking_tokens` θα πρέπει να διαβάζεται μόνο από το τελευταίο `message_delta.usage` και να μην αθροίζεται μεταξύ συμβάντων. -- `message_stop`: Λήξη μηνύματος. +- `message_start`：Έναρξη μηνύματος, περιλαμβάνει τις βασικές πληροφορίες του μηνύματος και το όνομα του μοντέλου. +- `content_block_start`：Έναρξη μπλοκ περιεχομένου. +- `content_block_delta`：Σταδιακή ενημέρωση μπλοκ περιεχομένου, περιλαμβάνει το νέο παραγόμενο τμήμα κειμένου. +- `content_block_stop`：Λήξη μπλοκ περιεχομένου. +- `message_delta`：Σταδιακή ενημέρωση επιπέδου μηνύματος, περιλαμβάνει `stop_reason` και τις τελικές πληροφορίες `usage`. Η έγκυρη τιμή του `output_tokens_details.thinking_tokens` θα πρέπει να διαβάζεται μόνο από το τελευταίο `message_delta.usage` και να μην αθροίζεται μεταξύ συμβάντων. +- `message_stop`：Λήξη μηνύματος. -Το αποτέλεσμα εξόδου είναι ως εξής: +Το αποτέλεσμα εξόδου είναι το εξής: ``` event: message_start @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Όπως φαίνεται, το συμβάν `content_block_delta` στη ροϊκή απόκριση περιλαμβάνει το σταδιακά παραγόμενο περιεχόμενο κειμένου και μπορείτε να λάβετε την πλήρη απάντηση ενώνοντας όλα τα `text_delta`. +Όπως φαίνεται, στο ροϊκό αποτέλεσμα, το συμβάν `content_block_delta` περιλαμβάνει το σταδιακά παραγόμενο κείμενο· με τη συνένωση όλων των `text_delta` μπορείτε να λάβετε την πλήρη απάντηση. ### Παράδειγμα JavaScript @@ -251,9 +254,9 @@ while (true) { } ``` -## Συνομιλίες πολλαπλών γύρων +## Πολυγυρικός διάλογος -Εάν θέλετε να ενσωματώσετε τη λειτουργία συνομιλιών πολλαπλών γύρων, πρέπει να τοποθετήσετε εναλλάξ μηνύματα με ρόλους `user` και `assistant` στον πίνακα `messages` και να μεταβιβάσετε μαζί το προηγούμενο ιστορικό συνομιλίας. +Αν θέλετε να ενσωματώσετε λειτουργία πολυγυρικού διαλόγου, πρέπει να τοποθετήσετε εναλλάξ μηνύματα με ρόλους `user` και `assistant` στον πίνακα `messages`, μεταβιβάζοντας μαζί και το προηγούμενο ιστορικό διαλόγου. ### Παράδειγμα Python @@ -282,8 +285,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Το αποτέλεσμα επιστροφής είναι ως εξής: - +Το αποτέλεσμα επιστροφής είναι το εξής: ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ print(response.json()) } ``` -Με τη μεταβίβαση του πλήρους ιστορικού συνομιλίας στο `messages`, το Claude μπορεί να απαντά με ακρίβεια λαμβάνοντας υπόψη το περιεχόμενο. +Περνώντας το πλήρες ιστορικό συνομιλίας στα `messages`, το Claude μπορεί να παρέχει ακριβείς απαντήσεις με βάση το πλαίσιο. -## Μοντέλο βαθιάς σκέψης +## Μοντέλα βαθιάς σκέψης Το thinking και το thinking summary του Claude είναι δύο διαφορετικές έννοιες: το μοντέλο μπορεί να εκτελεί εσωτερική συλλογιστική, αλλά το API δεν επιστρέφει την αρχική αλυσίδα σκέψης. Όταν χρειάζεται να εμφανιστεί η διαδικασία συλλογισμού, το API επιστρέφει μια επεξεργασμένη σύνοψη. -Για το τρέχον μοντέλο συνιστάται η χρήση adaptive thinking και ο έλεγχος της συνολικής επένδυσης συλλογισμού μέσω του `output_config.effort`: +Για τα τρέχοντα μοντέλα συνιστάται η χρήση adaptive thinking και ο έλεγχος της συνολικής επένδυσης συλλογισμού μέσω του `output_config.effort`: ```python import requests @@ -350,24 +352,25 @@ print(response.json()) "signature": "opaque-signature" } ``` -- `display: "summarized"` επιστρέφει μια αναγνώσιμη σύνοψη σκέψης· δεν είναι η ακατέργαστη αλυσίδα σκέψης. -- `display: "omitted"` επιστρέφει `thinking: ""`, αλλά εξακολουθεί να διατηρεί το opaque `signature` για την υποστήριξη επόμενων συνομιλιών. -- `display: "updates"` είναι η beta λειτουργία της Anthropic και απαιτεί το `anthropic-beta: thinking-display-updates-2026-08-18`. Ο επίσημος ορισμός είναι να αποκρύπτει το κύριο σώμα της συλλογιστικής και να εμφανίζει σύντομες ενημερώσεις προόδου μεταξύ των κλήσεων εργαλείων. Η πλατφόρμα προωθεί αυτήν την παράμετρο και την κεφαλίδα beta ως έχουν, και δεν την ξαναγράφει υποχρεωτικά σε `summarized`· το πραγματικό περιεχόμενο εξόδου εξαρτάται από την υποστήριξη του επιλεγμένου μοντέλου. -- Τα `thinking`, `output_config`, effort, οι παράμετροι δειγματοληψίας και τα νέα επεκτατικά πεδία προωθούνται ως έχουν. Η πλατφόρμα δεν διατηρεί σκληρά κωδικοποιημένες ανά μοντέλο απαριθμήσεις τιμών ή περιορισμούς συνδυασμών, ούτε ξαναγράφει αυτόματα τις λειτουργίες thinking· το αν γίνονται δεκτές αυτές οι παράμετροι κρίνεται από το επιλεγμένο μοντέλο και τα σφάλματα παραμέτρων που επιστρέφει το μοντέλο μεταφέρονται πίσω στον πελάτη. -- Οι προεπιλεγμένες τιμές display για τα Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 και Opus 4.7 είναι `omitted`· τα Opus 4.6, Sonnet 4.6 και παλαιότερα μοντέλα που υποστηρίζουν thinking χρησιμοποιούν από προεπιλογή το `summarized`. + +- Το `display: "summarized"` επιστρέφει μια αναγνώσιμη σύνοψη σκέψης· δεν είναι η αρχική αλυσίδα σκέψης. +- Το `display: "omitted"` επιστρέφει `thinking: ""`, αλλά διατηρεί το opaque `signature` για την υποστήριξη επακόλουθων συνομιλιών. +- Το `display: "updates"` είναι η beta λειτουργία της Anthropic και απαιτεί το `anthropic-beta: thinking-display-updates-2026-08-18`. Ο επίσημος ορισμός είναι ότι αποκρύπτει το κυρίως σώμα της συλλογιστικής και εμφανίζει σύντομες ενημερώσεις προόδου μεταξύ κλήσεων εργαλείων. Η πλατφόρμα μεταβιβάζει αυτήν την παράμετρο και την κεφαλίδα beta όπως είναι και δεν την ξαναγράφει αναγκαστικά σε `summarized`· το πραγματικό περιεχόμενο εξόδου εξαρτάται από την υποστήριξη του επιλεγμένου μοντέλου. +- Τα `thinking`, `output_config`, effort, οι παράμετροι δειγματοληψίας και τα νέα επεκτατικά πεδία μεταβιβάζονται όπως είναι. Η πλατφόρμα δεν διατηρεί απαρίθμηση τιμών ή περιορισμούς συνδυασμών κωδικοποιημένους ανά μοντέλο, ούτε ξαναγράφει αυτόματα τη λειτουργία thinking· το αν γίνονται αποδεκτές αυτές οι παράμετροι κρίνεται από το επιλεγμένο μοντέλο και τα σφάλματα παραμέτρων που επιστρέφει το μοντέλο μεταβιβάζονται στον πελάτη. +- Οι προεπιλεγμένες τιμές display για τα Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 και Opus 4.7 είναι `omitted`· τα Opus 4.6, Sonnet 4.6 και παλαιότερα μοντέλα που υποστηρίζουν thinking χρησιμοποιούν από προεπιλογή `summarized`. - Το Display επηρεάζει μόνο το περιεχόμενο επιστροφής και την καθυστέρηση ροής, δεν απενεργοποιεί τη συλλογιστική και δεν μειώνει τη χρέωση των thinking token. -- Το αν το thinking είναι ενεργοποιημένο από προεπιλογή και η προεπιλεγμένη τιμή του display είναι δύο ανεξάρτητα ζητήματα. Τα Opus 5 και Sonnet 5 ενεργοποιούν από προεπιλογή το adaptive thinking· για το Opus 5, η παράλειψη του `thinking` ισοδυναμεί με adaptive και η παράλειψη του `output_config.effort` ισοδυναμεί με `high`. Τα Opus 4.8, 4.7 και 4.6 απαιτούν ρητή ενεργοποίηση. -- Το Thinking και το τελικό κυρίως κείμενο μοιράζονται τον προϋπολογισμό εξόδου `max_tokens`. Όταν ο προϋπολογισμός είναι πολύ μικρός, το thinking μπορεί να καταλάβει το μεγαλύτερο μέρος του ορίου, αφήνοντας το κυρίως κείμενο κενό ή περικομμένο· αυξήστε το `max_tokens` ή χρησιμοποιήστε effort `low` / `medium` για να ελέγξετε την επένδυση στη συλλογιστική. -- Για μοντέλα που επιτρέπουν την απενεργοποίηση του thinking, μπορείτε να περάσετε `thinking: {"type":"disabled"}`. Οι νέες λειτουργίες όπως `between_tools` και οι συνδυασμοί effort εξαρτώνται από το επιλεγμένο μοντέλο· η πλατφόρμα δεν απορρίπτει εκ των προτέρων βάσει παλαιών κανόνων μοντέλων. -- Ο σταθερός προϋπολογισμός σκέψης μπορεί να περαστεί μέσω του `budget_tokens`· τα νέα μοντέλα χρησιμοποιούν συνήθως `thinking.type=adaptive` και `output_config.effort`. Το αν υποστηρίζεται σταθερός προϋπολογισμός ή η απενεργοποίηση της σκέψης καθορίζεται από τις τρέχουσες δυνατότητες του επιλεγμένου μοντέλου. -- Σε συνομιλίες πολλών γύρων και κλήσεις εργαλείων, θα πρέπει να επιστρέφετε αυτούσια τα πλήρη thinking blocks και τα signature που επιστρέφει ο assistant· μην τροποποιείτε ή δημιουργείτε μόνοι σας signature. -- Η προώθηση παραμέτρων δεν σημαίνει ότι κάθε μοντέλο υποστηρίζει όλες τις λειτουργίες. Οι διαπρωτοκολλιακές κλήσεις εξακολουθούν να απαιτούν μετατροπή, και το εύρος υποστήριξης και τα σφάλματα για περιεχόμενο όπως το `redacted_thinking` καθορίζονται από την υπηρεσία μοντέλου που επεξεργάζεται πραγματικά το αίτημα. +- Το αν το thinking ενεργοποιείται από προεπιλογή και η προεπιλεγμένη τιμή display είναι δύο ανεξάρτητα ζητήματα. Τα Opus 5 και Sonnet 5 ενεργοποιούν από προεπιλογή το adaptive thinking· για το Opus 5, η παράλειψη του `thinking` ισοδυναμεί με adaptive και η παράλειψη του `output_config.effort` ισοδυναμεί με `high`. Τα Opus 4.8, 4.7 και 4.6 απαιτούν ρητή ενεργοποίηση. +- Το Thinking και το τελικό κυρίως κείμενο καταναλώνουν μαζί τον προϋπολογισμό εξόδου `max_tokens`. Όταν ο προϋπολογισμός είναι πολύ μικρός, το thinking μπορεί να καταναλώσει το μεγαλύτερο μέρος του ορίου, αφήνοντας το κυρίως κείμενο κενό ή περικομμένο· αυξήστε το `max_tokens` ή χρησιμοποιήστε effort `low` / `medium` για να ελέγξετε την επένδυση συλλογισμού. +- Για μοντέλα που επιτρέπουν την απενεργοποίηση του thinking, μπορείτε να περάσετε `thinking: {"type":"disabled"}`. Νέες λειτουργίες όπως `between_tools` και οι συνδυασμοί effort εξαρτώνται από το επιλεγμένο μοντέλο· η πλατφόρμα δεν τα απορρίπτει εκ των προτέρων με βάση παλιούς κανόνες μοντέλων. +- Ένας σταθερός προϋπολογισμός σκέψης μπορεί να μεταβιβαστεί μέσω του `budget_tokens`· τα νέα μοντέλα συνήθως χρησιμοποιούν `thinking.type=adaptive` και `output_config.effort`. Το αν υποστηρίζονται ο σταθερός προϋπολογισμός ή η απενεργοποίηση της σκέψης εξαρτάται από τις τρέχουσες δυνατότητες του επιλεγμένου μοντέλου. +- Σε συνομιλίες πολλών γύρων και κλήσεις εργαλείων, θα πρέπει να επιστρέφετε αυτούσιο το πλήρες μπλοκ thinking και το signature που επέστρεψε ο assistant· μην τροποποιείτε ούτε δημιουργείτε μόνοι σας signature. +- Η μεταβίβαση παραμέτρων δεν σημαίνει ότι κάθε μοντέλο υποστηρίζει όλες τις λειτουργίες. Οι διαπρωτοκολλιακές κλήσεις εξακολουθούν να απαιτούν μετατροπή και το εύρος υποστήριξης και τα σφάλματα για περιεχόμενο όπως `redacted_thinking` καθορίζονται από την υπηρεσία μοντέλου που επεξεργάζεται πραγματικά το αίτημα. -Σε αιτήματα ροής, το `summarized` παράγει `thinking_delta`· το `omitted` δεν παράγει `thinking_delta`, και διατηρεί μόνο τον κύκλο ζωής του thinking block και το `signature_delta`. +Σε αιτήματα ροής, το `summarized` παράγει `thinking_delta`· το `omitted` δεν παράγει `thinking_delta`, διατηρώντας μόνο τον κύκλο ζωής του μπλοκ thinking και το `signature_delta`. ## Μοντέλα όρασης -Το Claude υποστηρίζει πολυτροπικές εισόδους και μπορεί να επεξεργάζεται ταυτόχρονα κείμενο και εικόνες. Στο Messages API, μπορείτε να χρησιμοποιήσετε δυνατότητες όρασης ορίζοντας το `content` σε μορφή πίνακα και περνώντας blocks περιεχομένου εικόνας. +Το Claude υποστηρίζει πολυτροπική είσοδο και μπορεί να επεξεργάζεται ταυτόχρονα κείμενο και εικόνες. Στο Messages API, μπορείτε να χρησιμοποιήσετε τις δυνατότητες όρασης ορίζοντας το `content` σε μορφή πίνακα και περνώντας μπλοκ περιεχομένου εικόνας. ### Χρήση εικόνων κωδικοποιημένων σε Base64 @@ -456,7 +459,6 @@ print(response.json()) ``` ### Παράδειγμα cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -486,11 +488,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Οι υποστηριζόμενες μορφές εικόνων περιλαμβάνουν: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Οι υποστηριζόμενες μορφές εικόνας περιλαμβάνουν: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Έγγραφα και PDF -Τα PDF χρησιμοποιούν block περιεχομένου `document`, υποστηρίζοντας δύο σταθερές πηγές: Base64 και URL. Η πηγή Base64 πρέπει να χρησιμοποιεί `application/pdf`: +Τα PDF χρησιμοποιούν το μπλοκ περιεχομένου `document`, υποστηρίζοντας δύο σταθερές πηγές: Base64 και URL. Η πηγή Base64 πρέπει να χρησιμοποιεί `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -Η πηγή URL γράφεται ως `{"type":"url","url":"https://example.com/report.pdf"}`. Το `document` υποστηρίζει επίσης `text/plain` και πηγές `content` αποτελούμενες από blocks text/image· τα προαιρετικά πεδία περιλαμβάνουν `title`, `context` και `citations`. Η πηγή `file_id` του Files API ανήκει σε ανεξάρτητη beta λειτουργία και δεν περιλαμβάνεται στο σταθερό συμβόλαιο αυτής της διεπαφής. +Η πηγή URL γράφεται ως `{"type":"url","url":"https://example.com/report.pdf"}`. Το `document` υποστηρίζει επίσης το `text/plain` και την πηγή `content` που αποτελείται από μπλοκ text/image· τα προαιρετικά πεδία περιλαμβάνουν `title`, `context` και `citations`. Η πηγή `file_id` του Files API ανήκει σε ανεξάρτητη beta λειτουργία και δεν περιλαμβάνεται στο σταθερό συμβόλαιο αυτής της διεπαφής. -## Προσωρινή αποθήκευση prompt +## Προσωρινή αποθήκευση προτροπών -Το κορυφαίου επιπέδου `cache_control` τοποθετεί αυτόματα το σημείο διακοπής της cache στο τελευταίο block που μπορεί να αποθηκευτεί προσωρινά: +Το ανώτατου επιπέδου `cache_control` τοποθετεί αυτόματα το σημείο διακοπής της προσωρινής αποθήκευσης στο τελευταίο μπλοκ που μπορεί να αποθηκευτεί προσωρινά: ```python payload = { @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Όταν απαιτείται ακριβής έλεγχος θέσης, μπορείτε επίσης να γράψετε το ίδιο `cache_control` σε μπλοκ περιεχομένου text, image, document, tool_use, tool_result ή στον ορισμό εργαλείου. Το `ttl` υποστηρίζει `5m` (προεπιλογή) και `1h`· παρακαλούμε προσδιορίστε την εγγραφή και την επιτυχία της προσωρινής αποθήκευσης μέσω των `usage.cache_creation_input_tokens` και `usage.cache_read_input_tokens`. -Όταν η απόκριση παρέχει `usage.cache_creation`, ισχύει ότι `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Εάν το `cache_creation` είναι `null` ή παραλείπεται, αυτό υποδηλώνει ότι υπάρχει μόνο το συνολικό ποσό εγγραφής στην προσωρινή αποθήκευση, χωρίς έγκυρη ανάλυση TTL· σε αυτήν την περίπτωση, μην θεωρείτε κανένα bucket ως γνωστό 0, και η χρέωση και το σύνολο εξακολουθούν να βασίζονται στο aggregate πεδίο. +Όταν απαιτείται ακριβής έλεγχος της θέσης, μπορείτε επίσης να γράψετε το ίδιο `cache_control` σε μπλοκ περιεχομένου text, image, document, tool_use, tool_result ή σε ορισμό εργαλείου. Το `ttl` υποστηρίζει `5m` (προεπιλογή) και `1h`· χρησιμοποιήστε τα `usage.cache_creation_input_tokens` και `usage.cache_read_input_tokens` για να προσδιορίσετε την εγγραφή και την επιτυχία εύρεσης στην προσωρινή αποθήκευση. + +Όταν η απόκριση παρέχει `usage.cache_creation`, τότε `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Εάν το `cache_creation` είναι `null` ή παραλείπεται, αυτό υποδηλώνει ότι υπάρχει μόνο η συνολική ποσότητα εγγραφής στην προσωρινή αποθήκευση, χωρίς έγκυρη ανάλυση TTL· σε αυτήν την περίπτωση, μην θεωρείτε κανένα bucket ως γνωστό 0, ενώ η χρέωση και τα σύνολα εξακολουθούν να βασίζονται στο συγκεντρωτικό πεδίο. -Παράδειγμα αποτελέσματος επιστροφής: +Παράδειγμα επιστρεφόμενου αποτελέσματος: ```json { @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Όταν το μοντέλο αποφασίσει να καλέσει ένα εργαλείο, το `content` στο αποτέλεσμα επιστροφής θα περιλαμβάνει ένα μπλοκ περιεχομένου τύπου `tool_use`: +Όταν το μοντέλο αποφασίσει να καλέσει ένα εργαλείο, το `content` στο επιστρεφόμενο αποτέλεσμα θα περιλαμβάνει ένα μπλοκ περιεχομένου τύπου `tool_use`: ```json { @@ -637,7 +640,7 @@ print(response.json()) } ``` -Σημειώστε ότι το `stop_reason` είναι `tool_use`, υποδεικνύοντας ότι το μοντέλο χρειάζεται να καλέσει ένα εργαλείο. Αφού λάβετε αυτό το αποτέλεσμα, πρέπει να εκτελέσετε τη συνάρτηση εργαλείου και να επιστρέψετε το αποτέλεσμα στο μοντέλο με τη μορφή `tool_result`: +Σημειώστε ότι το `stop_reason` είναι `tool_use`, υποδεικνύοντας ότι το μοντέλο χρειάζεται να καλέσει το εργαλείο. Αφού λάβετε αυτό το αποτέλεσμα, πρέπει να εκτελέσετε τη συνάρτηση του εργαλείου και να επιστρέψετε το αποτέλεσμα στο μοντέλο με τη μορφή `tool_result`: ```python payload = { @@ -685,37 +688,36 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Το μοντέλο θα δημιουργήσει την τελική απόκριση σε φυσική γλώσσα βάσει του αποτελέσματος που επιστρέφεται από το εργαλείο. +Το μοντέλο θα δημιουργήσει την τελική απόκριση φυσικής γλώσσας με βάση το αποτέλεσμα που επιστρέφει το εργαλείο. ## Διαφορές από το Chat Completion API -Το Ace Data Cloud παρέχει ταυτόχρονα δύο μορφές Claude API, και οι κύριες διαφορές μεταξύ τους είναι οι εξής: - -Το `usage.input_tokens` του Messages API υποδηλώνει μόνο μη αποθηκευμένες εισόδους, ενώ τα `cache_read_input_tokens` και `cache_creation_input_tokens` είναι ανεξάρτητα buckets χρέωσης· και τα τρία υπολογίζονται ξεχωριστά με τις αντίστοιχες τιμές. +Το Ace Data Cloud παρέχει ταυτόχρονα δύο μορφές Claude API, με τις κύριες διαφορές τους να είναι οι εξής: +Το `usage.input_tokens` του Messages API αντιπροσωπεύει μόνο μη αποθηκευμένες εισόδους, ενώ τα `cache_read_input_tokens` και `cache_creation_input_tokens` είναι ανεξάρτητα buckets χρέωσης· και τα τρία υπολογίζονται ξεχωριστά στις αντίστοιχες τιμές. | Χαρακτηριστικό | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Μορφή | Εγγενής μορφή Anthropic | Μορφή συμβατή με OpenAI | -| Μήνυμα συστήματος | Ανεξάρτητο πεδίο `system` | Μεταβιβάζεται μέσω `role: "system"` στο `messages` | -| Δομή απόκρισης | Πίνακας `content` (υποστηρίζει πολλούς τύπους) | Πίνακας `choices` (περιλαμβάνει `message`) | -| Μορφή ροής | Συμβάντα SSE (πολλοί τύποι συμβάντων) | Γραμμές SSE `data` | -| Βαθιά σκέψη | Εγγενή `thinking` και `output_config.effort` | Προεπιλεγμένη στρατηγική μοντέλου και παράμετροι συμβατότητας | -| Κλήση εργαλείων | Εγγενή `tools` + `input_schema` | Μορφή `tools` συμβατή με OpenAI | +| Μορφή | Εγγενής μορφή Anthropic | Συμβατή μορφή OpenAI | +| Προτροπή συστήματος | Ανεξάρτητο πεδίο `system` | Μεταδίδεται μέσω του `role: "system"` στα `messages` | +| Δομή απόκρισης | Πίνακας `content` (υποστηρίζει πολλαπλούς τύπους) | Πίνακας `choices` (περιλαμβάνει `message`) | +| Μορφή ροής | Συμβάντα SSE (πολλαπλοί τύποι συμβάντων) | Γραμμές SSE `data` | +| Βαθιά σκέψη | Εγγενές `thinking` και `output_config.effort` | Προεπιλεγμένη στρατηγική μοντέλου και συμβατές παράμετροι | +| Κλήση εργαλείων | Εγγενές `tools` + `input_schema` | Μορφή `tools` συμβατή με OpenAI | | Στατιστικά Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Εάν το σύστημά σας έχει ήδη ενσωματωθεί με API μορφής OpenAI, μπορείτε να χρησιμοποιήσετε το Chat Completion API για απρόσκοπτη εναλλαγή. Εάν χρειάζεται να χρησιμοποιήσετε όλες τις εγγενείς δυνατότητες του Claude, συνιστάται να χρησιμοποιήσετε το Messages API. +Εάν το σύστημά σας έχει ήδη ενσωματωθεί με API μορφής OpenAI, μπορείτε να χρησιμοποιήσετε το Chat Completion API για απρόσκοπτη εναλλαγή. Εάν χρειάζεστε να χρησιμοποιήσετε όλες τις εγγενείς δυνατότητες του Claude, συνιστάται να χρησιμοποιήσετε το Messages API. -## Χειρισμός σφαλμάτων +## Διαχείριση σφαλμάτων -Οι αποκρίσεις σφάλματος του δημόσιου API χρησιμοποιούν το envelope της πλατφόρμας Ace Data Cloud: το `error.code` είναι σταθερός κωδικός σφάλματος, το `error.message` είναι η περιγραφή και το `trace_id` χρησιμοποιείται για τη διερεύνηση αιτημάτων. Οι συνήθεις καταστάσεις HTTP περιλαμβάνουν: +Οι αποκρίσεις σφαλμάτων των δημόσιων διεπαφών χρησιμοποιούν το envelope της πλατφόρμας Ace Data Cloud: το `error.code` είναι ένας σταθερός κωδικός σφάλματος, το `error.message` είναι η περιγραφή και το `trace_id` χρησιμοποιείται για τη διερεύνηση αιτημάτων. Οι συνήθεις καταστάσεις HTTP περιλαμβάνουν: -- `400`: Οι παράμετροι αιτήματος ή το περιεχόμενο πρωτοκόλλου είναι μη έγκυρα. +- `400`: Οι παράμετροι αιτήματος ή το περιεχόμενο πρωτοκόλλου δεν είναι έγκυρα. - `401`: Το διακριτικό εξουσιοδότησης είναι μη έγκυρο, λείπει ή έχει λήξει. -- `403`: Απαγορεύεται η πρόσβαση, το υπόλοιπο είναι ανεπαρκές ή ο περιορισμός ποσόστωσης έχει ενεργοποιηθεί. +- `403`: Η πρόσβαση απαγορεύεται, το υπόλοιπο είναι ανεπαρκές ή το όριο χρήσης είναι περιορισμένο. - `404`: Το API ή το μοντέλο δεν υπάρχει. -- `413`: Το σώμα αιτήματος είναι πολύ μεγάλο. +- `413`: Το σώμα του αιτήματος είναι υπερβολικά μεγάλο. - `429`: Πάρα πολλά αιτήματα. -- `500` / `503` / `504`: Σφάλμα υπηρεσίας, προσωρινή μη διαθεσιμότητα ή χρονικό όριο επεξεργασίας. +- `500` / `503` / `504`: Σφάλμα υπηρεσίας, προσωρινά μη διαθέσιμη ή χρονικό όριο επεξεργασίας. ### Παράδειγμα απόκρισης σφάλματος @@ -729,7 +731,8 @@ print(response.json()) } ``` -Αυτή η δομή σφάλματος είναι το συμβόλαιο χρόνου εκτέλεσης του Ace Data Cloud και δεν ισοδυναμεί με το επίσημο envelope σφαλμάτων του Anthropic· παρακαλούμε χειριστείτε το σύμφωνα με την κατάσταση HTTP και το `error.code`. +Αυτή η δομή σφάλματος είναι το συμβόλαιο χρόνου εκτέλεσης του Ace Data Cloud και δεν ισοδυναμεί με το επίσημο envelope σφαλμάτων της Anthropic· παρακαλούμε να γίνεται χειρισμός βάσει της κατάστασης HTTP και του `error.code`. ## Συμπέρασμα -Μέσω αυτού του εγγράφου, έχετε ήδη μάθει πώς να χρησιμοποιείτε το Claude Messages API για να καλείτε τις λειτουργίες συνομιλίας του Claude στη μορφή εγγενή στο Anthropic. Το Messages API υποστηρίζει πλούσιες λειτουργίες όπως βασική συνομιλία, προτροπές συστήματος, αποκρίσεις ροής, συνομιλίες πολλαπλών γύρων, εις βάθος σκέψη, οπτική κατανόηση, PDF, προσωρινή αποθήκευση προτροπών και κλήση εργαλείων. Εάν έχετε οποιεσδήποτε ερωτήσεις, μη διστάσετε να επικοινωνήσετε με την ομάδα τεχνικής υποστήριξής μας. + +Μέσω αυτού του εγγράφου, έχετε ήδη μάθει πώς να χρησιμοποιείτε το Claude Messages API για να καλείτε τις λειτουργίες συνομιλίας του Claude σε εγγενή μορφή Anthropic. Το Messages API υποστηρίζει πλούσιες λειτουργίες όπως βασική συνομιλία, προτροπές συστήματος, αποκρίσεις ροής, συνομιλίες πολλαπλών γύρων, βαθιά σκέψη, οπτική κατανόηση, PDF, προσωρινή αποθήκευση προτροπών και κλήση εργαλείων. Εάν έχετε οποιεσδήποτε ερωτήσεις, επικοινωνήστε με την ομάδα τεχνικής υποστήριξής μας ανά πάσα στιγμή. diff --git a/el/guides/openai/openai_embeddings.mdx b/el/guides/openai/openai_embeddings.mdx index 9c56ad988..554f970a8 100644 --- a/el/guides/openai/openai_embeddings.mdx +++ b/el/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API Αίτηση και Χρήση" +title: "Αίτηση και χρήση του OpenAI Embeddings API" description: "OpenAI generation API guide - Ace Data Cloud" --- -Η υπηρεσία λέξεων OpenAI χρησιμοποιείται για τη δημιουργία λέξεων που αντιπροσωπεύουν τα αποτελέσματα του εισαγόμενου κειμένου. +Η υπηρεσία διανυσμάτων λέξεων του OpenAI χρησιμοποιείται για τη δημιουργία αποτελεσμάτων διανυσμάτων λέξεων που αναπαριστούν το εισαγόμενο κείμενο. -Αυτό το έγγραφο περιγράφει κυρίως τη διαδικασία χρήσης του OpenAI Embeddings API, με το οποίο μπορούμε να δημιουργήσουμε ενσωματωμένα διανύσματα που αντιπροσωπεύουν το εισαγόμενο κείμενο. +Αυτό το έγγραφο παρουσιάζει κυρίως τη διαδικασία χρήσης των λειτουργιών του OpenAI Embeddings API, με το οποίο μπορούμε να δημιουργήσουμε διανύσματα ενσωμάτωσης που αναπαριστούν το εισαγόμενο κείμενο。。 -## Διαδικασία Αίτησης +## Διαδικασία αίτησης -Για να χρησιμοποιήσετε το OpenAI Embeddings API, πρώτα πηγαίνετε στο [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) για να αποκτήσετε το API Token σας, το οποίο θα κρατήσετε για μελλοντική χρήση. +Για να χρησιμοποιήσετε το OpenAI Embeddings API, μεταβείτε πρώτα στην [Κονσόλα Ace Data Cloud](https://platform.acedata.cloud/console/applications) για να αποκτήσετε το API Token σας και κρατήστε το για μελλοντική χρήση. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Εάν δεν έχετε συνδεθεί ή εγγραφεί, θα μεταφερθείτε αυτόματα στη σελίδα σύνδεσης που σας προσκαλεί να εγγραφείτε και να συνδεθείτε, και μετά θα επιστρέψετε αυτόματα στη σελίδα που βρίσκεστε. +Εάν δεν έχετε ακόμη συνδεθεί ή εγγραφεί, θα ανακατευθυνθείτε αυτόματα στη σελίδα σύνδεσης για να εγγραφείτε και να συνδεθείτε, και μετά την ολοκλήρωση θα επιστρέψετε αυτόματα στην τρέχουσα σελίδα. -**Ένα API Token αρκεί για να καλέσετε όλες τις υπηρεσίες της πλατφόρμας, χωρίς να χρειάζεται να κάνετε ξεχωριστές αιτήσεις για κάθε υπηρεσία.** Η πρώτη αίτηση θα σας δώσει δωρεάν πιστώσεις για να δοκιμάσετε δωρεάν. Όταν οι πιστώσεις σας εξαντληθούν, μπορείτε να ανανεώσετε το γενικό σας υπόλοιπο στο [Console](https://platform.acedata.cloud/console/coin). +**Ένα API Token αρκεί για την κλήση όλων των υπηρεσιών της πλατφόρμας, χωρίς να χρειάζεται ξεχωριστή αίτηση για κάθε υπηρεσία.** Με την πρώτη αίτηση προσφέρεται δωρεάν πίστωση για δωρεάν δοκιμή· όταν η πίστωση δεν επαρκεί, μπορείτε να φορτίσετε το γενικό υπόλοιπο στην [κονσόλα](https://platform.acedata.cloud/console/coin). > 📘 Πλήρης τεκμηρίωση: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## Βασική Χρήση +## Βασική χρήση -Στη συνέχεια, μπορείτε να συμπληρώσετε τα αντίστοιχα περιεχόμενα στην οθόνη, όπως φαίνεται στην εικόνα: +Στη συνέχεια, μπορείτε να συμπληρώσετε το αντίστοιχο περιεχόμενο στη διεπαφή, όπως φαίνεται στην εικόνα:

-Κατά την πρώτη χρήση αυτής της διεπαφής, πρέπει τουλάχιστον να συμπληρώσετε τρία περιεχόμενα, ένα είναι το `authorization`, το οποίο μπορείτε να επιλέξετε απευθείας από τη λίστα. Ένα άλλο παράμετρο είναι το `model`, το `model` είναι η κατηγορία μοντέλου που επιλέγουμε να χρησιμοποιήσουμε από την επίσημη ιστοσελίδα του OpenAI, εδώ έχουμε κυρίως 3 μοντέλα, περισσότερες λεπτομέρειες μπορείτε να δείτε στα μοντέλα που παρέχουμε. Η τελευταία παράμετρος είναι το `input`, το `input` είναι το κείμενο που θέλουμε να μετατρέψουμε σε λέξεις. +Κατά την πρώτη χρήση αυτής της διεπαφής, χρειάζεται να συμπληρώσουμε τουλάχιστον τρία πεδία. Το ένα είναι το `authorization`, το οποίο μπορεί να επιλεγεί απευθείας από την αναπτυσσόμενη λίστα. Μια άλλη παράμετρος είναι το `model`, όπου το `model` είναι η κατηγορία μοντέλου του επίσημου ιστότοπου OpenAI που επιλέγουμε να χρησιμοποιήσουμε. Τα διαθέσιμα μοντέλα επί του παρόντος είναι τα `text-embedding-3-small` και `text-embedding-3-large`. Το `text-embedding-ada-002` δεν παρέχεται πλέον· εάν ένα υπάρχον ευρετήριο διανυσμάτων χρησιμοποιεί αυτό το παλιό μοντέλο, δεν μπορούν να αναμειχθούν απευθείας τα διανύσματα του νέου μοντέλου και πρέπει να δημιουργηθεί ξανά το ευρετήριο. Η τελευταία παράμετρος είναι το `input`, όπου το `input` είναι το κείμενο που χρειαζόμαστε να μετατρέψουμε σε διανύσματα λέξεων. -Μπορείτε επίσης να παρατηρήσετε ότι στα δεξιά υπάρχει η αντίστοιχη γεννήτρια κώδικα κλήσης, μπορείτε να αντιγράψετε τον κώδικα και να τον εκτελέσετε απευθείας ή να κάνετε κλικ στο κουμπί «Δοκιμή» για να το δοκιμάσετε. +Ταυτόχρονα, μπορείτε να παρατηρήσετε ότι στα δεξιά δημιουργείται ο αντίστοιχος κώδικας κλήσης. Μπορείτε να αντιγράψετε τον κώδικα και να τον εκτελέσετε απευθείας, ή να κάνετε απευθείας κλικ στο κουμπί «Try» για δοκιμή. Προαιρετικές παράμετροι: -- `dimensions`: Κόβει τις διαστάσεις του διανύσματος, η προεπιλεγμένη έξοδος είναι η πλήρης διάσταση. -- `encoding_format`: Μορφή επιστροφής, μπορεί να είναι `float` ή `base64`. +- `dimensions`: περικοπή των διαστάσεων του διανύσματος, με προεπιλογή την έξοδο των πλήρων διαστάσεων. +- `encoding_format`: μορφή επιστροφής, με επιλογές `float` ή `base64`.

-Παράδειγμα κώδικα κλήσης Python: +Δείγμα κώδικα κλήσης Python: ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Μετά την κλήση, διαπιστώνουμε ότι το αποτέλεσμα επιστροφής είναι το εξής: +Μετά την κλήση, διαπιστώνουμε ότι το αποτέλεσμα επιστροφής είναι το ακόλουθο: ```json { @@ -97,7 +97,7 @@ print(response.text) ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,25 +105,25 @@ print(response.text) } ``` -Το αποτέλεσμα επιστροφής περιλαμβάνει πολλά πεδία, τα οποία περιγράφονται ως εξής: +Το αποτέλεσμα επιστροφής περιέχει συνολικά πολλαπλά πεδία, τα οποία παρουσιάζονται παρακάτω: -- `model`, το μοντέλο που χρησιμοποιήθηκε για τη μετατροπή του κειμένου σε λέξεις. -- `usage`, οι πληροφορίες token που χρησιμοποιήθηκαν για τη μετατροπή του κειμένου σε λέξεις. -- `data`, το αποτέλεσμα των λέξεων που προήλθε από τη μετατροπή του κειμένου. +- `model`, το μοντέλο που χρησιμοποιήθηκε για τη μετατροπή του κειμένου σε διανύσματα λέξεων αυτή τη φορά. +- `usage`, οι πληροφορίες token που χρησιμοποιήθηκαν για τη μετατροπή του κειμένου σε διανύσματα λέξεων αυτή τη φορά. +- `data`, το αποτέλεσμα των διανυσμάτων λέξεων μετά τη μετατροπή του κειμένου. -Το `data` περιέχει τις συγκεκριμένες πληροφορίες των λέξεων που αντιστοιχούν στο κείμενο, όπου το `embedding` είναι το συγκεκριμένο αποτέλεσμα των λέξεων που δημιουργήθηκαν. +Μεταξύ αυτών, το `data` περιέχει τις συγκεκριμένες πληροφορίες για τα διανύσματα λέξεων που αντιστοιχούν στο κείμενο, και το `embedding` μέσα σε αυτό είναι το συγκεκριμένο αποτέλεσμα των παραγόμενων διανυσμάτων λέξεων. -## Διαχείριση Σφαλμάτων +## Διαχείριση σφαλμάτων -Κατά την κλήση του API, εάν προκύψει σφάλμα, το API θα επιστρέψει τον αντίστοιχο κωδικό σφάλματος και τις πληροφορίες. Για παράδειγμα: +Κατά την κλήση του API, εάν παρουσιαστεί σφάλμα, το API θα επιστρέψει τον αντίστοιχο κωδικό σφάλματος και τις σχετικές πληροφορίες. Για παράδειγμα: -- `400 token_mismatched`: Κακή αίτηση, πιθανώς λόγω ελλιπών ή μη έγκυρων παραμέτρων. -- `400 api_not_implemented`: Κακή αίτηση, πιθανώς λόγω ελλιπών ή μη έγκυρων παραμέτρων. +- `400 token_mismatched`: Εσφαλμένο αίτημα, πιθανώς λόγω ελλιπών ή μη έγκυρων παραμέτρων. +- `400 api_not_implemented`: Εσφαλμένο αίτημα, πιθανώς λόγω ελλιπών ή μη έγκυρων παραμέτρων. - `401 invalid_token`: Μη εξουσιοδοτημένο, μη έγκυρο ή ελλιπές token εξουσιοδότησης. -- `429 too_many_requests`: Πάρα πολλές αιτήσεις, έχετε υπερβεί το όριο ρυθμού. +- `429 too_many_requests`: Πάρα πολλά αιτήματα, έχετε υπερβεί το όριο ρυθμού. - `500 api_error`: Εσωτερικό σφάλμα διακομιστή, κάτι πήγε στραβά στον διακομιστή. -### Παράδειγμα Σφάλματος Απόκρισης +### Παράδειγμα απόκρισης σφάλματος ```json { @@ -138,4 +138,4 @@ print(response.text) ## Συμπέρασμα -Μέσω αυτού του εγγράφου, έχετε κατανοήσει πώς να χρησιμοποιήσετε το OpenAI Embeddings API για να αξιοποιήσετε εύκολα τη δυνατότητα δημιουργίας λέξεων από την επίσημη OpenAI. Ελπίζουμε αυτό το έγγραφο να σας βοηθήσει να συνδεθείτε και να χρησιμοποιήσετε καλύτερα αυτό το API. Εάν έχετε οποιαδήποτε ερώτηση, παρακαλούμε επικοινωνήστε με την τεχνική υποστήριξή μας. +Μέσω αυτού του εγγράφου, έχετε ήδη κατανοήσει πώς να χρησιμοποιείτε το OpenAI Embeddings API για να αξιοποιείτε εύκολα τη λειτουργία δημιουργίας διανυσμάτων λέξεων του επίσημου OpenAI. Ελπίζουμε ότι αυτό το έγγραφο θα σας βοηθήσει να ενσωματώσετε και να χρησιμοποιήσετε καλύτερα αυτό το API. Εάν έχετε οποιαδήποτε ερώτηση, παρακαλούμε επικοινωνήστε ανά πάσα στιγμή με την ομάδα τεχνικής υποστήριξής μας. diff --git a/el/guides/platform/wework_bot.mdx b/el/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..95d61407f --- /dev/null +++ b/el/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "Bot του WeCom" +description: "Platform API guide - Ace Data Cloud" +--- + +Αναπτύξτε τη δική σας παρουσία λογαριασμού WeCom, συνδεθείτε σαρώνοντας με το κινητό WeCom και διαβάστε τον λογαριασμό, τις επαφές, τις συνομιλίες και τα τοπικά συγχρονισμένα μηνύματα μέσω REST API ή MCP. Η παρουσία αντιστοιχεί σε έναν συνηθισμένο λογαριασμό WeCom και δεν απαιτεί ιδιωτικοποιημένο διακομιστή ή ρύθμιση εταιρικού domain email. + +Αυτή τη στιγμή βρίσκεται σε Alpha. Η ανάγνωση λογαριασμού έχει ολοκληρώσει πραγματική επαλήθευση συνομιλιών· η αποστολή κειμένου από τον ίδιο τον χρήστη και η ανάγνωση συμβάντων έχουν ολοκληρώσει πραγματική αποδοχή· οι ενέργειες για άλλες επαφές, ομάδες και η ανάκτηση νέων παρουσιών εξακολουθούν να χρειάζονται αποδοχή στο περιβάλλον ανάπτυξης. Η αποστολή πολυμέσων, η απάντηση με παράθεση, οι πραγματικές αναφορές @, η διαχείριση μελών ομάδας και οι αποδείξεις παράδοσης δεν είναι ακόμη διαθέσιμες. Ανατρέξτε στην τιμή επιστροφής του `/api/capabilities` της παρουσίας. + +## Ανάπτυξη και σύνδεση + +Ενεργοποιήστε την υπηρεσία στην κατηγορία Deployment και επιλέξτε πακέτο διάρκειας παρουσίας. Μετά την ανάπτυξη, ανοίξτε τη σελίδα διαχείρισης και σαρώστε με το WeCom του ίδιου του λογαριασμού· εάν απαιτείται επιβεβαίωση από κινητό ή άλλα βήματα σύνδεσης, ανοίξτε την απομακρυσμένη επιφάνεια εργασίας και εισαγάγετε τον κωδικό επιφάνειας εργασίας της παρουσίας. Τα διαπιστευτήρια API και ο κωδικός επιφάνειας εργασίας είναι ανεξάρτητα. Τα στοιχεία σύνδεσης αποθηκεύονται στον δίσκο της παρουσίας· η αναδημιουργία του κοντέινερ διατηρεί τον δίσκο· η διαγραφή του δίσκου διαγράφει την τοπική συνεδρία. + +Κάθε παρουσία χρεώνεται ανεξάρτητα και λειτουργεί για τη διάρκεια που έχει αγοραστεί. Οι κλήσεις REST / MCP δεν χρεώνονται επιπλέον ανά μήνυμα· οι πραγματικές τιμές υπόκεινται στη σελίδα του πακέτου. Προς το παρόν, η προεπιλεγμένη αναφορά είναι τα πακέτα διάρκειας για bot WeChat· πριν από την τελική διάθεση, απαιτείται επιβεβαίωση τιμολόγησης σε συνδυασμό με τους πόρους λειτουργίας. + +## API και MCP + +Χρησιμοποιήστε τη διεύθυνση API της παρουσίας στη σελίδα διαχείρισης· όλες οι διεπαφές λογαριασμού φέρουν `Authorization: Bearer `. Αυτές οι διαδρομές ανήκουν σε αποκλειστική παρουσία και δεν είναι κοινόχρηστη πύλη API. Η διεύθυνση MCP είναι η διεύθυνση της παρουσίας με προσθήκη `/mcp/` και χρησιμοποιεί το ίδιο Bearer token. + +| Διεπαφή | Λειτουργία | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Αν ο λογαριασμός είναι έτοιμος και η λίστα δυνατοτήτων | +| `GET /api/auth/qr` | PNG Base64 του τρέχοντος κωδικού QR σύνδεσης | +| `GET /api/account` | Τρέχων λογαριασμός | +| `GET /api/contacts?kind=all` | Εσωτερικοί συνάδελφοι και εξωτερικές επαφές· μπορεί να καθοριστεί internal / external | +| `GET /api/conversations` | Τοπικές συνομιλίες, διατηρούν τα αρχικά ID συνομιλίας | +| `GET /api/messages` | Τοπικά συγχρονισμένα μηνύματα· παράμετροι conversation_id, after_rowid, limit | +| `POST /api/search` | Αναζήτηση επαφών, συνομιλιών και τοπικού κειμένου | +| `POST /api/messages` | Ασύγχρονη εργασία αποστολής κειμένου, πρέπει να παρέχεται Idempotency-Key | +| `POST /api/messages/send` | Ίδιο σημείο εισόδου αποστολής, υποστηρίζει έναν ή πολλούς στόχους | +| `GET /api/groups/{conversation_id}` | Τοπικά συγχρονισμένες πληροφορίες ομάδας και μέλη | +| `GET /api/tasks` | Πρόσφατες εργασίες και αποτελέσματα ανά στόχο | +| `GET /api/tasks/{id}` | Ερώτημα αποτελέσματος αποστολής | +| `POST /api/tasks/{id}/cancel` | Ακύρωση εργασίας που δεν έχει ξεκινήσει ακόμη | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Παύση αυτοματοποίησης· συνέχιση μετά την επαλήθευση από τον ίδιο τον χρήστη | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Κατάσταση παρουσίας και τρέχουσα οθόνη, και τα δύο απαιτούν έλεγχο ταυτότητας | +| `GET /api/events?after=0` | Συμβάντα μηνυμάτων με επαναλήψιμο δρομέα | +| `WS /ws` | Ροή συμβάντων μηνυμάτων, έλεγχος ταυτότητας Bearer | + +Το σώμα αποστολής περιλαμβάνει `target`, `type: "text"` και `text`. Το `target` δέχεται ID συνομιλίας, ID επαφής, ID εταιρικού χρήστη ή μοναδικό πλήρες όνομα· προτιμήστε ID· όταν το εμφανιζόμενο όνομα εξακολουθεί να μην μπορεί να εντοπιστεί μοναδικά, η παρουσία θα απορρίψει την ενέργεια και δεν θα μαντέψει το αντικείμενο. Για επαφές χωρίς τοπική συνομιλία, θα ανοιχθεί πρώτα η συνομιλία μέσω του πελάτη και θα γίνει αποστολή αφού επαληθευτεί το πραγματικό ID συνομιλίας. Η κεφαλίδα αιτήματος `Idempotency-Key` έχει 8–128 γράμματα, αριθμούς ή `_.:-`. Τα επαναλαμβανόμενα αιτήματα για την ίδια ενέργεια πρέπει να επαναχρησιμοποιούν το ίδιο κλειδί και το ίδιο σώμα αιτήματος. + +Αντικαταστήστε το `target` με τον πίνακα `targets` για σειριακή αποστολή σε 1–50 ρητά καθορισμένους στόχους. Τα δύο δεν μπορούν να παρέχονται ταυτόχρονα. Όλοι οι στόχοι ολοκληρώνουν πρώτα την επίλυση ταυτότητας και διαφορετικά ψευδώνυμα που δείχνουν στο ίδιο αντικείμενο θα απορρίπτονται. Μετά την αποτυχία ενός στόχου, οι επόμενες αποστολές σταματούν και τα αποτελέσματα εργασίας καταγράφουν ανά στοιχείο `succeeded`, `failed`, `unknown` ή `not_attempted`· μην θεωρείτε τη μερική επιτυχία ως πλήρη επιτυχία. Αυτή η διαδικασία χρειάζεται επίσης να ολοκληρώσει πραγματική αποδοχή καθορισμένων επαφών στο περιβάλλον ανάπτυξης. + +Οι εργασίες μπορεί να βρίσκονται σε queued, running, submitting, succeeded, failed, unknown ή cancelled. Το `succeeded` υποδηλώνει ότι, μετά την υποβολή, βρέθηκαν το ακριβές κείμενο και το ID μηνύματος διακομιστή στην αντίστοιχη καταγραφή συνομιλίας· το `delivered` εξακολουθεί να είναι null και δεν υποδηλώνει ότι το άλλο μέρος το έχει λάβει. Το unknown υποδηλώνει ότι το αποτέλεσμα είναι ασαφές· ελέγξτε το ιστορικό και μην επαναλάβετε την αποστολή με νέο κλειδί. Η παρουσία δεν επαναποστέλλει αυτόματα εργασίες που διακόπηκαν. + +Το ιστορικό περιλαμβάνει μόνο περιεχόμενο που έχει ήδη συγχρονιστεί από τον πελάτη και δεν μπορεί να εγγυηθεί όλο το ιστορικό. Τα μη κειμενικά μηνύματα μπορεί να επιστρέφουν τύπο unknown· η λήψη συνημμένων δεν είναι ακόμη διαθέσιμη. Τα συμβάντα διατηρούν τις πιο πρόσφατες 10.000 εγγραφές· το `gap` υποδηλώνει ότι ο δρομέας έχει υπερβεί το παράθυρο διατήρησης. Η πρώτη σύνδεση δεν επαναμεταδίδει παλιό ιστορικό ως νέα μηνύματα. + +Τα `server_accepted` και `server_id` στο ιστορικό μηνυμάτων μπορούν να χρησιμοποιηθούν για να επαληθευτεί αν ο διακομιστής έχει αποδεχθεί το τοπικό μήνυμα· όταν εμφανίζεται μόνο τοπική εγγραφή χωρίς ID διακομιστή, δεν μπορεί να θεωρηθεί ότι η αποστολή πέτυχε. Αυτά τα πεδία δεν υποδηλώνουν ότι ο παραλήπτης έχει λάβει ή διαβάσει το μήνυμα. Οι εγγραφές συμβάντων διατηρούν την κατάσταση κατά τη στιγμή της δημιουργίας· για να ερωτήσετε την τρέχουσα κατάσταση επιβεβαίωσης, χρησιμοποιήστε τη διεπαφή ιστορικού μηνυμάτων. + +## Λογαριασμοί και διαπιστευτήρια + +Συνδεθείτε μόνο σε λογαριασμούς για τους οποίους ο ίδιος ο χρήστης έχει δικαίωμα λειτουργίας. Ρυθμίστε το API token σε αξιόπιστες εφαρμογές· μπορεί να προσπελάσει τα δεδομένα λογαριασμού αυτής της παρουσίας. Μη δημοσιεύετε κωδικούς, κωδικούς QR ή στιγμιότυπα οθόνης συνομιλιών σε δημόσια σημεία. Η παύση της παρουσίας θα διακόψει τα συμβάντα πραγματικού χρόνου. Μετά την αποσύνδεση λογαριασμού ή την αφαίρεση της συσκευής από την πλευρά του κινητού, απαιτείται εκ νέου σύνδεση. + +Η τρέχουσα εισαγωγή κειμένου υποστηρίζει μόνο μία γραμμή· οι αλλαγές γραμμής θα απορρίπτονται ρητά πριν από την αποστολή. Όταν ο πελάτης απαιτεί επαλήθευση ασφαλείας ή εκ νέου σύνδεση, αυτή πρέπει να ολοκληρώνεται από τον ίδιο τον χρήστη στην απομακρυσμένη επιφάνεια εργασίας· η παρουσία δεν θα παρακάμψει την επαλήθευση. Εργασίες μετά από διακοπή επαλήθευσης μπορεί να επιστρέφουν unknown· ερωτήστε πρώτα την καταγραφή μηνυμάτων και μην επαναστείλετε με νέο κλειδί ιδεμποτικότητας. + +Όταν εντοπιστεί προτροπή επαλήθευσης ασφαλείας, έξοδος ή αλλαγή λογαριασμού, η ουρά αυτοματοποίησης θα τίθεται σε μόνιμη παύση. Αφού ολοκληρωθεί η επαλήθευση μέσω κινητού, μπορείτε να συνεχίσετε τις εργασίες που δεν έχουν εκτελεστεί ακόμη μέσω της επιλογής «Συνέχιση μετά την επαλήθευση» στην κονσόλα παρουσίας· εργασίες που έχουν ήδη υποβληθεί αλλά έχουν αβέβαιο αποτέλεσμα δεν θα επανασταλούν. Η συνήθης απομακρυσμένη εργασία μπορεί επίσης να ενεργοποιήσει επαλήθευση ασφαλείας WeCom. Το παράθυρο 24 ωρών χωρίς εκ νέου κλείδωμα μετά την επαλήθευση που αναφέρεται στις επίσημες οδηγίες δεν σημαίνει ότι η ανίχνευση έχει ήδη εξαλειφθεί, ούτε σημαίνει ότι η παρουσία μπορεί να εγγυηθεί μακροχρόνια λειτουργία χωρίς επίβλεψη. diff --git a/en/guides/claude/claude_messages.mdx b/en/guides/claude/claude_messages.mdx index 395399138..42026952d 100644 --- a/en/guides/claude/claude_messages.mdx +++ b/en/guides/claude/claude_messages.mdx @@ -3,9 +3,9 @@ title: "Claude Messages API Application and Usage" description: "Claude AI integration guide - Ace Data Cloud" --- -Anthropic Claude is a very powerful AI conversational system. Simply enter a prompt, and it can generate fluent and natural responses in just a few seconds. Claude Messages API is Anthropic's official native API format. Unlike the OpenAI-compatible format (Chat Completion), it uses Anthropic's own request and response structure, enabling better use of Claude's unique capabilities, such as multimodal content input, tool calling, extended thinking, and other advanced features. +Anthropic Claude is a very powerful AI conversation system. Simply enter a prompt, and it can generate fluent and natural responses in just a few seconds. Claude Messages API is Anthropic's official native API format. Unlike the OpenAI-compatible format (Chat Completion), it uses Anthropic's own request and response structure, enabling better utilization of Claude's unique capabilities, such as multimodal content input, tool calling, extended thinking, and other advanced features. -This document mainly introduces the usage process of Claude Messages API operations. With it, we can use native interfaces consistent with Anthropic's official ones to invoke Claude's conversational capabilities. +This document mainly introduces the usage process of Claude Messages API operations. With it, we can use native interfaces consistent with Anthropic's official ones to call Claude's conversation capabilities. ## Application Process @@ -13,24 +13,24 @@ To use Claude Messages API, first go to the [Ace Data Cloud Console](https://pla ![](https://cdn.acedata.cloud/dvc3cg.jpg) -If you have not yet logged in or registered, you will be automatically redirected to the login page and invited to register and log in. After completion, you will automatically return to the current page. +If you have not yet logged in or registered, you will be automatically redirected to the login page to register and log in, and will automatically return to the current page after completion. -**One API Token can invoke all platform services; there is no need to apply separately for each service.** Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the [Console](https://platform.acedata.cloud/console/coin). +**One API Token can call all platform services; there is no need to apply separately for each service.** Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the [Console](https://platform.acedata.cloud/console/coin). -> 📘 Full documentation: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) +> 📘 Complete documentation: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Basic Usage The request path for Claude Messages API is `/v1/messages`, consistent with Anthropic's official API. We need to provide at least three required parameters: -- `model`: Select the Claude model to use. `claude-opus-5-5` is available only through the Messages API, supports 1 million Token context, a maximum output of 128K Tokens, and always enables adaptive thinking. The latest flagship is `claude-fable-5-1` (1 million Token context, maximum output of 128K Tokens); the original `claude-fable-5` remains retained for compatibility. `claude-sonnet-5-5` has joined the native Messages series interface, supports image input and adaptive thinking; its official reference prices for input, output, and cache reads are respectively $2, $10, and $0.20 per million Tokens. -- `messages`: The input message array. Each message includes `role` (role) and `content` (content), where `role` supports `user` and `assistant`. +- `model`: Select the Claude model to use. `claude-opus-5-5` is available only through the Messages API, supports 1 million Token context, a maximum output of 128K Tokens, and always enables adaptive thinking. The latest flagship is `claude-fable-5-1` (1 million Token context, maximum output of 128K Tokens); the original `claude-fable-5` remains compatible and retained. `claude-sonnet-5-5` has joined the native Messages series interface, supports image input and adaptive thinking; its official reference prices for input, output, and cache reads are 2, 10, and 0.20 USD per million Tokens respectively. +- `messages`: The array of input messages. Each message contains `role` (role) and `content` (content), where `role` supports `user` and `assistant`. - `max_tokens`: The maximum number of output tokens, used to limit the length of a single response. Common optional parameters: - `system`: System prompt, used to set the model's behavior and role. -- `temperature`: Generation randomness, between 0 and 1. The higher the value, the more divergent the response. +- `temperature`: Generation randomness, between 0 and 1. The larger the value, the more divergent the response. - `stream`: Whether to use streaming responses. Setting it to `true` enables a word-by-word return effect. - `stop_sequences`: Custom stop sequences. The model stops generating when it encounters these texts. - `top_p`: Nucleus sampling parameter, used with temperature to control generation randomness. @@ -38,6 +38,7 @@ Common optional parameters: - `tools`: Tool definitions, used to allow the model to call external functions. - `tool_choice`: Controls how the model uses the provided tools. - `cache_control`: Automatically creates a cache breakpoint at the last cacheable content block of the request; it can also be written on a specific content block. +- `metadata`: An optional request metadata object. `metadata.user_id` is a string that can pass a caller-defined user identifier, for example `{"user_id":"example-user-001"}`; it is recommended to use a stable identifier that does not contain personal information. It does not replace `Authorization` authentication and does not need to be included in the `messages` conversation content. ### cURL Example @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -After invoking it, the returned result is as follows: +After calling, the returned result is as follows: ```json { @@ -107,24 +110,24 @@ After invoking it, the returned result is as follows: ``` Description of returned result fields: - -- `id`: The unique identifier of this message. +- `id`: The unique identifier for this message. - `type`: Always `message`. - `role`: Always `assistant`. -- `content`: The response content array. Each element contains `type` (such as `text`) and the corresponding content. -- `model`: The name of the model that processed the request. -- `stop_reason`: The reason for stopping. Stable values include `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (the current assistant content can be returned unchanged to continue), `refusal`, and `model_context_window_exceeded`. -- `stop_sequence`: If stopped because of a custom stop sequence, displays the matched stop sequence text. -- `stop_details`: When `stop_reason` is `refusal`, it may contain the refusal category and explanation. -- `usage`: Token usage statistics. `input_tokens` are uncached inputs; `cache_creation_input_tokens` and `cache_read_input_tokens` are cache writes and reads respectively; `output_tokens` is the total number of output tokens. If `output_tokens_details.thinking_tokens` is returned, this value is a subset of `output_tokens`; do not add it again when calculating totals or costs. This detail may be `null` or omitted when there is no authoritative count. -- `usage.cache_creation`: Optional cache write TTL details, including `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens`. When the object exists, the sum of both equals `cache_creation_input_tokens`; a field being `null` or omitted means that no TTL breakdown is available for the current response and must not be interpreted as `0`. -- `usage.cost`: Non-streaming responses may contain a credit consumption object recorded by Ace Data Cloud, where `amount` is the actual consumption for this request, `currency` is the unit of measurement, and `list_amount` is the pre-discount amount (if any). The official base prices for Fable 5.1 cache reads are $0.25 per million Tokens, while the base prices for 5-minute and 1-hour cache writes are $12.50 and $20 per million Tokens respectively; actual platform prices are converted according to plan discounts. +- `content`: An array of reply content, where each element contains `type` (such as `text`) and the corresponding content. +- `model`: The name of the model processing the request. +- `stop_reason`: The reason for stopping. Stable values include `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (the current assistant content can be returned as-is to continue), `refusal`, and `model_context_window_exceeded`. +- `stop_sequence`: If stopped due to a custom stop sequence, displays the matched stop sequence text. +- `stop_details`: When `stop_reason` is `refusal`, may contain the refusal category and explanation. +- `usage`: Token usage statistics. `input_tokens` are uncached input; `cache_creation_input_tokens` and `cache_read_input_tokens` are cache writes and reads respectively; `output_tokens` is the total number of output tokens. If `output_tokens_details.thinking_tokens` is returned, this value is a subset of `output_tokens`; do not add it again when calculating totals or costs. This detail may be `null` or omitted when there is no authoritative count. +- `usage.cache_creation`: Optional cache write TTL details, including `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens`. When the object exists, the sum of the two equals `cache_creation_input_tokens`; fields being `null` or omitted indicates that the current response has no available TTL breakdown and must not be interpreted as `0`. +- `usage.cost`: Non-streaming responses may include an Ace Data Cloud-recorded credit consumption object, where `amount` is the actual consumption for this request, `currency` is the unit of measurement, and `list_amount` is the pre-discount amount (if any). The official cache-read list price for Fable 5.1 is $0.25/million Tokens, while the list prices for 5-minute and 1-hour cache writes are $12.50 and $20/million Tokens respectively; actual platform pricing is converted according to plan discounts. ## System Prompts -Claude Messages API supports setting system prompts through the `system` field, used to define the model's behavior, role, and context. +The Claude Messages API supports setting system prompts through the `system` field, which is used to define the model's behavior, role, and context. ### Python Example + ```python import requests @@ -153,7 +156,7 @@ By setting the `system` prompt, you can precisely control Claude's role and beha ## Streaming Responses -This interface also supports streaming responses. Set the `stream` parameter to `true` to receive results incrementally, which is highly suitable for implementing word-by-word display on web pages. +This API also supports streaming responses. Set the `stream` parameter to `true` to obtain progressively returned results, which is highly suitable for implementing word-by-word display on web pages. ### Python Example @@ -185,12 +188,12 @@ for line in response.iter_lines(): Streaming responses are returned in Server-Sent Events (SSE) format, with each line prefixed by `event:` and `data:`. Streaming event types include: -- `message_start`: The message begins, containing the message's basic information and model name. -- `content_block_start`: A content block begins. -- `content_block_delta`: An incremental update to a content block, containing newly generated text fragments. -- `content_block_stop`: A content block ends. -- `message_delta`: A message-level incremental update, containing `stop_reason` and final `usage` information. The authoritative value of `output_tokens_details.thinking_tokens` should only be read from the final `message_delta.usage`; do not accumulate it across events. -- `message_stop`: The message ends. +- `message_start`: Message start, containing basic message information and the model name. +- `content_block_start`: Content block start. +- `content_block_delta`: Incremental content block update, containing newly generated text fragments. +- `content_block_stop`: Content block end. +- `message_delta`: Message-level incremental update, containing `stop_reason` and final `usage` information. The authoritative value of `output_tokens_details.thinking_tokens` should only be read from the final `message_delta.usage`; do not accumulate it across events. +- `message_stop`: Message end. The output is as follows: @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -As you can see, the `content_block_delta` events in streaming responses contain progressively generated text content. By concatenating all `text_delta` values, you can obtain the complete reply. +It can be seen that the `content_block_delta` events in streaming responses contain progressively generated text content, and the complete reply can be obtained by concatenating all `text_delta` values. ### JavaScript Example @@ -253,7 +256,7 @@ while (true) { ## Multi-turn Conversations -If you want to integrate multi-turn conversation functionality, you need to alternate messages with the `user` and `assistant` roles in the `messages` array and pass in the previous conversation history together. +If you want to integrate multi-turn conversation functionality, you need to alternately arrange messages with the `user` and `assistant` roles in the `messages` array, and pass in the previous conversation history together. ### Python Example @@ -283,7 +286,6 @@ print(response.json()) ``` The returned result is as follows: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ The returned result is as follows: } ``` -By passing the complete conversation history in `messages`, Claude can provide accurate answers based on the context. +By passing the complete conversation history in `messages`, Claude can provide accurate responses based on the context. -## Extended Thinking Models +## Thinking Models Claude's thinking and thinking summary are two different concepts: the model can perform internal reasoning, but the API does not return the original chain of thought. When the reasoning process needs to be displayed, the API returns a processed summary. -Current models are recommended to use adaptive thinking, and control the overall reasoning effort through `output_config.effort`: +Current models are recommended to use adaptive thinking, with overall reasoning effort controlled through `output_config.effort`: ```python import requests @@ -341,7 +343,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -The thinking block in the response takes the following form: +The thinking block in the response looks like: ```json { @@ -350,26 +352,27 @@ The thinking block in the response takes the following form: "signature": "opaque-signature" } ``` + - `display: "summarized"` returns a readable thinking summary; it is not the original chain of thought. -- `display: "omitted"` returns `thinking: ""`, but still retains the opaque `signature` to support subsequent conversations. -- `display: "updates"` is Anthropic's beta mode and requires `anthropic-beta: thinking-display-updates-2026-08-18`. The official definition is to hide the reasoning content and display brief progress updates between tool calls. The platform passes this parameter and beta request header as-is and does not forcibly rewrite it to `summarized`; the actual output content depends on the selected model's support. +- `display: "omitted"` returns `thinking: ""`, while retaining the opaque `signature` to support subsequent conversations. +- `display: "updates"` is Anthropic's beta mode and requires `anthropic-beta: thinking-display-updates-2026-08-18`. The official definition is to hide the reasoning body and display brief progress updates between tool calls. The platform passes this parameter and the beta request header through as-is, and does not forcibly rewrite it to `summarized`; the actual output content depends on support from the selected model. - `thinking`, `output_config`, effort, sampling parameters, and newly added extension fields are passed through as-is. The platform does not maintain hardcoded value enumerations or combination restrictions by model, nor does it automatically rewrite thinking modes; whether these parameters are accepted is determined by the selected model, and parameter errors returned by the model are passed back to the client. -- The default value of display for Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8, and Opus 4.7 is `omitted`; Opus 4.6, Sonnet 4.6, and earlier models that support thinking use `summarized` by default. -- Display only affects the returned content and streaming latency, does not disable reasoning, and does not reduce thinking token billing. -- Whether thinking is enabled by default and the default value of display are two separate issues. Opus 5 and Sonnet 5 enable adaptive thinking by default; for Opus 5, omitting `thinking` is equivalent to adaptive, and omitting `output_config.effort` is equivalent to `high`. Opus 4.8, 4.7, and 4.6 require explicit enabling. -- Thinking and the final response body share the same `max_tokens` output budget. When the budget is too small, thinking may consume most of the quota, causing the response body to be empty or truncated; please increase `max_tokens`, or use `low` / `medium` effort to control reasoning investment. -- For models that allow disabling thinking, you can pass `thinking: {"type":"disabled"}`. New modes such as `between_tools` and effort combinations depend on the selected model; the platform does not preemptively reject based on old model rules. +- The default display value for Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8, and Opus 4.7 is `omitted`; Opus 4.6, Sonnet 4.6, and earlier models that support thinking use `summarized` by default. +- Display only affects returned content and streaming latency; it does not disable reasoning or reduce billing for thinking tokens. +- Whether thinking is enabled by default and the default display value are two independent issues. Opus 5 and Sonnet 5 enable adaptive thinking by default; for Opus 5, omitting `thinking` is equivalent to adaptive, and omitting `output_config.effort` is equivalent to `high`. Opus 4.8, 4.7, and 4.6 require explicit enabling. +- Thinking and the final body jointly consume the `max_tokens` output budget. When the budget is too small, thinking may consume most of the quota, causing the body to be empty or truncated; increase `max_tokens`, or use `low` / `medium` effort to control reasoning investment. +- For models that allow thinking to be disabled, you can pass `thinking: {"type":"disabled"}`. New modes such as `between_tools` and effort combinations depend on the selected model; the platform does not reject them in advance based on old model rules. - A fixed thinking budget can be passed through `budget_tokens`; new models typically use `thinking.type=adaptive` and `output_config.effort`. Whether fixed budgets or disabling thinking are supported depends on the current capabilities of the selected model. -- During multi-turn conversations and tool calls, the complete thinking block and signature returned by the assistant should be passed back unchanged; do not modify or generate signatures yourself. -- Parameter pass-through does not mean every model supports all features. Cross-protocol calls still require conversion; support scope and errors for content such as `redacted_thinking` are determined by the actual model service processing the request. +- During multi-turn conversations and tool calls, the complete thinking block and signature returned by the assistant should be passed back as-is; do not modify or generate the signature yourself. +- Parameter pass-through does not mean that every model supports all features. Cross-protocol calls still require conversion, and the support scope and errors for content such as `redacted_thinking` are determined by the model service that actually processes the request. -In streaming requests, `summarized` produces `thinking_delta`; `omitted` does not produce `thinking_delta`, and only retains the thinking block lifecycle and `signature_delta`. +In streaming requests, `summarized` produces `thinking_delta`; `omitted` does not produce `thinking_delta`, retaining only the thinking block lifecycle and `signature_delta`. ## Vision Models -Claude supports multimodal input and can process text and images simultaneously. In the Messages API, visual capabilities can be used by setting `content` as an array format and passing in image content blocks. +Claude supports multimodal input and can process text and images simultaneously. In the Messages API, vision capabilities can be used by setting `content` to an array format and passing image content blocks. -### Using Base64 Encoded Images +### Using Base64-Encoded Images ```python import base64 @@ -456,7 +459,6 @@ print(response.json()) ``` ### cURL Example - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -486,11 +488,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Supported image formats include: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Supported image formats include: `image/jpeg`, `image/png`, `image/gif`, and `image/webp`. ## Documents and PDFs -PDF uses the `document` content block and supports two stable sources: Base64 and URL. Base64 sources must use `application/pdf`: +PDFs use the `document` content block and support two stable sources: Base64 and URL. A Base64 source must use `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -URL sources are written as `{"type":"url","url":"https://example.com/report.pdf"}`. `document` also supports `text/plain` and `content` sources composed of text/image blocks; optional fields include `title`, `context`, and `citations`. The `file_id` source of the Files API belongs to a separate beta feature and is not within the stable contract of this interface. +A URL source is written as `{"type":"url","url":"https://example.com/report.pdf"}`. `document` also supports `text/plain` and `content` sources composed of text/image blocks; optional fields include `title`, `context`, and `citations`. The Files API `file_id` source is an independent beta feature and is not part of the stable contract of this API. ## Prompt Caching -The top-level `cache_control` automatically places the cache breakpoint on the last cacheable block: +Top-level `cache_control` automatically places the cache breakpoint on the last cacheable block: ```python payload = { @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -When precise position control is required, you can also write the same `cache_control` on text, image, document, `tool_use`, `tool_result` content blocks, or tool definitions. `ttl` supports `5m` (default) and `1h`; please determine cache writes and hits through `usage.cache_creation_input_tokens` and `usage.cache_read_input_tokens`. -When the response provides `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. If `cache_creation` is `null` or omitted, it means there is only the total amount of cache writes and no authoritative TTL breakdown; in this case, do not treat either bucket as a known 0. Billing and totals should still be based on the aggregate fields. +When precise position control is needed, the same `cache_control` can also be written on text, image, document, `tool_use`, `tool_result` content blocks, or tool definitions. `ttl` supports `5m` (default) and `1h`; use `usage.cache_creation_input_tokens` and `usage.cache_read_input_tokens` to determine cache writes and hits. + +When the response provides `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. If `cache_creation` is `null` or omitted, it means there is only the total amount of cache writes and no authoritative TTL breakdown; in this case, do not treat either bucket as a known 0, and billing and totals should still be based on the aggregate field. -Example return result: +Example response: ```json { @@ -563,7 +566,7 @@ Example return result: ## Tool Use -Claude Messages API natively supports tool calling functionality, allowing the model to call tools/functions you have predefined when needed. +The Claude Messages API natively supports tool use functionality, allowing the model to call your predefined tools/functions when needed. ### Python Example @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -When the model decides to call a tool, the returned result's `content` will contain content blocks of type `tool_use`: +When the model decides to call a tool, `content` in the response will include a content block of type `tool_use`: ```json { @@ -685,33 +688,32 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -The model will generate the final natural language response based on the results returned by the tool. +The model will generate the final natural-language response based on the result returned by the tool. -## Differences from Chat Completion API +## Differences from the Chat Completion API -Ace Data Cloud provides two Claude API formats at the same time. The main differences between them are as follows: +Ace Data Cloud provides two Claude API formats simultaneously. Their main differences are as follows: -Messages API's `usage.input_tokens` only represents uncached input. `cache_read_input_tokens` and `cache_creation_input_tokens` are independently billed buckets; the three are calculated separately according to their corresponding prices. - -| Feature | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +For the Messages API, `usage.input_tokens` only represents uncached input, while `cache_read_input_tokens` and `cache_creation_input_tokens` are independently billed buckets; all three are calculated separately according to their respective prices. +| Feature | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Format | Anthropic native format | OpenAI-compatible format | -| System prompt | Separate `system` field | Passed through `role: "system"` in `messages` | -| Response structure | `content` array (supports multiple types) | `choices` array (containing `message`) | -| Streaming format | SSE events (multiple event types) | SSE `data` lines | -| Deep thinking | Native `thinking` and `output_config.effort` | Model default strategy and compatibility parameters | -| Tool calling | Native `tools` + `input_schema` | OpenAI-compatible `tools` format | +| Format | Anthropic native format | OpenAI-compatible format | +| System prompt | Separate `system` field | Passed through `role: "system"` in `messages` | +| Response structure | `content` array (supports multiple types) | `choices` array (contains `message`) | +| Streaming format | SSE events (multiple event types) | SSE `data` lines | +| Extended thinking | Native `thinking` and `output_config.effort` | Model default strategy and compatible parameters | +| Tool calling | Native `tools` + `input_schema` | OpenAI-compatible `tools` format | | Token statistics | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -If your system has already integrated with an OpenAI-format API, you can use the Chat Completion API for seamless switching. If you need to use all of Claude's native capabilities, it is recommended to use the Messages API. +If your system has already integrated with the OpenAI-format API, you can use the Chat Completion API to switch seamlessly. If you need to use all of Claude's native capabilities, it is recommended to use the Messages API. ## Error Handling -The error responses of the public interface use the Ace Data Cloud platform envelope: `error.code` is the stable error code, `error.message` is the description, and `trace_id` is used for troubleshooting requests. Common HTTP statuses include: +Error responses from public APIs use the Ace Data Cloud platform envelope: `error.code` is the stable error code, `error.message` is the description, and `trace_id` is used for request troubleshooting. Common HTTP statuses include: -- `400`: Invalid request parameters or protocol content. -- `401`: Invalid, missing, or expired authorization token. -- `403`: Access forbidden, insufficient balance, or quota restrictions. +- `400`: Request parameters or protocol content are invalid. +- `401`: Authorization token is invalid, missing, or expired. +- `403`: Access is forbidden, balance is insufficient, or quota is restricted. - `404`: API or model does not exist. - `413`: Request body is too large. - `429`: Too many requests. @@ -729,7 +731,8 @@ The error responses of the public interface use the Ace Data Cloud platform enve } ``` -This error structure is Ace Data Cloud's runtime contract and is not equivalent to Anthropic's official error envelope; please handle it according to the HTTP status and `error.code`. +This error structure is the runtime contract of Ace Data Cloud and is not equivalent to Anthropic's official error envelope; please handle it according to the HTTP status and `error.code`. ## Conclusion -Through this document, you have learned how to use the Claude Messages API to invoke Claude's conversational capabilities in Anthropic's native format. The Messages API supports rich features such as basic conversations, system prompts, streaming responses, multi-turn conversations, extended thinking, vision understanding, PDFs, prompt caching, and tool use. If you have any questions, please feel free to contact our technical support team. + +Through this document, you have learned how to use the Claude Messages API to call Claude's conversational capabilities in Anthropic's native format. The Messages API supports rich features such as basic conversations, system prompts, streaming responses, multi-turn conversations, extended thinking, vision understanding, PDFs, prompt caching, and tool calling. If you have any questions, please feel free to contact our technical support team. diff --git a/en/guides/openai/openai_embeddings.mdx b/en/guides/openai/openai_embeddings.mdx index 0465a3dbb..f46ce8821 100644 --- a/en/guides/openai/openai_embeddings.mdx +++ b/en/guides/openai/openai_embeddings.mdx @@ -3,40 +3,40 @@ title: "OpenAI Embeddings API Application and Usage" description: "OpenAI generation integration guide - Ace Data Cloud" --- -OpenAI word vector service, used to generate word vector results that represent the input text. +The OpenAI embedding service is used to generate embedding results representing input text. -This document mainly introduces the usage process of the OpenAI Embeddings API, which allows us to create embedding vectors that represent the input text. +This document mainly introduces the usage process of OpenAI Embeddings API operations. With it, we can create embedding vectors representing input text. ## Application Process -To use the OpenAI Embeddings API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. +To use the OpenAI Embeddings API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token and keep it as a backup. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page. +If you have not yet logged in or registered, you will be automatically redirected to the login page, where you will be invited to register and log in. After completion, you will automatically return to the current page. -**One API Token can call all services on the platform, no need to apply separately for each service.** The first application will grant a free quota for a free experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). +**One API Token can be used to call all services on the platform; there is no need to apply separately for each service.** Your first application includes free credits for a free trial; when credits are insufficient, you can recharge your general balance in the [Console](https://platform.acedata.cloud/console/coin). -> 📘 Complete documentation: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) +> 📘 Full documentation: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) ## Basic Usage -Next, you can fill in the corresponding content on the interface, as shown in the figure: +Next, you can fill in the corresponding content in the interface, as shown in the image:

-When using this interface for the first time, we need to fill in at least three pieces of content: one is `authorization`, which can be selected directly from the dropdown list. The other parameter is `model`, which is the model category we choose to use from the OpenAI official website; here we mainly have 3 types of models, details can be found in the models we provide. The last parameter is `input`, which is the text we need to convert into a word vector. +When using this API for the first time, we need to fill in at least three items. One is `authorization`, which can be selected directly from the dropdown list. Another parameter is `model`; `model` is the OpenAI official model type we choose to use. The currently available models are `text-embedding-3-small` and `text-embedding-3-large`. `text-embedding-ada-002` is no longer available; if an existing vector index uses this old model, its vectors cannot be directly mixed with vectors from the new models, and the index needs to be rebuilt. The last parameter is `input`; `input` is the text for which we need to convert into embeddings. -You may also notice that there is corresponding code generation on the right side; you can copy the code to run directly or click the "Try" button for testing. +At the same time, you can notice that there is corresponding generated invocation code on the right. You can copy the code and run it directly, or directly click the "Try" button for testing. Optional parameters: -- `dimensions`: Crop vector dimensions, default output is the full dimension. -- `encoding_format`: Return format, optional `float` or `base64`. +- `dimensions`: Trims the vector dimensions; the full dimensions are output by default. +- `encoding_format`: Return format, either `float` or `base64`.

-Python sample call code: +Python sample invocation code: ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -After the call, we find that the returned result is as follows: +After the invocation, we find that the returned result is as follows: ```json { @@ -97,7 +97,7 @@ After the call, we find that the returned result is as follows: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -107,15 +107,15 @@ After the call, we find that the returned result is as follows: The returned result contains multiple fields, described as follows: -- `model`, the model used for this text-to-word vector conversion. -- `usage`, the token information used for this text-to-word vector conversion. -- `data`, the word vector result after text conversion. +- `model`, the model used for this text-to-embedding conversion. +- `usage`, the token information used for this text-to-embedding conversion. +- `data`, the embedding result after text conversion. -Among them, `data` contains the specific information of the word vector corresponding to the text, and the `embedding` inside it is the specific result of the generated word vector. +Among them, `data` contains the specific information about the embedding corresponding to the text, and its `embedding` is the specific generated embedding result. ## Error Handling -When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: +When calling the API, if an error occurs, the API will return the corresponding error code and information. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. @@ -138,4 +138,4 @@ When calling the API, if an error occurs, the API will return the corresponding ## Conclusion -Through this document, you have learned how to easily use the official OpenAI word vector generation function with the OpenAI Embeddings API. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team. +Through this document, you have learned how to easily use the official OpenAI embedding generation functionality through the OpenAI Embeddings API. We hope this document helps you better integrate and use this API. If you have any questions, please feel free to contact our technical support team. diff --git a/en/guides/platform/wework_bot.mdx b/en/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..a3ee7412f --- /dev/null +++ b/en/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "WeCom Bot" +description: "Platform integration guide - Ace Data Cloud" +--- + +Deploy your own WeCom account instance, use mobile WeCom to scan and log in, and read the account, contacts, conversations, and locally synchronized messages through REST API or MCP. Instances correspond to ordinary WeCom accounts, with no need for a private server or enterprise email domain configuration. + +Currently Alpha. Account reading has completed real conversation verification; self text sending and event readback have completed real acceptance; other contacts, group operations, and new instance recovery still need deployment environment acceptance. Media sending, quoted replies, real @ mentions, group member management, and delivery receipts are not yet available. Please refer to the value returned by the instance `/api/capabilities`. + +## Deployment and Login + +Enable the service under the Deployment category and select an instance duration plan. After deployment, open the management page and use the account owner's WeCom to scan and log in; if mobile confirmation or other login steps are required, open the remote desktop and enter the desktop password of that instance. API credentials and desktop passwords are independent. Login data is saved on the instance disk; rebuilding the container retains the disk; deleting the disk deletes the local session. + +Each instance is billed independently and runs according to the purchased duration. REST / MCP calls are not additionally billed per message; actual pricing is subject to the plan page. The current default reference is the duration plan for WeChat bots; pricing confirmation still needs to be completed based on runtime resources before final availability. + +## API and MCP + +Use the instance API address in the management page, and carry `Authorization: Bearer ` for all account interfaces. These paths belong to dedicated instances, not a shared API gateway. The MCP address is the instance address plus `/mcp/`, using the same Bearer token. + +| Interface | Function | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`, `GET /api/auth/status` | Whether the account is ready and the capability list | +| `GET /api/auth/qr` | Current login QR code PNG Base64 | +| `GET /api/account` | Current account | +| `GET /api/contacts?kind=all` | Internal colleagues and external contacts; internal / external can be specified | +| `GET /api/conversations` | Local conversations, retaining original conversation IDs | +| `GET /api/messages` | Locally synchronized messages; conversation_id, after_rowid, limit parameters | +| `POST /api/search` | Contacts, conversations, and local text search | +| `POST /api/messages` | Asynchronous text sending task; Idempotency-Key must be provided | +| `POST /api/messages/send` | Same sending endpoint, supporting one or multiple targets | +| `GET /api/groups/{conversation_id}` | Locally synchronized group information and members | +| `GET /api/tasks` | Recent tasks and the result of each target | +| `GET /api/tasks/{id}` | Query sending results | +| `POST /api/tasks/{id}/cancel` | Cancel tasks that have not yet started | +| `POST /api/runtime/pause`, `POST /api/runtime/resume` | Pause automation; resume after owner verification | +| `GET /api/diagnostics`, `GET /api/diagnostics/screenshot` | Instance status and current screen, both require authentication | +| `GET /api/events?after=0` | Message events with resumable cursors | +| `WS /ws` | Message event stream, Bearer authentication | + +The sending body contains `target`, `type: "text"`, and `text`. `target` accepts a conversation ID, contact ID, enterprise user ID, or unique full name; IDs are preferred; when display names still cannot uniquely identify an object, the instance will reject the operation and will not guess the target. Contacts without local conversations will first have a conversation opened through the client, and the message will be sent after verifying the actual conversation ID. The request header `Idempotency-Key` consists of 8–128 letters, numbers, or `_.:-`. Repeated requests for the same operation must reuse the same key and the same request body. + +Replacing `target` with a `targets` array can send serially to 1–50 explicitly specified targets. The two cannot be provided at the same time. All targets complete identity resolution first, and different aliases pointing to the same object will be rejected. Subsequent sending stops after one target fails, and task results record `succeeded`, `failed`, `unknown`, or `not_attempted` item by item; do not treat partial success as complete success. This process also needs to complete real acceptance for specified contacts in the deployment environment. + +Tasks may be in queued, running, submitting, succeeded, failed, unknown, or cancelled states. `succeeded` means that, after submission, the exact text and server message ID were found in the corresponding conversation record; `delivered` remains null and does not mean the other party has received it. unknown means the result is unclear; please check the history record and do not resend with a new key. The instance will not automatically retry interrupted tasks. + +History only includes content already synchronized by the client and cannot guarantee the complete history. Non-text messages may return an unknown type, and attachment downloads are not yet available. Events retain the most recent 10,000 entries; `gap` means the cursor has exceeded the retention window. The first connection will not replay old history as new messages. + +`server_accepted` and `server_id` in message history can be used to verify whether the server has accepted a local message; when only a local record appears without a server ID, sending cannot be considered successful. These fields do not mean the recipient has received or read it. Event records retain the status at the time of generation; use the message history interface to query the current confirmation status. + +## Accounts and Credentials + +Only log in to accounts that you are authorized to operate. Configure the API token in trusted applications; it can access the account data of that instance. Do not publish passwords, QR codes, or chat screenshots in public locations. Pausing an instance will interrupt real-time events. After the account logs out or the device is removed on mobile, you need to log in again. + +Current text input supports only a single line; line breaks will be explicitly rejected before sending. When the client requires security verification or re-login, it should be completed by the account owner in the remote desktop; the instance will not bypass verification. Tasks after verification interruption may return unknown; query message records first, and do not resend with a new idempotency key. + +After detecting a security verification prompt, account logout, or change, the automation queue will be persistently paused. After completing mobile verification, you can continue tasks not yet executed through “Resume After Verification” in the instance console; tasks that have already been submitted but have uncertain results will not be resent. Normal remote work may also trigger WeCom security verification. The officially stated 24-hour window after verification during which it will not be locked again does not mean detection has been eliminated, nor does it mean the instance can guarantee long-term unattended operation. diff --git a/es/guides/claude/claude_messages.mdx b/es/guides/claude/claude_messages.mdx index cc172a093..92169995b 100644 --- a/es/guides/claude/claude_messages.mdx +++ b/es/guides/claude/claude_messages.mdx @@ -3,19 +3,19 @@ title: "Solicitud y uso de Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude es un sistema de conversación de IA muy potente; basta con introducir un prompt para generar respuestas fluidas y naturales en solo unos segundos. Claude Messages API es el formato de API nativo oficial de Anthropic. A diferencia del formato compatible con OpenAI (Chat Completion), adopta la propia estructura de solicitudes y respuestas de Anthropic, lo que permite aprovechar mejor las capacidades únicas de Claude, como la entrada de contenido multimodal, la llamada de herramientas, el pensamiento profundo (Extended Thinking) y otras características avanzadas. +Anthropic Claude es un sistema de conversación de IA muy potente; basta con introducir un prompt para generar respuestas fluidas y naturales en solo unos segundos. Claude Messages API es el formato de API nativo oficial de Anthropic; a diferencia del formato compatible con OpenAI (Chat Completion), adopta la estructura propia de solicitudes y respuestas de Anthropic, lo que permite aprovechar mejor las capacidades únicas de Claude, como la entrada de contenido multimodal, la llamada de herramientas, el pensamiento profundo (Extended Thinking) y otras funciones avanzadas. Este documento presenta principalmente el proceso de uso de las operaciones de Claude Messages API. Con ella, podemos utilizar una interfaz nativa coherente con la oficial de Anthropic para invocar la función de conversación de Claude. ## Proceso de solicitud -Para utilizar Claude Messages API, primero ve a la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu API Token y guárdalo para usarlo posteriormente. +Para utilizar Claude Messages API, primero obtenga su API Token en la [Consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo como respaldo. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Si aún no has iniciado sesión o te has registrado, se te redirigirá automáticamente a la página de inicio de sesión para invitarte a registrarte e iniciar sesión; al finalizar, volverás automáticamente a la página actual. +Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual. -**Un único API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye crédito gratuito, que permite una experiencia gratuita; cuando el crédito sea insuficiente, puedes recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin). +**Un único API Token permite invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye crédito gratuito para una experiencia sin coste; cuando el crédito sea insuficiente, puede recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin). > 📘 Documentación completa: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) @@ -23,21 +23,22 @@ Si aún no has iniciado sesión o te has registrado, se te redirigirá automáti La ruta de solicitud de Claude Messages API es `/v1/messages`, coherente con la API oficial de Anthropic. Debemos proporcionar al menos tres parámetros obligatorios: -- `model`: selecciona el modelo Claude que se utilizará. `claude-opus-5-5` se proporciona únicamente a través de Messages API, admite un contexto de 1 millón de Token, una salida máxima de 128K Token y siempre activa el pensamiento adaptativo. El último modelo insignia es `claude-fable-5-1` (contexto de 1 millón de Token, salida máxima de 128K Token); el anterior `claude-fable-5` sigue siendo compatible y se conserva. `claude-sonnet-5-5` se ha incorporado a la interfaz de la serie nativa Messages, admite entrada de imágenes y pensamiento adaptativo; sus precios oficiales de referencia para entrada, salida y lectura de caché son respectivamente 2, 10 y 0,20 dólares por millón de Token. +- `model`: selecciona el modelo Claude que se utilizará. `claude-opus-5-5` solo se proporciona a través de Messages API, admite un contexto de 1 millón de Token, una salida máxima de 128K Token y siempre activa el pensamiento adaptativo. El último modelo insignia es `claude-fable-5-1` (contexto de 1 millón de Token, salida máxima de 128K Token); el anterior `claude-fable-5` sigue siendo compatible y se mantiene. `claude-sonnet-5-5` se ha incorporado a la interfaz de la serie nativa Messages, admite entrada de imágenes y pensamiento adaptativo; sus precios de referencia oficiales para entrada, salida y lectura de caché son respectivamente 2, 10 y 0,20 dólares por millón de Token. - `messages`: el arreglo de mensajes de entrada; cada mensaje contiene `role` (rol) y `content` (contenido), donde `role` admite `user` y `assistant`. -- `max_tokens`: el número máximo de tokens de salida, utilizado para limitar la longitud de una sola respuesta. +- `max_tokens`: el número máximo de token de salida, utilizado para limitar la longitud de una sola respuesta. -Parámetros opcionales comunes: +Parámetros opcionales de uso común: - `system`: prompt del sistema, utilizado para establecer el comportamiento y el rol del modelo. -- `temperature`: aleatoriedad de la generación, entre 0 y 1; cuanto mayor sea el valor, más dispersa será la respuesta. -- `stream`: si se utiliza respuesta en streaming; establecerlo en `true` permite lograr un efecto de retorno palabra por palabra. +- `temperature`: aleatoriedad de generación, entre 0 y 1; cuanto mayor sea el valor, más dispersa será la respuesta. +- `stream`: si se utiliza respuesta en streaming; establecerlo en `true` permite lograr un efecto de devolución carácter por carácter. - `stop_sequences`: secuencias de detención personalizadas; el modelo dejará de generar cuando encuentre estos textos. -- `top_p`: parámetro de muestreo de núcleo, que controla la aleatoriedad de la generación junto con temperature. -- `top_k`: muestrea únicamente entre las K opciones con mayor probabilidad. -- `tools`: definición de herramientas, utilizada para permitir que el modelo llame a funciones externas. +- `top_p`: parámetro de muestreo nuclear, que controla la aleatoriedad de la generación junto con temperature. +- `top_k`: solo realiza muestreo entre las K opciones con mayor probabilidad. +- `tools`: definición de herramientas, utilizada para permitir que el modelo invoque funciones externas. - `tool_choice`: controla cómo utiliza el modelo las herramientas proporcionadas. -- `cache_control`: crea automáticamente un punto de interrupción de caché en el último bloque de contenido almacenable en caché de la solicitud; también puede escribirse en un bloque de contenido específico. +- `cache_control`: crea automáticamente un punto de interrupción de caché en el último bloque de contenido almacenable en caché de la solicitud; también puede escribirse en bloques de contenido específicos. +- `metadata`: objeto opcional de metadatos de solicitud. `metadata.user_id` es una cadena de texto que puede transmitir un identificador de usuario personalizado por el llamador, por ejemplo `{"user_id":"example-user-001"}`; se recomienda utilizar un identificador estable que no contenga información personal. No sustituye la autenticación `Authorization` ni necesita escribirse en el contenido de la conversación de `messages`. ### Ejemplo de cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -107,24 +110,24 @@ Después de la llamada, el resultado devuelto es el siguiente: ``` Descripción de los campos del resultado devuelto: - -- `id`: identificador único de este mensaje. +- `id`: el identificador único de este mensaje. - `type`: siempre es `message`. - `role`: siempre es `assistant`. -- `content`: arreglo del contenido de la respuesta; cada elemento contiene `type` (como `text`) y el contenido correspondiente. -- `model`: nombre del modelo que procesa la solicitud. -- `stop_reason`: motivo de detención. Los valores estables incluyen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (puede devolverse el contenido actual de assistant sin cambios para continuar), `refusal` y `model_context_window_exceeded`. +- `content`: un arreglo de contenido de respuesta, donde cada elemento contiene `type` (como `text`) y el contenido correspondiente. +- `model`: el nombre del modelo que procesa la solicitud. +- `stop_reason`: el motivo de detención. Los valores estables incluyen `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (puede devolver sin cambios el contenido actual de `assistant` para continuar), `refusal` y `model_context_window_exceeded`. - `stop_sequence`: si se detiene debido a una secuencia de detención personalizada, muestra el texto de la secuencia de detención coincidente. -- `stop_details`: cuando `stop_reason` es `refusal`, puede contener la categoría y la explicación del rechazo. -- `usage`: estadísticas de uso de tokens. `input_tokens` es la entrada no almacenada en caché; `cache_creation_input_tokens` y `cache_read_input_tokens` son respectivamente la escritura y lectura de caché; `output_tokens` es el número total de tokens de salida. Si se devuelve `output_tokens_details.thinking_tokens`, este valor es un subconjunto de `output_tokens`; no lo sumes nuevamente al calcular el total o el costo. Este detalle puede ser `null` u omitirse cuando no hay un conteo autorizado. -- `usage.cache_creation`: detalle opcional de TTL de escritura de caché, que contiene `ephemeral_5m_input_tokens` y `ephemeral_1h_input_tokens`. Cuando el objeto existe, la suma de ambos equivale a `cache_creation_input_tokens`; que el campo sea `null` u omitido indica que la respuesta actual no tiene una descomposición de TTL disponible y no puede interpretarse como `0`. -- `usage.cost`: las respuestas no en streaming pueden contener un objeto de consumo de crédito registrado por Ace Data Cloud, donde `amount` es el consumo real de esta vez, `currency` es la unidad de medida y `list_amount` es el importe antes del descuento (si lo hubiera). El precio base oficial de lectura de caché de Fable 5.1 es $0.25/millón de Token, y los precios base de escritura de caché de 5 minutos y 1 hora son respectivamente $12.50 y $20/millón de Token; los precios reales de la plataforma se convierten según el descuento del plan. +- `stop_details`: cuando `stop_reason` es `refusal`, puede contener la categoría y la descripción del rechazo. +- `usage`: estadísticas de uso de tokens. `input_tokens` es la entrada no almacenada en caché; `cache_creation_input_tokens` y `cache_read_input_tokens` son, respectivamente, la escritura y la lectura de caché; `output_tokens` es el número total de tokens de salida. Si se devuelve `output_tokens_details.thinking_tokens`, este valor es un subconjunto de `output_tokens`; no lo sume nuevamente al calcular el total o el coste. Este detalle puede ser `null` u omitirse cuando no hay un recuento autorizado. +- `usage.cache_creation`: detalle opcional del TTL de escritura de caché, que contiene `ephemeral_5m_input_tokens` y `ephemeral_1h_input_tokens`. Cuando el objeto existe, la suma de ambos equivale a `cache_creation_input_tokens`; que los campos sean `null` u omitidos indica que la respuesta actual no tiene un desglose de TTL disponible y no debe interpretarse como `0`. +- `usage.cost`: las respuestas no transmitidas pueden contener un objeto de consumo de créditos registrado por Ace Data Cloud, donde `amount` es el consumo real de esta vez, `currency` es la unidad de medida y `list_amount` es el importe antes del descuento (si existe). El precio oficial base de lectura de caché de Fable 5.1 es de $0.25/millón de tokens, y los precios base de escritura de caché de 5 minutos y 1 hora son de $12.50 y $20/millón de tokens, respectivamente; el precio real de la plataforma se convierte según el descuento del plan. -## Prompt del sistema +## Mensaje del sistema -Claude Messages API admite establecer un prompt del sistema mediante el campo `system`, utilizado para definir el comportamiento, el rol y el contexto del modelo. +Claude Messages API admite establecer mensajes del sistema mediante el campo `system`, utilizados para definir el comportamiento, el rol y el contexto del modelo. ### Ejemplo de Python + ```python import requests @@ -149,13 +152,13 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Al configurar el prompt `system`, se puede controlar con precisión el rol y la forma de comportamiento de Claude. +Al configurar el mensaje de `system`, se puede controlar con precisión el rol y el comportamiento de Claude. ## Respuesta en streaming -Esta interfaz también admite respuestas en streaming; establezca el parámetro `stream` en `true` para obtener un efecto de retorno gradual, lo cual es muy adecuado para implementar la visualización carácter por carácter en páginas web. +Esta interfaz también admite respuestas en streaming; basta con establecer el parámetro `stream` en `true` para obtener un efecto de devolución progresiva, muy adecuado para implementar una visualización carácter por carácter en páginas web. -### Ejemplo en Python +### Ejemplo de Python ```python import requests @@ -183,14 +186,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -La respuesta en streaming se devuelve en formato Server-Sent Events (SSE), y cada línea lleva como prefijo `event:` y `data:`. Los tipos de eventos de streaming incluyen: +Las respuestas en streaming se devuelven en formato Server-Sent Events (SSE), y cada línea tiene los prefijos `event:` y `data:`. Los tipos de eventos de streaming incluyen: - `message_start`: inicio del mensaje, contiene la información básica del mensaje y el nombre del modelo. - `content_block_start`: inicio del bloque de contenido. - `content_block_delta`: actualización incremental del bloque de contenido, contiene el fragmento de texto recién generado. -- `content_block_stop`: finalización del bloque de contenido. -- `message_delta`: actualización incremental a nivel de mensaje, contiene la información de `stop_reason` y `usage` final. El valor autorizado de `output_tokens_details.thinking_tokens` solo debe leerse del último `message_delta.usage`; no debe acumularse entre eventos. -- `message_stop`: finalización del mensaje. +- `content_block_stop`: fin del bloque de contenido. +- `message_delta`: actualización incremental a nivel de mensaje, contiene `stop_reason` y la información final de `usage`. El valor autorizado de `output_tokens_details.thinking_tokens` solo debe leerse del último `message_delta.usage`; no debe acumularse entre eventos. +- `message_stop`: fin del mensaje. El efecto de salida es el siguiente: @@ -220,9 +223,9 @@ event: message_stop data: {"type":"message_stop"} ``` -Se puede ver que, en la respuesta en streaming, el evento `content_block_delta` contiene el contenido de texto generado gradualmente; al concatenar todos los `text_delta` se puede obtener la respuesta completa. +Se puede ver que, en las respuestas en streaming, el evento `content_block_delta` contiene el contenido de texto generado progresivamente; al concatenar todos los `text_delta` se puede obtener la respuesta completa. -### Ejemplo en JavaScript +### Ejemplo de JavaScript ```javascript const options = { @@ -251,11 +254,11 @@ while (true) { } ``` -## Conversación de múltiples turnos +## Conversaciones de múltiples turnos -Si desea integrar la función de conversación de múltiples turnos, debe alternar los mensajes con roles `user` y `assistant` en el array `messages`, e incluir conjuntamente el historial de conversación anterior. +Si desea integrar la función de conversación de múltiples turnos, debe organizar alternativamente los mensajes con los roles `user` y `assistant` en el arreglo `messages`, e incluir todo el historial de conversación anterior. -### Ejemplo en Python +### Ejemplo de Python ```python import requests @@ -283,7 +286,6 @@ print(response.json()) ``` El resultado devuelto es el siguiente: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ El resultado devuelto es el siguiente: } ``` -Al transmitir el historial completo de la conversación en `messages`, Claude puede dar respuestas precisas basándose en el contexto. +Al pasar el historial completo de la conversación en `messages`, Claude puede combinar el contexto para proporcionar respuestas precisas. ## Modelo de razonamiento profundo -El thinking y el thinking summary de Claude son dos conceptos diferentes: el modelo puede realizar razonamiento interno, pero la API no devolverá la cadena de pensamiento original. Cuando se necesita mostrar el proceso de razonamiento, la API devuelve un resumen procesado. +El thinking y el thinking summary de Claude son dos conceptos diferentes: el modelo puede realizar razonamiento interno, pero la API no devuelve la cadena de pensamiento original. Cuando se necesita mostrar el proceso de razonamiento, la API devuelve un resumen procesado. -Actualmente, se recomienda utilizar adaptive thinking con el modelo actual y controlar la inversión general de razonamiento mediante `output_config.effort`: +Actualmente, se recomienda que los modelos usen adaptive thinking y controlen la inversión total de razonamiento mediante `output_config.effort`: ```python import requests @@ -350,24 +352,25 @@ El bloque thinking en la respuesta tiene la siguiente forma: "signature": "opaque-signature" } ``` + - `display: "summarized"` devuelve un resumen de pensamiento legible; no es la cadena de pensamiento original. - `display: "omitted"` devuelve `thinking: ""`, pero aún conserva la `signature` opaca para admitir conversaciones posteriores. -- `display: "updates"` es el modo beta de Anthropic, y requiere incluir `anthropic-beta: thinking-display-updates-2026-08-18`. La definición oficial es ocultar el texto del razonamiento y mostrar breves actualizaciones de progreso entre llamadas a herramientas. La plataforma transmite este parámetro y el encabezado de solicitud beta según sus valores originales, y no los reescribe forzosamente como `summarized`; el contenido de salida real depende de la compatibilidad del modelo seleccionado. -- `thinking`, `output_config`, effort, los parámetros de muestreo y los nuevos campos de extensión se transmiten según sus valores originales. La plataforma no mantiene enumeraciones de valores ni restricciones de combinaciones codificadas por modelo, ni reescribe automáticamente el modo thinking; si el modelo seleccionado acepta estos parámetros lo determina el propio modelo, y los errores de parámetros devueltos por el modelo se retransmitirán al cliente. -- Los valores predeterminados de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 y Opus 4.7 son `omitted`; Opus 4.6, Sonnet 4.6 y los modelos anteriores que admiten thinking usan `summarized` de forma predeterminada. +- `display: "updates"` es el modo beta de Anthropic, y se debe incluir `anthropic-beta: thinking-display-updates-2026-08-18`. La definición oficial es ocultar el cuerpo del razonamiento y mostrar breves actualizaciones de progreso entre llamadas a herramientas. La plataforma transmite este parámetro y el encabezado de solicitud beta según sus valores originales, y no los reescribe forzosamente como `summarized`; el contenido de salida real depende de la compatibilidad del modelo seleccionado. +- `thinking`, `output_config`, effort, los parámetros de muestreo y los campos de extensión añadidos se transmiten según sus valores originales. La plataforma no mantiene enumeraciones de valores ni restricciones de combinación codificadas por modelo, y tampoco reescribe automáticamente el modo thinking; el modelo seleccionado determina si acepta estos parámetros, y los errores de parámetros devueltos por el modelo se transmitirán al cliente. +- El valor predeterminado de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 y Opus 4.7 es `omitted`; Opus 4.6, Sonnet 4.6 y los modelos anteriores que admiten thinking usan `summarized` de forma predeterminada. - Display solo afecta al contenido devuelto y a la latencia de streaming, no desactiva el razonamiento ni reduce la facturación de tokens de thinking. - Si thinking está habilitado de forma predeterminada y el valor predeterminado de display son dos cuestiones independientes. Opus 5 y Sonnet 5 habilitan adaptive thinking de forma predeterminada; para Opus 5, omitir `thinking` equivale a adaptive, y omitir `output_config.effort` equivale a `high`. Opus 4.8, 4.7 y 4.6 requieren habilitación explícita. -- Thinking y el texto final comparten el presupuesto de salida de `max_tokens`. Cuando el presupuesto es demasiado pequeño, thinking puede ocupar la mayor parte de la cuota, dejando el texto vacío o truncado; aumente `max_tokens`, o use effort `low` / `medium` para controlar la inversión en razonamiento. -- Para los modelos que permiten desactivar thinking, se puede pasar `thinking: {"type":"disabled"}`. Los nuevos modos como `between_tools` y las combinaciones de effort dependen del modelo seleccionado; la plataforma no rechaza anticipadamente según reglas antiguas de modelos. -- El presupuesto fijo de pensamiento se puede pasar mediante `budget_tokens`; los modelos nuevos normalmente usan `thinking.type=adaptive` y `output_config.effort`. Que se admita un presupuesto fijo o desactivar el pensamiento depende de las capacidades actuales del modelo seleccionado. -- En conversaciones de varias rondas y llamadas a herramientas, se deben devolver sin modificaciones los bloques completos de thinking y signature devueltos por assistant; no modifique ni genere por su cuenta signature. -- La transmisión de parámetros no significa que cada modelo admita todas las funciones. Las llamadas entre protocolos aún requieren conversión, y el alcance de compatibilidad y los errores de contenidos como `redacted_thinking` los determina el servicio del modelo que procesa realmente la solicitud. +- Thinking y el cuerpo final comparten el presupuesto de salida de `max_tokens`. Cuando el presupuesto es demasiado pequeño, thinking puede ocupar la mayor parte de la cuota, dejando el cuerpo vacío o truncado; aumente `max_tokens`, o use effort `low` / `medium` para controlar la inversión de razonamiento. +- Para los modelos que permiten desactivar thinking, se puede pasar `thinking: {"type":"disabled"}`. Los nuevos modos como `between_tools` y las combinaciones de effort dependen del modelo seleccionado; la plataforma no los rechaza anticipadamente basándose en reglas de modelos antiguas. +- El presupuesto de pensamiento fijo puede pasarse mediante `budget_tokens`; los modelos nuevos suelen usar `thinking.type=adaptive` y `output_config.effort`. Si se admite un presupuesto fijo o desactivar el pensamiento depende de las capacidades actuales del modelo seleccionado. +- En conversaciones de varias rondas y llamadas a herramientas, se debe devolver intacto el bloque thinking completo y la signature devueltos por assistant; no modifique ni genere por su cuenta la signature. +- La transmisión de parámetros no significa que todos los modelos admitan todas las funciones. Las llamadas entre protocolos aún requieren conversión, y el alcance de compatibilidad y los errores de contenido como `redacted_thinking` son determinados por el servicio del modelo que procesa realmente la solicitud. -En las solicitudes de streaming, `summarized` produce `thinking_delta`; `omitted` no produce `thinking_delta`, y solo conserva el ciclo de vida del bloque thinking y `signature_delta`. +En las solicitudes de streaming, `summarized` genera `thinking_delta`; `omitted` no genera `thinking_delta`, y solo conserva el ciclo de vida del bloque thinking y `signature_delta`. -## Modelos visuales +## Modelo visual -Claude admite entradas multimodales y puede procesar texto e imágenes al mismo tiempo. En la Messages API, las capacidades visuales se pueden utilizar estableciendo `content` en formato de matriz y pasando bloques de contenido de imagen. +Claude admite entradas multimodales y puede procesar texto e imágenes al mismo tiempo. En la API de Messages, las capacidades visuales se pueden utilizar estableciendo `content` en formato de matriz y pasando bloques de contenido de imagen. ### Usar imágenes codificadas en Base64 @@ -456,7 +459,6 @@ print(response.json()) ``` ### Ejemplo de cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -486,11 +488,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Los formatos de imagen admitidos incluyen: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Los formatos de imagen compatibles incluyen: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Documentos y PDF -Los PDF usan el bloque de contenido `document`, y admiten dos fuentes estables: Base64 y URL. Las fuentes Base64 deben usar `application/pdf`: +Los PDF utilizan el bloque de contenido `document`, compatible con dos fuentes estables: Base64 y URL. La fuente Base64 debe utilizar `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -La fuente URL se escribe como `{"type":"url","url":"https://example.com/report.pdf"}`. `document` también admite `text/plain` y fuentes `content` compuestas por bloques text/image; los campos opcionales incluyen `title`, `context` y `citations`. La fuente `file_id` de la Files API pertenece a una función beta independiente y no forma parte del contrato estable de esta interfaz. +La fuente URL se escribe como `{"type":"url","url":"https://example.com/report.pdf"}`. `document` también admite `text/plain` y fuentes `content` compuestas por bloques text/image; los campos opcionales incluyen `title`, `context` y `citations`. La fuente `file_id` de la API Files pertenece a una función beta independiente y no forma parte del contrato estable de esta interfaz. -## Caché de prompts +## Caché de indicaciones -El `cache_control` de nivel superior colocará automáticamente el punto de interrupción de caché en el último bloque almacenable en caché: +El `cache_control` de nivel superior coloca automáticamente el punto de interrupción de caché en el último bloque almacenable en caché: ```python payload = { @@ -534,9 +536,10 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Cuando se requiera un control preciso de la posición, también puede escribir el mismo `cache_control` en bloques de contenido text, image, document, tool_use, tool_result o en definiciones de herramientas. `ttl` admite `5m` (predeterminado) y `1h`; determine la escritura y los aciertos de caché mediante `usage.cache_creation_input_tokens` y `usage.cache_read_input_tokens`. -Cuando la respuesta proporciona `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` es `null` o se omite, indica que solo existe el total de escritura de caché y no un desglose autoritativo de TTL; en este caso, no considere ningún bucket como un 0 conocido, y la facturación y los totales seguirán basándose en el campo agregado. +Cuando se necesita un control preciso de la posición, también se puede escribir el mismo `cache_control` en bloques de contenido text, image, document, tool_use, tool_result o en definiciones de herramientas. `ttl` admite `5m` (predeterminado) y `1h`; utilice `usage.cache_creation_input_tokens` y `usage.cache_read_input_tokens` para determinar las escrituras y los aciertos de caché. + +Cuando la respuesta proporciona `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` es `null` u se omite, indica que solo hay un total de escrituras de caché, sin un desglose de TTL autorizado; en este caso, no trate ningún bucket como un 0 conocido, y la facturación y los totales seguirán basándose en el campo agregado. Ejemplo de resultado devuelto: @@ -561,9 +564,9 @@ Ejemplo de resultado devuelto: } ``` -## Llamada de herramientas (Tool Use) +## Llamada a herramientas (Tool Use) -La API de Claude Messages admite de forma nativa la funcionalidad de llamada de herramientas, permitiendo que el modelo invoque sus herramientas/funciones predefinidas cuando sea necesario. +La API de Claude Messages admite de forma nativa la función de llamada a herramientas, lo que permite que el modelo invoque sus herramientas/funciones predefinidas cuando sea necesario. ### Ejemplo en Python @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Cuando el modelo decide llamar a una herramienta, `content` en el resultado devuelto incluirá un bloque de contenido de tipo `tool_use`: +Cuando el modelo decide llamar a una herramienta, el resultado devuelto incluirá un bloque de contenido de tipo `tool_use` en `content`: ```json { @@ -637,7 +640,7 @@ Cuando el modelo decide llamar a una herramienta, `content` en el resultado devu } ``` -Tenga en cuenta que `stop_reason` es `tool_use`, lo que indica que el modelo necesita llamar a una herramienta. Después de recibir este resultado, debe ejecutar la función de herramienta y devolver el resultado al modelo en forma de `tool_result`: +Tenga en cuenta que `stop_reason` es `tool_use`, lo que indica que el modelo necesita llamar a una herramienta. Después de recibir este resultado, debe ejecutar la función de la herramienta y devolver el resultado al modelo en forma de `tool_result`: ```python payload = { @@ -685,37 +688,36 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -El modelo generará una respuesta final en lenguaje natural basándose en el resultado devuelto por la herramienta. - -## Diferencias con la API de Chat Completion +El modelo generará la respuesta final en lenguaje natural basándose en el resultado devuelto por la herramienta. -Ace Data Cloud proporciona simultáneamente dos formatos de API de Claude; las principales diferencias entre ambos son las siguientes: +## Diferencias con la API Chat Completion -`usage.input_tokens` de la API Messages solo representa la entrada no almacenada en caché; `cache_read_input_tokens` y `cache_creation_input_tokens` son buckets de facturación independientes; los tres se calcularán por separado según los precios correspondientes. +Ace Data Cloud proporciona simultáneamente dos formatos de API de Claude, cuyas principales diferencias son las siguientes: -| Característica | API Messages (`/v1/messages`) | API Chat Completion (`/v1/chat/completions`) | +`usage.input_tokens` de la API Messages solo representa la entrada no almacenada en caché; `cache_read_input_tokens` y `cache_creation_input_tokens` son buckets de facturación independientes; los tres se calcularán por separado según sus precios correspondientes. +| Característica | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Formato | Formato nativo de Anthropic | Formato compatible con OpenAI | | Prompt del sistema | Campo `system` independiente | Se transmite mediante `role: "system"` en `messages` | -| Estructura de respuesta | Matriz `content` (admite varios tipos) | Matriz `choices` (incluye `message`) | -| Streaming | Eventos SSE (varios tipos de eventos) | Líneas SSE `data` | -| Razonamiento profundo | `thinking` nativo y `output_config.effort` | Estrategia predeterminada del modelo y parámetros de compatibilidad | -| Llamada de herramientas | `tools` + `input_schema` nativos | Formato `tools` compatible con OpenAI | -| Estadísticas de tokens | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | +| Estructura de respuesta | Array `content` (admite múltiples tipos) | Array `choices` (contiene `message`) | +| Formato de streaming | Eventos SSE (múltiples tipos de eventos) | Líneas SSE `data` | +| Pensamiento profundo | `thinking` nativo y `output_config.effort` | Estrategia predeterminada del modelo y parámetros compatibles | +| Llamada a herramientas | `tools` nativo + `input_schema` | Formato `tools` compatible con OpenAI | +| Estadísticas de Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Si su sistema ya está integrado con una API en formato OpenAI, puede utilizar la API Chat Completion para realizar un cambio sin problemas. Si necesita utilizar todas las capacidades nativas de Claude, se recomienda utilizar la API Messages. +Si su sistema ya está integrado con una API en formato OpenAI, puede utilizar Chat Completion API para cambiar sin problemas. Si necesita utilizar todas las capacidades nativas de Claude, se recomienda utilizar Messages API. ## Manejo de errores Las respuestas de error de la interfaz pública utilizan el envelope de la plataforma Ace Data Cloud: `error.code` es un código de error estable, `error.message` es una descripción y `trace_id` se utiliza para investigar solicitudes. Los estados HTTP comunes incluyen: -- `400`: los parámetros de la solicitud o el contenido del protocolo no son válidos. -- `401`: el token de autorización no es válido, falta o ha expirado. -- `403`: acceso prohibido, saldo insuficiente o cuota restringida. -- `404`: la API o el modelo no existe. -- `413`: el cuerpo de la solicitud es demasiado grande. -- `429`: demasiadas solicitudes. -- `500` / `503` / `504`: error de servicio, indisponibilidad temporal o tiempo de procesamiento agotado. +- `400`: Los parámetros de la solicitud o el contenido del protocolo no son válidos. +- `401`: El token de autorización no es válido, falta o ha expirado. +- `403`: Acceso prohibido, saldo insuficiente o cuota restringida. +- `404`: La API o el modelo no existen. +- `413`: El cuerpo de la solicitud es demasiado grande. +- `429`: Demasiadas solicitudes. +- `500` / `503` / `504`: Error del servicio, no disponible temporalmente o tiempo de procesamiento agotado. ### Ejemplo de respuesta de error @@ -729,7 +731,8 @@ Las respuestas de error de la interfaz pública utilizan el envelope de la plata } ``` -Esta estructura de error es el contrato de tiempo de ejecución de Ace Data Cloud y no equivale al envelope de error oficial de Anthropic; procéselo según el estado HTTP y `error.code`. +Esta estructura de error es el contrato de tiempo de ejecución de Ace Data Cloud y no equivale al envelope de error oficial de Anthropic; procese según el estado HTTP y `error.code`. ## Conclusión -A través de este documento, ya ha aprendido cómo utilizar Claude Messages API para invocar las capacidades de conversación de Claude en el formato nativo de Anthropic. Messages API admite funciones enriquecidas como conversaciones básicas, mensajes del sistema, respuestas en streaming, conversaciones de múltiples turnos, pensamiento profundo, comprensión visual, PDF, caché de prompts y llamadas a herramientas. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico. + +A través de este documento, ya ha aprendido cómo utilizar Claude Messages API para invocar las funciones de conversación de Claude en el formato nativo de Anthropic. Messages API admite funciones enriquecidas como conversación básica, prompts del sistema, respuestas de streaming, conversaciones de múltiples turnos, pensamiento profundo, comprensión visual, PDF, caché de prompts y llamadas a herramientas. Si tiene alguna pregunta, no dude en contactar a nuestro equipo de soporte técnico. diff --git a/es/guides/openai/openai_embeddings.mdx b/es/guides/openai/openai_embeddings.mdx index 8030cfff8..c7f8a9e86 100644 --- a/es/guides/openai/openai_embeddings.mdx +++ b/es/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "Solicitud y uso de la API de Embeddings de OpenAI" +title: "Solicitud y uso de la API de OpenAI Embeddings" description: "OpenAI generation API guide - Ace Data Cloud" --- -El servicio de vectores de palabras de OpenAI se utiliza para generar resultados de vectores de palabras que representan el texto de entrada. +Servicio de vectores de palabras de OpenAI, utilizado para generar resultados de vectores de palabras que representan el texto de entrada. -Este documento describe principalmente el proceso de uso de la API de Embeddings de OpenAI, mediante el cual podemos crear vectores de incrustación que representan el texto de entrada. +Este documento presenta principalmente el proceso de uso de las operaciones de la API de OpenAI Embeddings; con ella podemos crear vectores de incrustación que representan el texto de entrada。。 ## Proceso de solicitud -Para utilizar la API de Embeddings de OpenAI, primero dirígete a [la consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu token de API, que debes guardar como respaldo. +Para usar la API de OpenAI Embeddings, primero obtenga su API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo como respaldo. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invita a registrarte e iniciar sesión; una vez completado, regresarás automáticamente a la página actual. +Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al finalizar, regresará automáticamente a la página actual. -**Un token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio.** La primera solicitud incluye un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en [la consola](https://platform.acedata.cloud/console/coin). +**Un API Token permite invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye crédito gratuito, que permite una experiencia gratuita; cuando el crédito sea insuficiente, puede recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin). -> 📘 Documentación completa: [API de Embeddings de OpenAI →](https://platform.acedata.cloud/documents/openai-embeddings) +> 📘 Documentación completa: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) ## Uso básico -A continuación, puedes completar el contenido correspondiente en la interfaz, como se muestra en la imagen: +A continuación, puede completar el contenido correspondiente en la interfaz, como se muestra en la imagen:

-En tu primera vez usando esta interfaz, necesitarás completar al menos tres campos: uno es `authorization`, que puedes seleccionar directamente en la lista desplegable. El otro parámetro es `model`, que es la categoría del modelo que elegimos usar de la página oficial de OpenAI; aquí tenemos principalmente 3 tipos de modelos, los detalles se pueden ver en los modelos que proporcionamos. El último parámetro es `input`, que es el texto que necesitamos convertir en un vector de palabras. +Al usar esta interfaz por primera vez, necesitamos completar al menos tres contenidos: uno es `authorization`, que puede seleccionarse directamente en la lista desplegable. Otro parámetro es `model`; `model` corresponde a la categoría de modelo del sitio web oficial de OpenAI que elegimos utilizar; los modelos actualmente disponibles son `text-embedding-3-small` y `text-embedding-3-large`. `text-embedding-ada-002` ha dejado de ofrecerse; si los índices vectoriales existentes utilizan este modelo antiguo, no pueden mezclar directamente los vectores de los nuevos modelos y es necesario reconstruir el índice. El último parámetro es `input`; `input` es el texto de vectores de palabras que necesitamos convertir. -También puedes notar que a la derecha hay un código de llamada correspondiente que se genera, puedes copiar el código y ejecutarlo directamente, o simplemente hacer clic en el botón "Try" para realizar una prueba. +Al mismo tiempo, puede observar que a la derecha se genera el código de llamada correspondiente; puede copiar el código y ejecutarlo directamente, o también puede hacer clic directamente en el botón «Try» para realizar pruebas. Parámetros opcionales: -- `dimensions`: recortar la dimensión del vector, la salida por defecto es la dimensión completa. -- `encoding_format`: formato de retorno, puede ser `float` o `base64`. +- `dimensions`: recorta las dimensiones del vector; por defecto, genera las dimensiones completas. +- `encoding_format`: formato de retorno; puede ser `float` o `base64`.

-Código de ejemplo de llamada en Python: +Código de llamada de ejemplo en Python: ```python import requests @@ -50,8 +50,8 @@ headers = { } payload = { - "input": "La comida estaba deliciosa y el camarero...", - "model": "text-embedding-ada-002", + "input": "The food was delicious and the waiter...", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Después de la llamada, encontramos que el resultado devuelto es el siguiente: +Después de la llamada, observamos que el resultado devuelto es el siguiente: ```json { @@ -97,7 +97,7 @@ Después de la llamada, encontramos que el resultado devuelto es el siguiente: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,22 +105,22 @@ Después de la llamada, encontramos que el resultado devuelto es el siguiente: } ``` -El resultado devuelto tiene varios campos, que se describen a continuación: +El resultado devuelto contiene varios campos, que se presentan a continuación: -- `model`, el modelo utilizado para convertir el texto en un vector de palabras. -- `usage`, la información de tokens utilizada para convertir el texto en un vector de palabras. -- `data`, el resultado del vector de palabras después de la conversión del texto. +- `model`, el modelo utilizado esta vez para convertir el texto en vectores de palabras. +- `usage`, la información de tokens utilizada esta vez para convertir el texto en vectores de palabras. +- `data`, el resultado de los vectores de palabras después de la conversión del texto. -Dentro de `data` se incluye la información específica del vector de palabras correspondiente al texto, donde `embedding` es el resultado específico del vector de palabras generado. +Entre ellos, `data` contiene la información específica de los vectores de palabras correspondientes al texto, y su `embedding` es el resultado específico de los vectores de palabras generados. ## Manejo de errores -Al llamar a la API, si se encuentra con un error, la API devolverá el código de error y la información correspondiente. Por ejemplo: +Al invocar la API, si se produce un error, la API devolverá el código y la información de error correspondientes. Por ejemplo: -- `400 token_mismatched`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos. -- `400 api_not_implemented`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos. -- `401 invalid_token`: No autorizado, token de autorización inválido o faltante. -- `429 too_many_requests`: Demasiadas solicitudes, has superado el límite de tasa. +- `400 token_mismatched`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o no válidos. +- `400 api_not_implemented`: Solicitud incorrecta, posiblemente debido a parámetros faltantes o no válidos. +- `401 invalid_token`: No autorizado, token de autorización no válido o faltante. +- `429 too_many_requests`: Demasiadas solicitudes, ha excedido el límite de velocidad. - `500 api_error`: Error interno del servidor, algo salió mal en el servidor. ### Ejemplo de respuesta de error @@ -138,4 +138,4 @@ Al llamar a la API, si se encuentra con un error, la API devolverá el código d ## Conclusión -A través de este documento, has aprendido cómo utilizar la API de Embeddings de OpenAI para aprovechar fácilmente la función de generación de vectores de palabras de OpenAI. Esperamos que este documento te ayude a integrar y utilizar mejor esta API. Si tienes alguna pregunta, no dudes en contactar a nuestro equipo de soporte técnico. +A través de este documento, ya ha comprendido cómo utilizar la API de OpenAI Embeddings para usar fácilmente la función oficial de OpenAI de generación de vectores de palabras. Esperamos que este documento pueda ayudarle a conectar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en contactar a nuestro equipo de soporte técnico. diff --git a/es/guides/platform/wework_bot.mdx b/es/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..d0e758b34 --- /dev/null +++ b/es/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "Robot de WeCom" +description: "Platform API guide - Ace Data Cloud" +--- + +Despliega tu propia instancia de cuenta de WeCom, inicia sesión escaneando con WeCom móvil y lee la cuenta, los contactos, las conversaciones y los mensajes sincronizados localmente mediante REST API o MCP. La instancia corresponde a una cuenta normal de WeCom, sin necesidad de configuración de servidor privado ni de dominio de correo empresarial. + +Actualmente está en Alpha. La lectura de cuentas ha completado la validación con conversaciones reales; el envío de texto propio y la lectura de eventos han completado la aceptación real; las operaciones con otros contactos, grupos y la recuperación de nuevas instancias aún deben completar la aceptación en el entorno de despliegue. El envío de medios, las respuestas con cita, las menciones @ reales, la gestión de miembros de grupos y los acuses de entrega aún no están disponibles. Consulte el valor devuelto por `/api/capabilities` de la instancia. + +## Despliegue e inicio de sesión + +Active el servicio en la categoría Deployment y seleccione el plan de duración de la instancia. Después del despliegue, abra la página de administración y escanee con WeCom de la propia cuenta; si se requiere confirmación móvil u otros pasos de inicio de sesión, abra el escritorio remoto e introduzca la contraseña de escritorio de esa instancia. Las credenciales de API y la contraseña de escritorio son independientes. Los datos de inicio de sesión se guardan en el disco de la instancia; al reconstruir el contenedor se conserva el disco; eliminar el disco eliminará la sesión local. + +Cada instancia se cobra de forma independiente y se ejecuta según la duración adquirida. Las llamadas REST / MCP no se cobran adicionalmente por mensaje; el precio real prevalece según la página del plan. Actualmente se toma como referencia predeterminada el plan de duración de los robots de WeChat; antes de la apertura final, se debe confirmar la fijación de precios en combinación con los recursos de ejecución. + +## API y MCP + +Utilice la dirección API de la instancia en la página de administración; todas las interfaces de cuenta llevan `Authorization: Bearer `. Estas rutas pertenecen a instancias exclusivas, no a una puerta de enlace API compartida. La dirección MCP es la dirección de la instancia más `/mcp/`, utilizando el mismo token Bearer. + +| Interfaz | Función | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Si la cuenta está lista y la lista de capacidades | +| `GET /api/auth/qr` | PNG Base64 del código QR de inicio de sesión actual | +| `GET /api/account` | Cuenta actual | +| `GET /api/contacts?kind=all` | Colegas internos y contactos externos; se puede especificar internal / external | +| `GET /api/conversations` | Conversaciones locales, conservando el ID de conversación original | +| `GET /api/messages` | Mensajes sincronizados localmente; parámetros conversation_id, after_rowid, limit | +| `POST /api/search` | Búsqueda local de contactos, conversaciones y texto | +| `POST /api/messages` | Tarea asíncrona de envío de texto; se debe proporcionar Idempotency-Key | +| `POST /api/messages/send` | Misma entrada de envío, admite uno o varios destinos | +| `GET /api/groups/{conversation_id}` | Información y miembros de grupos sincronizados localmente | +| `GET /api/tasks` | Tareas recientes y resultados de cada destino | +| `GET /api/tasks/{id}` | Consultar resultado de envío | +| `POST /api/tasks/{id}/cancel` | Cancelar tareas que aún no han comenzado | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Pausar la automatización; reanudar después de la verificación del propietario | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Estado de la instancia y pantalla actual; ambos requieren autenticación | +| `GET /api/events?after=0` | Eventos de mensajes con cursor recuperable | +| `WS /ws` | Flujo de eventos de mensajes, autenticación Bearer | + +El cuerpo de envío contiene `target`, `type: "text"` y `text`. `target` acepta ID de conversación, ID de contacto, ID de usuario empresarial o nombre completo único; se priorizan los ID; si el nombre mostrado aún no permite una localización única, la instancia rechazará la operación y no adivinará el destinatario. Para los contactos sin conversación local, primero se abrirá una conversación a través del cliente, y se enviará después de verificar el ID de conversación real. El encabezado de solicitud `Idempotency-Key` tiene entre 8 y 128 caracteres de letras, números o `_.:-`. Las solicitudes repetidas para la misma operación deben reutilizar la misma clave y el mismo cuerpo de solicitud. + +Cambiar `target` por una matriz `targets` permite enviar secuencialmente a 1–50 destinos especificados de forma explícita. No se pueden proporcionar ambos simultáneamente. Todos los destinos completan primero la resolución de identidad; se rechazarán distintos alias que apunten al mismo objeto. Después de que falle un destino, se detendrán los envíos posteriores; el resultado de la tarea registra por elemento `succeeded`, `failed`, `unknown` o `not_attempted`; no trate el éxito parcial como éxito completo. Este flujo aún debe completar la aceptación real de contactos especificados en el entorno de despliegue. + +Las tareas pueden estar en queued, running, submitting, succeeded, failed, unknown o cancelled. `succeeded` indica que, después del envío, se encontró el texto exacto y el ID de mensaje del servidor en el registro de la conversación correspondiente; `delivered` sigue siendo null y no representa que la otra parte lo haya recibido. unknown indica que el resultado no está claro; revise los registros históricos y no repita el envío con una clave nueva. La instancia no reintentará automáticamente las tareas interrumpidas. + +El historial solo contiene contenido ya sincronizado por el cliente y no puede garantizar todo el historial. Los mensajes no textuales pueden devolver un tipo unknown; la descarga de archivos adjuntos aún no está disponible. Los eventos conservan las 10.000 entradas más recientes; `gap` indica que el cursor ha superado la ventana de retención. La primera conexión no reproducirá el historial antiguo como mensajes nuevos. + +`server_accepted` y `server_id` del historial de mensajes pueden utilizarse para verificar si el servidor ha aceptado el mensaje local; cuando solo aparece un registro local sin ID de servidor, no se puede determinar que el envío haya tenido éxito. Estos campos no representan que el receptor lo haya recibido o leído. Los registros de eventos conservan el estado en el momento de su generación; para consultar el estado de confirmación actual, se debe utilizar la interfaz de historial de mensajes. + +## Cuenta y credenciales + +Inicie sesión únicamente en cuentas que el propietario tenga autorización para operar. Configure el token API en aplicaciones de confianza; puede acceder a los datos de cuenta de esa instancia. No publique contraseñas, códigos QR ni capturas de pantalla de chats en lugares públicos. Pausar la instancia interrumpirá los eventos en tiempo real. Después de cerrar sesión en la cuenta o eliminar el dispositivo desde el móvil, será necesario iniciar sesión de nuevo. + +La entrada de texto actual solo admite una línea; los saltos de línea se rechazarán explícitamente antes del envío. Cuando el cliente requiera verificación de seguridad o volver a iniciar sesión, el propietario de la cuenta debe completarlo en el escritorio remoto; la instancia no eludirá la verificación. Las tareas tras una interrupción de verificación pueden devolver unknown; consulte primero el registro de mensajes y no reenvíe con una nueva clave de idempotencia. + +Después de detectar un aviso de verificación de seguridad, el cierre de sesión de la cuenta o cambios, la cola de automatización se pausará de forma persistente. Después de completar la verificación móvil, puede continuar las tareas aún no ejecutadas mediante «Reanudar después de la verificación» en la consola de la instancia; las tareas ya enviadas pero con resultado incierto no se reenviarán. El trabajo remoto normal también puede activar la verificación de seguridad de WeCom. La ventana de 24 horas sin bloqueo adicional después de la verificación indicada en la documentación oficial no significa que se haya eliminado la detección, ni significa que la instancia pueda garantizar una operación desatendida a largo plazo. diff --git a/fi/guides/claude/claude_messages.mdx b/fi/guides/claude/claude_messages.mdx index e5e3c8236..caa1ee5b9 100644 --- a/fi/guides/claude/claude_messages.mdx +++ b/fi/guides/claude/claude_messages.mdx @@ -3,41 +3,42 @@ title: "Claude Messages API:n hakeminen ja käyttö" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude on erittäin tehokas AI-keskustelujärjestelmä, joka pystyy tuottamaan sujuvia ja luonnollisia vastauksia vain muutamassa sekunnissa, kun syötät kehotteen. Claude Messages API on Anthropicin virallinen natiivi API-muoto. Se eroaa OpenAI-yhteensopivasta muodosta (Chat Completion) käyttämällä Anthropicin omaa pyyntö- ja vastausrakennetta, minkä ansiosta Clauden ainutlaatuisia ominaisuuksia voidaan hyödyntää paremmin, kuten multimodaalista sisällön syöttöä, työkalukutsuja, syvällistä ajattelua (Extended Thinking) ja muita edistyneitä ominaisuuksia. +Anthropic Claude on erittäin tehokas AI-keskustelujärjestelmä, joka voi tuottaa sujuvia ja luonnollisia vastauksia vain muutamassa sekunnissa, kun syötät kehotteen. Claude Messages API on Anthropicin virallinen natiivi API-muoto, joka eroaa OpenAI-yhteensopivasta muodosta (Chat Completion) siten, että se käyttää Anthropicin omaa pyyntö- ja vastausrakennetta ja voi hyödyntää paremmin Clauden ainutlaatuisia ominaisuuksia, kuten multimodaalista sisällön syöttöä, työkalukutsuja, syvällistä ajattelua (Extended Thinking) ja muita edistyneitä ominaisuuksia. -Tässä dokumentissa esitellään pääasiassa Claude Messages API -toimintojen käyttöprosessi. Sen avulla voimme käyttää Anthropicin virallisen rajapinnan mukaista natiivia käyttöliittymää Clauden keskustelutoimintojen kutsumiseen. +Tässä dokumentissa esitellään pääasiassa Claude Messages API -toimintojen käyttöprosessi. Sen avulla voimme käyttää Anthropicin virallista vastaavaa natiivia rajapintaa Clauden keskustelutoimintojen kutsumiseen. ## Hakuprosessi -Käyttääksesi Claude Messages API:a hanki ensin API Token -avaimesi [Ace Data Cloud -konsolista](https://platform.acedata.cloud/console/applications) ja säilytä se varalla. +Jos haluat käyttää Claude Messages API:a, hanki ensin API Tokenisi [Ace Data Cloud -konsolista](https://platform.acedata.cloud/console/applications) ja pidä se varalla. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Jos et ole vielä kirjautunut sisään tai rekisteröitynyt, sinut ohjataan automaattisesti kirjautumissivulle rekisteröitymään ja kirjautumaan sisään. Valmistumisen jälkeen palaat automaattisesti tälle sivulle. +Jos et ole vielä kirjautunut sisään tai rekisteröitynyt, sinut ohjataan automaattisesti kirjautumissivulle rekisteröitymään ja kirjautumaan sisään, minkä jälkeen palaat automaattisesti tälle sivulle. -**Yhdellä API Token -avaimella voidaan kutsua kaikkia alustan palveluita, eikä jokaista palvelua tarvitse hakea erikseen.** Ensimmäisellä hakukerralla saat maksutonta käyttökiintiötä ilmaista kokeilua varten; jos kiintiö ei riitä, voit lisätä yleistä saldoa [konsolissa](https://platform.acedata.cloud/console/coin). +**Yhdellä API Tokenilla voi kutsua kaikkia alustan palveluita, eikä sitä tarvitse hakea erikseen jokaiselle palvelulle.** Ensimmäisen hakemuksen yhteydessä saat ilmaista käyttökiintiötä maksutonta kokeilua varten; kun kiintiö ei riitä, voit ladata yleissaldoa [konsolissa](https://platform.acedata.cloud/console/coin). > 📘 Täydellinen dokumentaatio: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Peruskäyttö -Claude Messages API:n pyyntöpolku on `/v1/messages`, ja se vastaa Anthropicin virallista API:a. Meidän on annettava vähintään kolme pakollista parametria: +Claude Messages API:n pyyntöpolku on `/v1/messages`, joka on sama kuin Anthropicin virallisessa API:ssa. Meidän on annettava vähintään kolme pakollista parametria: -- `model`: Valitse käytettävä Claude-malli. `claude-opus-5-5` on saatavilla vain Messages API:n kautta, tukee 1 miljoonan Tokenin kontekstia, enintään 128K Tokenin tulostetta ja käyttää aina mukautuvaa ajattelua. Uusin lippulaiva on `claude-fable-5-1` (1 miljoonan Tokenin konteksti, enintään 128K Tokenin tuloste); alkuperäinen `claude-fable-5` säilyy edelleen yhteensopivana. `claude-sonnet-5-5` on lisätty natiiviin Messages-rajapintasariin, tukee kuvasyötettä ja mukautuvaa ajattelua; sen viralliset viitehinnat syötteelle, tulosteelle ja välimuistin luvulle ovat vastaavasti 2, 10 ja 0,20 Yhdysvaltain dollaria miljoonaa Tokenia kohden. -- `messages`: Syötettävä viestitaulukko, jossa jokainen viesti sisältää `role`-arvon (rooli) ja `content`-arvon (sisältö); `role` tukee arvoja `user` ja `assistant`. +- `model`: Valitse käytettävä Claude-malli. `claude-opus-5-5` on saatavilla vain Messages API:n kautta, se tukee 1 miljoonan Tokenin kontekstia, enintään 128K Tokenin tulostetta ja ottaa aina käyttöön mukautuvan ajattelun. Uusin lippulaivamalli on `claude-fable-5-1` (1 miljoonan Tokenin konteksti, enintään 128K Tokenin tuloste); alkuperäinen `claude-fable-5` säilyy edelleen yhteensopivana. `claude-sonnet-5-5` on liittynyt natiiviin Messages-sarjan rajapintaan ja tukee kuvasisältöä sekä mukautuvaa ajattelua; sen viralliset viitehinnat syötteelle, tulosteelle ja välimuistin luvulle ovat vastaavasti 2, 10 ja 0,20 Yhdysvaltain dollaria miljoonaa Tokenia kohden. +- `messages`: Syötettyjen viestien taulukko, jossa jokainen viesti sisältää `role`-arvon (rooli) ja `content`-arvon (sisältö); `role` tukee arvoja `user` ja `assistant`. - `max_tokens`: Tulostettavien tokenien enimmäismäärä, jota käytetään yksittäisen vastauksen pituuden rajoittamiseen. Yleisesti käytetyt valinnaiset parametrit: - `system`: Järjestelmäkehote, jota käytetään mallin toiminnan ja roolin määrittämiseen. -- `temperature`: Generoinnin satunnaisuus, välillä 0–1; mitä suurempi arvo, sitä hajautuneempi vastaus. -- `stream`: Käytetäänkö suoratoistovastausta; asettamalla arvoksi `true` voidaan toteuttaa merkki kerrallaan palautuva vaikutus. +- `temperature`: Luomisen satunnaisuus, välillä 0–1; mitä suurempi arvo, sitä hajautuneempia vastaukset ovat. +- `stream`: Käytetäänkö suoratoistovastausta; arvon `true` asettaminen mahdollistaa merkkikohtaisen palautusefektin. - `stop_sequences`: Mukautetut pysäytyssekvenssit; malli lopettaa generoinnin kohdatessaan nämä tekstit. -- `top_p`: Ydinnäytteenoton parametri, joka säätelee generoinnin satunnaisuutta yhdessä temperaturen kanssa. +- `top_p`: Ydinnäytteenottoparametri, joka yhdessä temperaturen kanssa hallitsee generoinnin satunnaisuutta. - `top_k`: Näytteistää vain K:sta todennäköisimmästä vaihtoehdosta. -- `tools`: Työkalumäärittelyt, joiden avulla malli voi kutsua ulkoisia funktioita. -- `tool_choice`: Hallitsee sitä, miten malli käyttää annettuja työkaluja. -- `cache_control`: Luo automaattisesti välimuistin katkaisukohdan pyynnön viimeiseen välimuistiin tallennettavissa olevaan sisältölohkoon; voidaan myös kirjoittaa tiettyyn sisältölohkoon. +- `tools`: Työkalumääritykset, joiden avulla malli voi kutsua ulkoisia funktioita. +- `tool_choice`: Hallitsee, miten malli käyttää tarjottuja työkaluja. +- `cache_control`: Luo automaattisesti välimuistin katkaisupisteen pyynnön viimeiseen välimuistiin tallennettavaan sisältölohkoon; voidaan myös kirjoittaa tiettyyn sisältölohkoon. +- `metadata`: Valinnainen pyynnön metatieto-objekti. `metadata.user_id` on merkkijono, johon voidaan välittää kutsujan mukautettu käyttäjätunniste, esimerkiksi `{"user_id":"example-user-001"}`; on suositeltavaa käyttää vakaata tunnistetta, joka ei sisällä henkilötietoja. Se ei korvaa `Authorization`-todennusta eikä sitä tarvitse kirjoittaa `messages`-keskustelusisältöön. ### cURL-esimerkki @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -106,25 +109,25 @@ Kutsun jälkeen palautettava tulos on seuraava: } ``` -Palautettavien tuloskenttien selitys: - +Palautustuloksen kenttien selitykset: - `id`: Tämän viestin yksilöllinen tunniste. - `type`: Aina `message`. - `role`: Aina `assistant`. -- `content`: Vastaussisällön taulukko, jossa jokainen elementti sisältää `type`-arvon (kuten `text`) ja vastaavan sisällön. +- `content`: Vastaussisältötaulukko, jonka jokainen elementti sisältää `type`-kentän (kuten `text`) ja vastaavan sisällön. - `model`: Pyynnön käsittelevän mallin nimi. -- `stop_reason`: Pysäytyksen syy. Vakaat arvot sisältävät `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (voit lähettää nykyisen assistant-sisällön sellaisenaan takaisin jatkaaksesi), `refusal` ja `model_context_window_exceeded`. -- `stop_sequence`: Jos toiminta pysäytetään mukautetun pysäytyssekvenssin vuoksi, näyttää vastaavan pysäytyssekvenssin tekstin. -- `stop_details`: Kun `stop_reason` on `refusal`, voi sisältää kieltäytymisluokan ja selityksen. -- `usage`: Tokenien käyttötilastot. `input_tokens` tarkoittaa välimuistiin tallentamatonta syötettä; `cache_creation_input_tokens` ja `cache_read_input_tokens` tarkoittavat vastaavasti välimuistin kirjoitusta ja lukua; `output_tokens` on kaikkien tulostettujen tokenien määrä. Jos palautetaan `output_tokens_details.thinking_tokens`, tämä arvo on `output_tokens`-arvon osajoukko, eikä sitä pidä laskea uudelleen mukaan kokonaismäärää tai kustannuksia laskettaessa. Tämä erittely voi olla `null` tai puuttua, jos sille ei ole luotettavaa laskentaa. -- `usage.cache_creation`: Valinnainen välimuistin kirjoituksen TTL-erittely, joka sisältää `ephemeral_5m_input_tokens` ja `ephemeral_1h_input_tokens`. Kun objekti on olemassa, näiden kahden summa vastaa arvoa `cache_creation_input_tokens`; jos kenttä on `null` tai puuttuu, nykyisessä vastauksessa ei ole käytettävissä TTL-erittelyä, eikä sitä voida tulkita arvoksi `0`. -- `usage.cost`: Muut kuin suoratoistovastaukset voivat sisältää Ace Data Cloudin tallentaman käyttökiintiön kulutusobjektin, jossa `amount` on tämän kerran todellinen kulutus, `currency` on mittayksikkö ja `list_amount` on summa ennen alennusta (jos sellainen on). Fable 5.1:n virallinen välimuistin luvun perushinta on $0.25/miljoona Tokenia, ja 5 minuutin sekä 1 tunnin välimuistin kirjoituksen perushinnat ovat vastaavasti $12.50 ja $20/miljoona Tokenia; alustan todellinen hinta muunnetaan pakettialennuksen mukaisesti. +- `stop_reason`: Lopetussyy. Vakaat arvot sisältävät `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (voit palauttaa nykyisen assistant-sisällön sellaisenaan jatkaaksesi), `refusal` ja `model_context_window_exceeded`. +- `stop_sequence`: Jos pysäytys johtuu mukautetusta pysäytyssekvenssistä, näyttää vastaavan pysäytyssekvenssin tekstin. +- `stop_details`: Kun `stop_reason` on `refusal`, voi sisältää kieltäytymiskategorian ja kuvauksen. +- `usage`: Tokenien käyttötilastot. `input_tokens` on välimuistiin tallentamaton syöte; `cache_creation_input_tokens` ja `cache_read_input_tokens` ovat vastaavasti välimuistin kirjoitus ja luku; `output_tokens` on kaikkien tulostokenien määrä. Jos palautetaan `output_tokens_details.thinking_tokens`, tämä arvo on `output_tokens`-arvon osajoukko, eikä sitä tule lisätä uudelleen kokonaismäärää tai kustannusta laskettaessa. Tämä erittely voi olla `null` tai puuttua, jos sillä ei ole auktoritatiivista laskentaa. +- `usage.cache_creation`: Valinnainen välimuistikirjoituksen TTL-erittely, joka sisältää `ephemeral_5m_input_tokens` ja `ephemeral_1h_input_tokens`. Kun objekti on olemassa, näiden kahden summa on yhtä suuri kuin `cache_creation_input_tokens`; `null`-arvo tai puuttuva kenttä tarkoittaa, ettei nykyiselle vastaukselle ole saatavilla TTL-erittelyä, eikä sitä voi tulkita arvoksi `0`. +- `usage.cost`: Ei-suoratoistovastaukset voivat sisältää Ace Data Cloudin kirjaaman käyttöhyvityskulutusobjektin, jossa `amount` on tämän kerran todellinen kulutus, `currency` on mittayksikkö ja `list_amount` on summa ennen alennusta (jos sellainen on). Fable 5.1:n virallinen välimuistilukemisen perushinta on $0.25/miljoona tokenia, ja 5 minuutin sekä 1 tunnin välimuistikirjoituksen perushinnat ovat vastaavasti $12.50 ja $20/miljoona tokenia; alustan todellinen hinta muunnetaan pakettialennuksen mukaan. ## Järjestelmäkehote -Claude Messages API tukee järjestelmäkehotteen määrittämistä `system`-kentän kautta mallin toiminnan, roolin ja kontekstin määrittämiseksi. +Claude Messages API tukee järjestelmäkehotteiden määrittämistä `system`-kentän kautta, jota käytetään mallin toiminnan, roolin ja kontekstin määrittelyyn. ### Python-esimerkki + ```python import requests @@ -153,7 +156,7 @@ Asettamalla `system`-kehotteen voit hallita tarkasti Clauden roolia ja toimintat ## Suoratoistovastaus -Tämä rajapinta tukee myös suoratoistovastauksia. Asettamalla `stream`-parametrin arvoksi `true` saat vaiheittain palautuvan vaikutelman, mikä soveltuu erittäin hyvin merkkikohtaisen näytön toteuttamiseen verkkosivulla. +Tämä rajapinta tukee myös suoratoistovastauksia. Asettamalla `stream`-parametrin arvoksi `true` voit saada vaiheittaisen palautuksen, mikä sopii erinomaisesti merkkikohtaisen näytön toteuttamiseen verkkosivulla. ### Python-esimerkki @@ -183,16 +186,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Suoratoistovastaus palautetaan Server-Sent Events (SSE) -muodossa, ja jokainen rivi alkaa etuliitteellä `event:` ja `data:`. Suoratoistotapahtumatyyppejä ovat: +Suoratoistovastaus palautetaan Server-Sent Events (SSE) -muodossa, jossa jokainen rivi alkaa etuliitteillä `event:` ja `data:`. Suoratoistotapahtumatyypit sisältävät: -- `message_start`: Viesti alkaa ja sisältää viestin perustiedot sekä mallin nimen. -- `content_block_start`: Sisältölohko alkaa. -- `content_block_delta`: Sisältölohkon inkrementaalinen päivitys, joka sisältää uuden tuotetun tekstikatkelman. -- `content_block_stop`: Sisältölohko päättyy. -- `message_delta`: Viestitason inkrementaalinen päivitys, joka sisältää `stop_reason`- ja lopulliset `usage`-tiedot. Kohdan `output_tokens_details.thinking_tokens` auktoritatiivinen arvo tulee lukea vain viimeisestä `message_delta.usage`-kohdasta, eikä sitä tule kerryttää tapahtumien välillä. -- `message_stop`: Viesti päättyy. +- `message_start`: Viestin alku, sisältää viestin perustiedot ja mallin nimen. +- `content_block_start`: Sisältölohkon alku. +- `content_block_delta`: Sisältölohkon inkrementaalinen päivitys, sisältää uuden luodun tekstikatkelman. +- `content_block_stop`: Sisältölohkon loppu. +- `message_delta`: Viestitason inkrementaalinen päivitys, sisältää `stop_reason`- ja lopulliset `usage`-tiedot. `output_tokens_details.thinking_tokens`-arvon auktoritatiivinen arvo tulee lukea vain viimeisestä `message_delta.usage`-tapahtumasta, eikä sitä tule kerryttää tapahtumien välillä. +- `message_stop`: Viestin loppu. -Tuloste näyttää seuraavalta: +Tuloste on seuraava: ``` event: message_start @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Kuten nähdään, suoratoistovastauksen `content_block_delta`-tapahtuma sisältää vaiheittain tuotetun tekstisisällön, ja yhdistämällä kaikki `text_delta`-kohdat saat täydellisen vastauksen. +Kuten voidaan nähdä, suoratoistovastauksen `content_block_delta`-tapahtuma sisältää vaiheittain luodun tekstisisällön, ja yhdistämällä kaikki `text_delta`-osat voidaan saada täydellinen vastaus. ### JavaScript-esimerkki @@ -253,7 +256,7 @@ while (true) { ## Monikierroksinen keskustelu -Jos haluat ottaa käyttöön monikierroksisen keskustelutoiminnon, sinun tulee sijoittaa `messages`-taulukkoon vuorotellen `user`- ja `assistant`-roolien viestejä sekä välittää aiempi keskusteluhistoria mukana. +Jos haluat ottaa käyttöön monikierroksisen keskustelutoiminnon, sinun on järjestettävä `messages`-taulukossa `user`- ja `assistant`-roolien viestit vuorotellen ja välitettävä samalla aiempi keskusteluhistoria. ### Python-esimerkki @@ -283,7 +286,6 @@ print(response.json()) ``` Palautettu tulos on seuraava: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ Palautettu tulos on seuraava: } ``` -Välittämällä koko keskusteluhistorian `messages`-kohdassa Claude voi antaa tarkkoja vastauksia asiayhteyden perusteella. +Välittämällä koko keskusteluhistorian `messages`-kentässä Claude voi antaa tarkkoja vastauksia kontekstin perusteella. -## Syvällisen päättelyn malli +## Syvällisen ajattelun mallit -Clauden thinking ja thinking summary ovat kaksi eri käsitettä: malli voi suorittaa sisäistä päättelyä, mutta API ei palauta alkuperäistä ajatusketjua. Kun päättelyprosessi täytyy näyttää, API palauttaa käsitellyn yhteenvedon. +Clauden thinking ja thinking summary ovat kaksi eri käsitettä: malli voi suorittaa sisäistä päättelyä, mutta API ei palauta alkuperäistä ajatusketjua. Kun päättelyprosessi on näytettävä, API palauttaa käsitellyn yhteenvedon. -Nykyiselle mallille suositellaan adaptive thinking -toimintoa, ja kokonaispäättelyyn käytettävää panostusta hallitaan `output_config.effort`-asetuksella: +Nykyisille malleille suositellaan adaptive thinkingiä, ja kokonaispäättelypanostusta hallitaan `output_config.effort`-asetuksella: ```python import requests @@ -341,7 +343,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Vastauksen thinking-lohko on seuraavanlainen: +Vastauksen thinking-lohko näyttää tältä: ```json { @@ -350,26 +352,27 @@ Vastauksen thinking-lohko on seuraavanlainen: "signature": "opaque-signature" } ``` -- `display: "summarized"` palauttaa luettavan tiivistelmän ajattelusta; se ei ole alkuperäinen ajatusketju. -- `display: "omitted"` palauttaa `thinking: ""`, mutta säilyttää edelleen läpinäkymättömän `signature`-arvon myöhempiä keskusteluja varten. -- `display: "updates"` on Anthropicin beta-tila, ja sen mukana on lähetettävä `anthropic-beta: thinking-display-updates-2026-08-18`. Virallinen määritelmä on, että päättelyn varsinainen teksti piilotetaan ja työkalukutsujen välillä näytetään lyhyitä tilannepäivityksiä. Alusta välittää tämän parametrin ja beta-pyyntöotsakkeen sellaisenaan, eikä pakota sen uudelleenkirjoittamista muotoon `summarized`; todellinen tulostussisältö riippuu valitun mallin tuesta. -- `thinking`-, `output_config`-, effort-, näytteenottoparametrit sekä uudet laajennuskentät välitetään alkuperäisillä arvoillaan. Alusta ei ylläpidä mallikohtaisesti kovakoodattuja arvoluetteloita tai yhdistelmärajoituksia eikä kirjoita thinking-tilaa automaattisesti uudelleen; valittu malli määrittää, hyväksytäänkö nämä parametrit, ja mallin palauttamat parametrivirheet välitetään takaisin asiakkaalle. -- Fable 5.1:n, Fable 5:n, Opus 5:n, Sonnet 5:n, Opus 4.8:n ja Opus 4.7:n display-oletusarvo on `omitted`; Opus 4.6:ssa, Sonnet 4.6:ssa ja aiemmissa thinkingiä tukevissa malleissa käytetään oletuksena `summarized`-arvoa. -- Display vaikuttaa vain palautettavaan sisältöön ja suoratoiston viiveeseen; se ei poista päättelyä käytöstä eikä vähennä thinking-tokenien laskutusta. -- Thinkingin oletusarvoinen käyttöönotto ja display-oletusarvo ovat kaksi erillistä kysymystä. Opus 5 ja Sonnet 5 ottavat adaptive thinkingin oletuksena käyttöön; Opus 5:ssa `thinking`-kentän pois jättäminen vastaa adaptive-tilaa ja `output_config.effort`-kentän pois jättäminen vastaa arvoa `high`. Opus 4.8, 4.7 ja 4.6 edellyttävät nimenomaista käyttöönottoa. -- Thinking ja lopullinen tekstisisältö käyttävät yhdessä `max_tokens`-tulostusbudjetin. Jos budjetti on liian pieni, thinking voi käyttää suurimman osan kiintiöstä, jolloin tekstisisältö jää tyhjäksi tai katkeaa; kasvata `max_tokens`-arvoa tai hallitse päättelypanostusta `low` / `medium` effortilla. -- Malleille, joissa thinking voidaan poistaa käytöstä, voi välittää `thinking: {"type":"disabled"}`. Uudet tilat, kuten `between_tools`, sekä effort-yhdistelmät riippuvat valitusta mallista; alusta ei hylkää niitä etukäteen vanhojen mallisääntöjen perusteella. -- Kiinteä ajattelubudjetti voidaan välittää `budget_tokens`-kentällä; uudet mallit käyttävät yleensä `thinking.type=adaptive`-asetusta ja `output_config.effort`-kenttää. Kiinteän budjetin tai ajattelun poistamisen käytöstä tuki määräytyy valitun mallin nykyisten ominaisuuksien mukaan. -- Monikierroksisissa keskusteluissa ja työkalukutsuissa assistantin palauttamat täydelliset thinking-lohkot ja signature on välitettävä takaisin sellaisinaan; signaturea ei saa muokata eikä luoda itse. -- Parametrien läpivienti ei tarkoita, että jokainen malli tukisi kaikkia toimintoja. Protokollien väliset kutsut edellyttävät edelleen muunnosta, ja sisällön, kuten `redacted_thinking`, tuki sekä virheet määräytyvät pyynnön tosiasiallisesti käsittelevän mallipalvelun mukaan. + +- `display: "summarized"` palauttaa luettavan ajatteluyhteenvedon; se ei ole alkuperäinen ajatusketju. +- `display: "omitted"` palauttaa `thinking: ""`-arvon, mutta säilyttää edelleen peitetyn `signature`-arvon myöhempien keskustelujen tukemiseksi. +- `display: "updates"` on Anthropicin beta-tila, joka edellyttää `anthropic-beta: thinking-display-updates-2026-08-18`-otsaketta. Virallinen määritelmä on, että päättelytekstin sisältö piilotetaan ja työkalukutsujen välillä näytetään lyhyitä tilannepäivityksiä. Alusta välittää tämän parametrin ja beta-pyynnön otsakkeen sellaisenaan eikä pakota niiden uudelleenkirjoittamista muotoon `summarized`; todellinen tulostussisältö riippuu valitun mallin tuesta. +- `thinking`, `output_config`, effort, näytteenottoparametrit ja uudet laajennuskentät välitetään sellaisinaan. Alusta ei ylläpidä mallikohtaisesti kovakoodattuja arvoluetteloita tai yhdistelmärajoituksia eikä kirjoita thinking-tilaa automaattisesti uudelleen; valittu malli päättää, hyväksytäänkö nämä parametrit, ja mallin palauttamat parametrivirheet välitetään takaisin asiakkaalle. +- Fable 5.1:n, Fable 5:n, Opus 5:n, Sonnet 5:n, Opus 4.8:n ja Opus 4.7:n display-oletusarvo on `omitted`; Opus 4.6, Sonnet 4.6 ja aiemmat thinkingiä tukevat mallit käyttävät oletuksena `summarized`-arvoa. +- Display vaikuttaa vain palautettavaan sisältöön ja suoratoistoviiveeseen; se ei poista päättelyä käytöstä eikä vähennä thinking-tokenien laskutusta. +- Se, onko thinking oletusarvoisesti käytössä, ja displayn oletusarvo ovat kaksi erillistä kysymystä. Opus 5 ja Sonnet 5 ottavat adaptive thinkingin käyttöön oletusarvoisesti; Opus 5:ssä `thinking`-kentän pois jättäminen vastaa adaptive-tilaa ja `output_config.effort`-kentän pois jättäminen vastaa `high`-arvoa. Opus 4.8, 4.7 ja 4.6 edellyttävät nimenomaista käyttöönottoa. +- Thinking ja lopullinen tekstisisältö kuluttavat yhdessä `max_tokens`-tulostusbudjettia. Jos budjetti on liian pieni, thinking voi kuluttaa suurimman osan kiintiöstä, jolloin tekstisisältö jää tyhjäksi tai katkeaa; kasvata `max_tokens`-arvoa tai käytä `low` / `medium` effort -asetusta päättelypanostuksen hallintaan. +- Malleille, joissa thinkingin voi poistaa käytöstä, voidaan välittää `thinking: {"type":"disabled"}`. Uudet tilat, kuten `between_tools`, sekä effort-yhdistelmät riippuvat valitusta mallista; alusta ei hylkää niitä etukäteen vanhojen mallisääntöjen perusteella. +- Kiinteä ajattelubudjetti voidaan välittää `budget_tokens`-parametrilla; uudet mallit käyttävät yleensä `thinking.type=adaptive`-asetusta ja `output_config.effort`-asetusta. Se, tuetaanko kiinteää budjettia tai ajattelun poistamista käytöstä, riippuu valitun mallin nykyisistä ominaisuuksista. +- Monikierroksisissa keskusteluissa ja työkalukutsuissa assistantin palauttama täydellinen thinking-lohko ja signature on välitettävä takaisin sellaisenaan; älä muokkaa tai luo signaturea itse. +- Parametrien välittäminen ei tarkoita, että jokainen malli tukisi kaikkia toimintoja. Protokollien väliset kutsut edellyttävät edelleen muunnosta, ja sisällön, kuten `redacted_thinking`, tuen laajuuden ja virheet määrittää pyynnön tosiasiallisesti käsittelevä mallipalvelu. Suoratoistopyynnöissä `summarized` tuottaa `thinking_delta`-arvon; `omitted` ei tuota `thinking_delta`-arvoa, vaan säilyttää vain thinking-lohkon elinkaaren ja `signature_delta`-arvon. ## Visuaaliset mallit -Claude tukee multimodaalista syötettä ja voi käsitellä tekstiä ja kuvia samanaikaisesti. Messages API:ssa visuaalisia ominaisuuksia voi käyttää asettamalla `content` taulukkomuotoon ja välittämällä kuvasisältölohkoja. +Claude tukee monimuotoista syötettä ja voi käsitellä tekstiä ja kuvia samanaikaisesti. Messages API:ssa visuaalisia ominaisuuksia voi käyttää asettamalla `content` taulukkomuotoon ja välittämällä kuvasisältölohkon. -### Base64-koodattujen kuvien käyttäminen +### Base64-koodattujen kuvien käyttö ```python import base64 @@ -415,7 +418,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### URL-kuvien käyttäminen +### URL-kuvien käyttö ```python import requests @@ -456,7 +459,6 @@ print(response.json()) ``` ### cURL-esimerkki - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -486,11 +488,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Tuetut kuvamuodot ovat: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Tuetut kuvamuodot sisältävät: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Asiakirjat ja PDF:t -PDF:t käyttävät `document`-sisältölohkoa ja tukevat kahta vakaata lähdettä: Base64:ää ja URL:ää. Base64-lähteen on käytettävä `application/pdf`-tyyppiä: +PDF käyttää `document`-sisältölohkoa ja tukee kahta vakaata lähdettä: Base64:ää ja URL:ää. Base64-lähteen on käytettävä `application/pdf`-tyyppiä: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -URL-lähde kirjoitetaan muodossa `{"type":"url","url":"https://example.com/report.pdf"}`. `document` tukee myös `text/plain`-tyyppiä sekä `content`-lähdettä, joka koostuu text/image-lohkoista; valinnaisia kenttiä ovat `title`, `context` ja `citations`. Files API:n `file_id`-lähde kuuluu erilliseen beta-toimintoon eikä sisälly tämän rajapinnan vakaaseen sopimukseen. +URL-lähde kirjoitetaan muodossa `{"type":"url","url":"https://example.com/report.pdf"}`. `document` tukee myös `text/plain`-tyyppiä sekä text/image-lohkoista koostuvaa `content`-lähdettä; valinnaisia kenttiä ovat `title`, `context` ja `citations`. Files API:n `file_id`-lähde kuuluu erilliseen beta-ominaisuuteen eikä tämän rajapinnan vakaaseen sopimukseen. ## Kehotevälimuisti -Ylätason `cache_control` sijoittaa välimuistin katkaisukohdan automaattisesti viimeiseen välimuistiin kelpaavaan lohkoon: +Ylimmän tason `cache_control` sijoittaa automaattisesti välimuistin katkaisukohdan viimeiseen välimuistiin tallennettavaan lohkoon: ```python payload = { @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Kun sijaintia on hallittava tarkasti, saman `cache_control`-asetuksen voi kirjoittaa myös text-, image-, document-, tool_use- ja tool_result-sisältölohkoihin tai työkalun määrittelyyn. `ttl` tukee arvoja `5m` (oletus) ja `1h`; tarkista välimuistin kirjoitus ja osumat kenttien `usage.cache_creation_input_tokens` ja `usage.cache_read_input_tokens` avulla. -Kun vastaus tarjoaa `usage.cache_creation`-kentän, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Jos `cache_creation` on `null` tai se puuttuu, tämä tarkoittaa, että käytettävissä on vain välimuistin kirjoituksen kokonaismäärä ilman virallista TTL-erittelyä; tällöin mitään bucketia ei pidä käsitellä tunnettuna arvona 0, ja laskutus sekä kokonaismäärät perustuvat edelleen aggregate-kenttään. +Kun sijaintia on hallittava tarkasti, saman `cache_control`-määrityksen voi myös kirjoittaa text-, image-, document-, tool_use- tai tool_result-sisältölohkoon tai työkalun määritelmään. `ttl` tukee arvoja `5m` (oletus) ja `1h`; määritä välimuistiin kirjoittaminen ja osumat käyttämällä `usage.cache_creation_input_tokens`- ja `usage.cache_read_input_tokens`-kenttiä. + +Kun vastaus sisältää `usage.cache_creation`-kentän, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Jos `cache_creation` on `null` tai se jätetään pois, se tarkoittaa, että vain välimuistiin kirjoittamisen kokonaismäärä on saatavilla eikä auktoritatiivista TTL-erittelyä ole; tällöin mitään bucketia ei pidä pitää tunnettuna arvona 0, vaan laskutus ja kokonaismäärä perustuvat edelleen aggregate-kenttään. -Palautustulosesimerkki: +Palautetun tuloksen esimerkki: ```json { @@ -563,7 +566,7 @@ Palautustulosesimerkki: ## Työkalukutsut (Tool Use) -Claude Messages API tukee natiivisti työkalukutsutoimintoa, jonka avulla malli voi tarvittaessa kutsua ennalta määrittämiäsi työkaluja/funktioita. +Claude Messages API tukee natiivisti työkalukutsutoimintoa, jonka avulla malli voi tarvittaessa kutsua ennalta määritettyjä työkalujasi/funktioitasi. ### Python-esimerkki @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Kun malli päättää kutsua työkalua, palautustuloksen `content` sisältää `tool_use`-tyyppisen sisältölohkon: +Kun malli päättää kutsua työkalua, palautetun tuloksen `content` sisältää `tool_use`-tyyppisen sisältölohkon: ```json { @@ -637,7 +640,7 @@ Kun malli päättää kutsua työkalua, palautustuloksen `content` sisältää ` } ``` -Huomaa, että `stop_reason` on `tool_use`, mikä tarkoittaa, että mallin on kutsuttava työkalua. Kun olet saanut tämän tuloksen, sinun on suoritettava työkalufunktio ja palautettava tulos mallille `tool_result`-muodossa: +Huomaa, että `stop_reason` on `tool_use`, mikä osoittaa, että mallin on kutsuttava työkalua. Saatuasi tämän tuloksen sinun on suoritettava työkalufunktio ja palautettava tulos mallille `tool_result`-muodossa: ```python payload = { @@ -685,39 +688,38 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Malli luo työkalun palauttamien tulosten perusteella lopullisen luonnollisen kielen vastauksen. +Malli luo työkalun palauttaman tuloksen perusteella lopullisen luonnollisen kielen vastauksen. ## Erot Chat Completion API:in verrattuna Ace Data Cloud tarjoaa samanaikaisesti kahta Claude API -muotoa, joiden tärkeimmät erot ovat seuraavat: -Messages API:n `usage.input_tokens` tarkoittaa vain välimuistiin tallentamatonta syötettä, ja `cache_read_input_tokens` sekä `cache_creation_input_tokens` ovat itsenäisiä laskutusluokkia; kaikki kolme lasketaan erikseen vastaavien hintojen mukaan. - +Messages API:n `usage.input_tokens` tarkoittaa vain välimuistiin tallentamatonta syötettä, kun taas `cache_read_input_tokens` ja `cache_creation_input_tokens` ovat erillisiä laskutuksen luokkia; kaikki kolme lasketaan erikseen niitä vastaavien hintojen mukaan. | Ominaisuus | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Muoto | Anthropicin natiivimuoto | OpenAI-yhteensopiva muoto | -| Järjestelmäkehote | Erillinen `system`-kenttä | Välitetään `messages`-kentässä `role: "system"` -arvolla | -| Vastausrakenne | `content`-taulukko (tukee useita tyyppejä) | `choices`-taulukko (sisältää `message`-kentän) | -| Suoratoistomuoto | SSE-tapahtumat (useita tapahtumatyyppejä) | SSE `data` -rivit | +| Järjestelmäkehote | Erillinen `system`-kenttä | Välitetään `messages`-kentässä `role: "system"` | +| Vastausrakenne | `content`-taulukko (tukee useita tyyppejä) | `choices`-taulukko (sisältää `message`-objektin) | +| Suoratoistomuoto | SSE-tapahtumat (useita tapahtumatyyppejä) | SSE `data`-rivit | | Syvällinen päättely | Natiivi `thinking` ja `output_config.effort` | Mallin oletusstrategia ja yhteensopivuusparametrit | | Työkalukutsut | Natiivi `tools` + `input_schema` | OpenAI-yhteensopiva `tools`-muoto | | Token-tilastot | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Jos järjestelmäsi on jo integroitu OpenAI-muotoiseen API:in, voit käyttää Chat Completion API:a saumattomaan vaihtoon. Jos tarvitset kaikki Clauden natiivit ominaisuudet, Messages API:n käyttöä suositellaan. +Jos järjestelmäsi on jo integroitu OpenAI-muotoiseen APIin, voit käyttää Chat Completion APIa vaihtaaksesi saumattomasti. Jos tarvitset kaikki Clauden natiivit ominaisuudet, on suositeltavaa käyttää Messages APIa. ## Virheenkäsittely -Julkisen rajapinnan virhevastaus käyttää Ace Data Cloud -alustan envelopea: `error.code` on vakaa virhekoodi, `error.message` on kuvaus ja `trace_id` käytetään pyynnön selvittämiseen. Yleisiä HTTP-tiloja ovat: +Julkisten rajapintojen virhevastaus käyttää Ace Data Cloud -alustan envelope-rakennetta: `error.code` on vakaa virhekoodi, `error.message` on kuvaus ja `trace_id` käytetään pyynnön selvittämiseen. Yleisiä HTTP-tiloja ovat: -- `400`: Pyyntöparametrit tai protokollan sisältö ovat virheellisiä. +- `400`: Pyyntöparametrit tai protokollasisältö ovat virheellisiä. - `401`: Valtuutustunnus on virheellinen, puuttuu tai on vanhentunut. -- `403`: Pääsy on estetty, saldo ei riitä tai kiintiötä on rajoitettu. -- `404`: API:a tai mallia ei ole olemassa. +- `403`: Käyttö on kielletty, saldo on riittämätön tai kiintiötä on rajoitettu. +- `404`: APIa tai mallia ei ole olemassa. - `413`: Pyyntörunko on liian suuri. - `429`: Pyyntöjä on liikaa. - `500` / `503` / `504`: Palveluvirhe, tilapäisesti ei käytettävissä tai käsittely aikakatkaistiin. -### Virhevastausesimerkki +### Esimerkki virhevastauksesta ```json { @@ -729,7 +731,8 @@ Julkisen rajapinnan virhevastaus käyttää Ace Data Cloud -alustan envelopea: ` } ``` -Tämä virherakenne on Ace Data Cloudin ajonaikainen sopimus, eikä se vastaa Anthropicin virallista virhe-envelopea; käsittele se HTTP-tilan ja `error.code`-kentän mukaisesti. +Tämä virherakenne on Ace Data Cloudin ajonaikainen sopimus, eikä se vastaa Anthropicin virallista error envelope -rakennetta; käsittele se HTTP-tilan ja `error.code`-arvon mukaan. ## Johtopäätös -Tämän dokumentin kautta olet jo oppinut, kuinka Claude Messages API:a käytetään Clauden keskusteluominaisuuksien kutsumiseen Anthropicille ominaisessa muodossa. Messages API tukee monipuolisia toimintoja, kuten peruskeskusteluja, järjestelmäkehotteita, suoratoistovastauksia, monikierroksisia keskusteluja, syvällistä ajattelua, visuaalista ymmärrystä, PDF-tiedostoja, kehotteiden välimuistitallennusta ja työkalukutsuja. Jos sinulla on kysyttävää, ota milloin tahansa yhteyttä tekniseen tukitiimiimme. + +Tämän dokumentaation avulla olet oppinut, kuinka Claude Messages APIa käytetään Clauden keskusteluominaisuuksien kutsumiseen Anthropicin natiivimuodossa. Messages API tukee monipuolisia toimintoja, kuten peruskeskustelua, järjestelmäkehotteita, suoratoistovastauksia, monikierroksisia keskusteluja, syvällistä päättelyä, visuaalista ymmärrystä, PDF:iä, kehotevälimuistia ja työkalukutsuja. Jos sinulla on kysyttävää, ota milloin tahansa yhteyttä tekniseen tukitiimiimme. diff --git a/fi/guides/openai/openai_embeddings.mdx b/fi/guides/openai/openai_embeddings.mdx index 5bf1a4a3c..26a92fff2 100644 --- a/fi/guides/openai/openai_embeddings.mdx +++ b/fi/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API - Hakeminen ja käyttö" +title: "OpenAI Embeddings API:n hakeminen ja käyttö" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI sanavektoripalvelu, joka tuottaa syötetyn tekstin sanavektorituloksia. +OpenAI-sana-vektoripalvelu, jota käytetään syötetyn tekstin sana-vektoritulosten luomiseen. -Tässä asiakirjassa esitellään OpenAI Embeddings API:n käyttöprosessi, jonka avulla voimme luoda syötetyn tekstin upotussanoja. +Tässä dokumentissa esitellään pääasiassa OpenAI Embeddings API:n käyttöprosessi, jonka avulla voimme luoda syötetyn tekstin esitystä vastaavia upotusvektoreita。。 ## Hakuprosessi -Käyttääksesi OpenAI Embeddings API:a, sinun on ensin mentävä [Ace Data Cloud -hallintapaneeliin](https://platform.acedata.cloud/console/applications) saadaksesi API-tokenisi, jota voit käyttää myöhemmin. +Jotta voit käyttää OpenAI Embeddings API:a, hanki ensin API Tokenisi [Ace Data Cloud -konsolista](https://platform.acedata.cloud/console/applications) ja säästä se myöhempää käyttöä varten. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Jos et ole vielä kirjautunut sisään tai rekisteröitynyt, sinut ohjataan automaattisesti kirjautumissivulle, jossa sinua kutsutaan rekisteröitymään ja kirjautumaan sisään, ja sen jälkeen sinut ohjataan takaisin nykyiselle sivulle. +Jos et ole vielä kirjautunut sisään tai rekisteröitynyt, sinut ohjataan automaattisesti kirjautumissivulle rekisteröitymään ja kirjautumaan sisään, minkä jälkeen palaat automaattisesti tälle sivulle. -**Yksi API-token riittää kaikkien palveluiden kutsumiseen, eikä jokaiselle palvelulle tarvitse hakea erikseen.** Ensimmäisellä hakemuksella saat ilmaisen käyttöoikeuden, jonka avulla voit kokeilla palvelua ilmaiseksi; jos käyttöoikeus loppuu, voit ladata yleistä saldoa [hallintapaneelista](https://platform.acedata.cloud/console/coin). +**Yhdellä API Tokenilla voi kutsua kaikkia alustan palveluita, eikä jokaista palvelua varten tarvitse hakea erikseen.** Ensimmäisellä hakukerralla saat ilmaista saldoa, jolla voit kokeilla palvelua maksutta; jos saldo ei riitä, voit ladata yleissaldoa [konsolissa](https://platform.acedata.cloud/console/coin). -> 📘 Täydellinen asiakirja: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) +> 📘 Täydellinen dokumentaatio: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) ## Peruskäyttö -Seuraavaksi voit täyttää vastaavat tiedot käyttöliittymässä, kuten kuvassa näkyy: +Seuraavaksi voit täyttää käyttöliittymässä vastaavat tiedot, kuten kuvassa näkyy:

-Kun käytät tätä rajapintaa ensimmäistä kertaa, sinun on täytettävä vähintään kolme tietoa: yksi on `authorization`, jonka voit valita suoraan pudotusvalikosta. Toinen parametri on `model`, `model` on se, mitä valitsemme käytettäväksi OpenAI:n verkkosivuston malliluokista, täällä meillä on pääasiassa 3 erilaista mallia, lisätietoja voit katsoa tarjoamistamme malleista. Viimeinen parametri on `input`, `input` on se teksti, jonka haluamme muuntaa sanavektoriksi. +Kun käytät tätä rajapintaa ensimmäistä kertaa, meidän on täytettävä vähintään kolme kohtaa. Yksi niistä on `authorization`, jonka voi valita suoraan pudotusvalikosta. Toinen parametri on `model`; `model` tarkoittaa OpenAI:n virallisilta verkkosivuilta valitsemaamme malliluokkaa. Tällä hetkellä käytettävissä olevat mallit ovat `text-embedding-3-small` ja `text-embedding-3-large`. Mallia `text-embedding-ada-002` ei enää tarjota; jos olemassa oleva vektori-indeksi käyttää tätä vanhaa mallia, uuden mallin vektoreita ei voi suoraan käyttää yhdessä sen kanssa, vaan indeksi on rakennettava uudelleen. Viimeinen parametri on `input`; `input` on teksti, joka meidän on muunnettava sanavektoriksi. -Voit myös huomata, että oikealla puolella on vastaava kutsukoodin generointi, voit kopioida koodin ja suorittaa sen suoraan tai voit napsauttaa "Try" -painiketta testataksesi. +Samalla voit huomata, että oikealla puolella luodaan vastaava kutsukoodi. Voit kopioida koodin ja suorittaa sen suoraan tai testata sitä suoraan napsauttamalla 「Try」-painiketta. Valinnaiset parametrit: -- `dimensions`: leikkaa vektorin ulottuvuudet, oletusarvoisesti tulostaa täydet ulottuvuudet. -- `encoding_format`: palautusmuoto, valinnaisesti `float` tai `base64`. +- `dimensions`: rajaa vektorin ulottuvuudet, oletuksena tulostetaan täydet ulottuvuudet. +- `encoding_format`: palautusmuoto, vaihtoehdot ovat `float` tai `base64`.

-Python-esimerkkikutsukoodi: +Python-esimerkkikutsu: ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Kutsun jälkeen huomaamme, että palautustulos on seuraava: +Kutsun jälkeen havaitsemme, että palautettu tulos on seuraava: ```json { @@ -97,7 +97,7 @@ Kutsun jälkeen huomaamme, että palautustulos on seuraava: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,25 +105,25 @@ Kutsun jälkeen huomaamme, että palautustulos on seuraava: } ``` -Palautustuloksessa on useita kenttiä, jotka esitellään seuraavasti: +Palautetussa tuloksessa on useita kenttiä, jotka esitellään seuraavasti: -- `model`, malli, jota käytettiin tämän tekstin muuntamiseen sanavektoriksi. -- `usage`, token-tiedot, joita käytettiin tämän tekstin muuntamiseen sanavektoriksi. -- `data`, tekstin muuntamisen jälkeen saadut sanavektoritulokset. +- `model`, malli, jota käytetään tässä tekstin muuntamisessa sanavektoriksi. +- `usage`, token-tiedot, joita käytetään tässä tekstin muuntamisessa sanavektoriksi. +- `data`, tekstin muuntamisen jälkeinen sanavektoritulos. -`data` sisältää tekstin vastaavat sanavektoritiedot, ja sen sisällä `embedding` on luotujen sanavektorien tarkat tulokset. +Näistä `data` sisältää tekstin vastaavia sanavektoreita koskevat yksityiskohtaiset tiedot, ja sen `embedding` on luodun sanavektorin varsinainen tulos. -## Virheiden käsittely +## Virheenkäsittely -API:a kutsuttaessa, jos kohtaat virheitä, API palauttaa vastaavat virhekoodit ja tiedot. Esimerkiksi: +Kun API:a kutsuttaessa tapahtuu virhe, API palauttaa vastaavan virhekoodin ja tiedot. Esimerkiksi: -- `400 token_mismatched`: Huono pyyntö, mahdollisesti puuttuvien tai virheellisten parametrien vuoksi. -- `400 api_not_implemented`: Huono pyyntö, mahdollisesti puuttuvien tai virheellisten parametrien vuoksi. -- `401 invalid_token`: Valtuuttamaton, virheellinen tai puuttuva valtuutustoken. -- `429 too_many_requests`: Liikaa pyyntöjä, olet ylittänyt nopeusrajoituksen. -- `500 api_error`: Sisäinen palvelinvirhe, jotain meni pieleen palvelimella. +- `400 token_mismatched`: Virheellinen pyyntö, mahdollisesti puuttuvien tai virheellisten parametrien vuoksi. +- `400 api_not_implemented`: Virheellinen pyyntö, mahdollisesti puuttuvien tai virheellisten parametrien vuoksi. +- `401 invalid_token`: Ei valtuutusta, virheellinen tai puuttuva valtuutustunnus. +- `429 too_many_requests`: Liian monta pyyntöä, olet ylittänyt nopeusrajoituksen. +- `500 api_error`: Sisäinen palvelinvirhe, palvelimella tapahtui jotain virheellistä. -### Virhevastauksen esimerkki +### Esimerkki virhevastausta ```json { @@ -138,4 +138,4 @@ API:a kutsuttaessa, jos kohtaat virheitä, API palauttaa vastaavat virhekoodit j ## Johtopäätös -Tämän asiakirjan avulla olet oppinut, kuinka käyttää OpenAI Embeddings API:a ja hyödyntää virallista OpenAI:n sanavektorigenerointitoimintoa. Toivottavasti tämä asiakirja auttaa sinua paremmin yhdistämään ja käyttämään tätä API:a. Jos sinulla on kysymyksiä, ota rohkeasti yhteyttä tekniseen tukitiimiimme. +Tämän dokumentin avulla olet oppinut, kuinka OpenAI Embeddings API:a käytetään OpenAI:n virallisen sanavektorien luontitoiminnon hyödyntämiseen helposti. Toivomme, että tämä dokumentti auttaa sinua integroimaan ja käyttämään tätä API:a paremmin. Jos sinulla on kysyttävää, ota milloin tahansa yhteyttä tekniseen tukitiimiimme. diff --git a/fi/guides/platform/wework_bot.mdx b/fi/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..d28cc15a5 --- /dev/null +++ b/fi/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "WeCom-robotti" +description: "Platform API guide - Ace Data Cloud" +--- + +Ota käyttöön oma WeCom-tili-instanssisi, kirjaudu sisään skannaamalla QR-koodi WeCom-mobiilisovelluksella ja lue tiliä, yhteystietoja, keskusteluja ja paikallisesti synkronoituja viestejä REST API:n tai MCP:n kautta. Instanssi vastaa tavallista WeCom-tiliä, eikä yksityistä palvelinta tai yrityssähköpostin verkkotunnuksen määritystä tarvita. + +Tällä hetkellä Alpha-vaiheessa. Tilin luku on läpäissyt todellisen keskustelun varmennuksen; omien tekstiviestien lähetys ja tapahtumien takaisinluku ovat läpäisseet todellisen hyväksyntätestin; muut yhteystiedot, ryhmätoiminnot ja uusien instanssien palautus edellyttävät vielä käyttöönottotyöympäristön hyväksyntätestiä. Median lähetys, lainauksena vastaaminen, todellinen @-maininta, ryhmän jäsenten hallinta ja toimituskuittaukset eivät ole vielä käytettävissä. Käytä instanssin `/api/capabilities`-paluuarvoa ensisijaisena lähteenä. + +## Käyttöönotto ja kirjautuminen + +Ota palvelu käyttöön Deployment-luokassa ja valitse instanssin kestopaketti. Avaa käyttöönoton jälkeen hallintasivu ja skannaa QR-koodi tilin omalla WeCom-sovelluksella; jos tarvitaan puhelinvahvistusta tai muita kirjautumisvaiheita, avaa etätyöpöytä ja syötä kyseisen instanssin työpöytäsalasana. API-tunnistetiedot ja työpöytäsalasana ovat erillisiä. Kirjautumistiedot tallennetaan instanssin levylle; kontin uudelleenluonti säilyttää levyn, kun taas levyn poistaminen poistaa paikallisen istunnon. + +Jokaisesta instanssista veloitetaan erikseen, ja se toimii ostetun keston ajan. REST- / MCP-kutsuista ei veloiteta erikseen viestikohtaisesti, ja todellinen hinta määräytyy pakettisivun mukaan. Nykyinen oletusviite käyttää WeChat-robotin kestopaketteja, ja lopullinen hinnoittelu on vahvistettava käytettävien suoritusresurssien perusteella ennen lopullista julkaisua. + +## API ja MCP + +Käytä hallintasivulla olevaa instanssin API-osoitetta; kaikki tilirajapinnat sisältävät `Authorization: Bearer `. Nämä polut kuuluvat omaan instanssiin eivätkä jaettuun API-yhdyskäytävään. MCP-osoite on instanssin osoite lisättynä polulla `/mcp/`, ja se käyttää samaa Bearer-tokenia. + +| Rajapinta | Toiminto | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Onko tili valmis ja ominaisuusluettelo | +| `GET /api/auth/qr` | Nykyinen kirjautumisen QR-koodi PNG Base64-muodossa | +| `GET /api/account` | Nykyinen tili | +| `GET /api/contacts?kind=all` | Sisäiset kollegat ja ulkoiset yhteystiedot; voidaan määrittää internal / external | +| `GET /api/conversations` | Paikalliset keskustelut, alkuperäiset keskustelutunnukset säilytetään | +| `GET /api/messages` | Paikallisesti synkronoidut viestit; parametrit conversation_id, after_rowid, limit | +| `POST /api/search` | Yhteystietojen, keskustelujen ja paikallisen tekstin haku | +| `POST /api/messages` | Asynkroninen tekstinlähetystehtävä; Idempotency-Key on pakollinen | +| `POST /api/messages/send` | Sama lähetysrajapinta, tukee yhtä tai useampaa kohdetta | +| `GET /api/groups/{conversation_id}` | Paikallisesti synkronoidut ryhmätiedot ja jäsenet | +| `GET /api/tasks` | Viimeisimmät tehtävät ja kunkin kohteen tulokset | +| `GET /api/tasks/{id}` | Lähetystuloksen kysely | +| `POST /api/tasks/{id}/cancel` | Peruuta tehtävä, jota ei ole vielä aloitettu | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Keskeytä automaatio; jatka oman varmennuksen jälkeen | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Instanssin tila ja nykyinen näyttö, molemmat vaativat todennuksen | +| `GET /api/events?after=0` | Viestitapahtumat palautettavalla kursorilla | +| `WS /ws` | Viestitapahtumavirta, Bearer-todennus | + +Lähetysrakenne sisältää `target`-, `type: "text"`- ja `text`-kentät. `target` hyväksyy keskustelutunnuksen, yhteystietotunnuksen, yrityskäyttäjätunnuksen tai yksilöllisen täydellisen nimen; käytä ensisijaisesti tunnuksia; jos näyttönimi ei vieläkään yksilöi kohdetta, instanssi hylkää toiminnon eikä arvaa kohdetta. Yhteystiedolle, jolla ei ole paikallista keskustelua, avataan ensin keskustelu asiakkaassa, minkä jälkeen todellinen keskustelutunnus tarkistetaan ennen lähetystä. Pyyntöotsikon `Idempotency-Key` koostuu 8–128 kirjaimesta, numerosta tai merkistä `_.:-`. Saman toiminnon toistuvissa pyynnöissä on käytettävä samaa avainta ja samaa pyyntörunkoa. + +Korvaa `target` taulukolla `targets`, jotta viestejä voidaan lähettää sarjassa 1–50 yksiselitteisesti määritetylle kohteelle. Molempia ei voi antaa samanaikaisesti. Kaikkien kohteiden henkilöllisyys ratkaistaan ensin, ja samaan kohteeseen viittaavat eri aliakset hylätään. Jos jokin kohde epäonnistuu, myöhemmät lähetykset keskeytetään, ja tehtävän tulos kirjaa kohdekohtaisesti `succeeded`, `failed`, `unknown` tai `not_attempted`; älä pidä osittaista onnistumista täydellisenä onnistumisena. Tämä prosessi edellyttää vielä määritettyjen yhteystietojen todellista hyväksyntätestiä käyttöönottotyöympäristössä. + +Tehtävät voivat olla tilassa queued, running, submitting, succeeded, failed, unknown tai cancelled. `succeeded` tarkoittaa, että lähetyksen jälkeen vastaavan keskustelun tietueesta löytyi täsmällinen teksti ja palvelimen viestitunnus; `delivered` on edelleen null, eikä se tarkoita, että vastaanottaja olisi saanut viestin. unknown tarkoittaa, että tulos on epäselvä; tarkista historia äläkä lähetä uudelleen uudella avaimella. Instanssi ei lähetä keskeytyneitä tehtäviä automaattisesti uudelleen. + +Historia sisältää vain sisällön, jonka asiakas on jo synkronoinut, eikä se voi taata koko historiaa. Muut kuin tekstiviestit voivat palauttaa tyypin unknown, eikä liitteiden lataaminen ole vielä käytettävissä. Tapahtumat säilyttävät viimeisimmät 10 000 tietuetta, ja `gap` tarkoittaa, että kursori on ylittänyt säilytysikkunan. Ensimmäinen yhteys ei toista vanhaa historiaa uusina viesteinä. + +Viestihistorian `server_accepted` ja `server_id` voidaan käyttää sen tarkistamiseen, onko palvelin hyväksynyt paikallisen viestin; jos näkyvissä on vain paikallinen tietue ilman palvelintunnusta, lähetystä ei voida katsoa onnistuneeksi. Nämä kentät eivät tarkoita, että vastaanottaja olisi vastaanottanut tai lukenut viestin. Tapahtumatietueet säilyttävät luontihetken tilan; kysy nykyinen vahvistustila viestihistoriarajapinnasta. + +## Tili ja tunnistetiedot + +Kirjaudu sisään vain tilille, jonka käyttöön sinulla on oikeus. Määritä API-token luotettuun sovellukseen; se voi käyttää kyseisen instanssin tilitietoja. Älä julkaise salasanoja, QR-koodeja tai keskustelujen kuvakaappauksia julkisissa paikoissa. Instanssin keskeyttäminen katkaisee reaaliaikaiset tapahtumat. Tililtä uloskirjautumisen tai laitteen poistamisen jälkeen mobiilisovelluksesta on kirjauduttava uudelleen sisään. + +Nykyinen tekstinsyöttö tukee vain yhtä riviä, ja rivinvaihdot hylätään nimenomaisesti ennen lähetystä. Kun asiakas vaatii turvavarmennusta tai uudelleenkirjautumista, tilin omistajan on suoritettava se etätyöpöydällä; instanssi ei ohita varmennusta. Varmennuksen keskeyttämät tehtävät voivat palauttaa arvon unknown; kysy ensin viestitietueita äläkä lähetä uudelleen uudella idempotenssiavaimella. + +Kun turvavarmennuskehote, tililtä uloskirjautuminen tai muutos havaitaan, automaatiojono keskeytetään pysyvästi. Kun puhelinvahvistus on valmis, voit jatkaa vielä suorittamattomia tehtäviä instanssin konsolin toiminnolla ”Jatka varmennuksen jälkeen”; jo lähetettyjä tehtäviä, joiden tulos on epävarma, ei lähetetä uudelleen. Myös tavallinen etätyö voi laukaista WeComin turvavarmennuksen. Virallisissa ohjeissa mainittu 24 tunnin ikkuna, jonka aikana lukitusta ei enää tehdä varmennuksen jälkeen, ei tarkoita, että havaitseminen olisi poistunut, eikä se tarkoita, että instanssi voisi taata pitkäaikaisen valvomattoman käytön. diff --git a/fr/guides/claude/claude_messages.mdx b/fr/guides/claude/claude_messages.mdx index 475737151..2f2679bcf 100644 --- a/fr/guides/claude/claude_messages.mdx +++ b/fr/guides/claude/claude_messages.mdx @@ -3,41 +3,42 @@ title: "Demande et utilisation de l’API Claude Messages" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude est un système de conversation IA très puissant qui peut générer des réponses fluides et naturelles en quelques secondes seulement après avoir saisi une invite. L’API Claude Messages est le format d’API natif officiel d’Anthropic. Contrairement au format compatible avec OpenAI (Chat Completion), elle utilise la structure de requête et de réponse propre à Anthropic, ce qui permet de mieux exploiter les capacités uniques de Claude, telles que l’entrée de contenu multimodal, l’appel d’outils, la réflexion approfondie (Extended Thinking) et d’autres fonctionnalités avancées. +Anthropic Claude est un système de conversation IA très puissant qui peut générer des réponses fluides et naturelles en quelques secondes seulement à partir d’une invite. L’API Claude Messages est le format d’API natif officiel d’Anthropic. Contrairement au format compatible OpenAI (Chat Completion), elle utilise la propre structure de requête et de réponse d’Anthropic, permettant de mieux exploiter les capacités uniques de Claude, telles que l’entrée de contenu multimodal, l’appel d’outils, la réflexion approfondie (Extended Thinking) et d’autres fonctionnalités avancées. -Ce document présente principalement le processus d’utilisation des opérations de l’API Claude Messages. Grâce à elle, nous pouvons utiliser une interface native cohérente avec celle officielle d’Anthropic afin d’appeler les fonctionnalités de conversation de Claude. +Ce document présente principalement le processus d’utilisation des opérations de l’API Claude Messages. Grâce à elle, nous pouvons utiliser une interface native cohérente avec celle d’Anthropic officielle pour appeler les fonctionnalités conversationnelles de Claude. ## Processus de demande -Pour utiliser l’API Claude Messages, rendez-vous d’abord sur la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) pour obtenir votre API Token et le conserver pour une utilisation ultérieure. +Pour utiliser l’API Claude Messages, rendez-vous d’abord sur la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) afin d’obtenir votre API Token et conservez-le pour une utilisation ultérieure. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion afin de vous inviter à vous inscrire et vous connecter ; une fois terminé, vous reviendrez automatiquement sur la page actuelle. +Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion afin de vous inviter à vous inscrire et à vous connecter. Une fois terminé, vous reviendrez automatiquement sur la page actuelle. -**Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service.** Lors de la première demande, un quota gratuit est offert pour une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger le solde commun dans la [console](https://platform.acedata.cloud/console/coin). +**Un seul API Token permet d’appeler tous les services de la plateforme, sans devoir en demander un séparément pour chaque service.** La première demande offre un crédit gratuit permettant une expérience gratuite ; lorsque le crédit est insuffisant, vous pouvez recharger votre solde général dans la [console](https://platform.acedata.cloud/console/coin). -> 📘 Documentation complète : [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) +> 📘 Documentation complète : [API Claude Messages →](https://platform.acedata.cloud/documents/claude-messages) ## Utilisation de base -Le chemin de requête de l’API Claude Messages est `/v1/messages`, identique à l’API officielle d’Anthropic. Nous devons au minimum fournir trois paramètres obligatoires : +Le chemin de requête de l’API Claude Messages est `/v1/messages`, identique à celui de l’API officielle d’Anthropic. Nous devons fournir au minimum trois paramètres obligatoires : -- `model` : sélectionnez le modèle Claude à utiliser. `claude-opus-5-5` est fourni uniquement via l’API Messages, prend en charge 1 million de Tokens de contexte, un maximum de sortie de 128K Tokens, et active toujours la réflexion adaptative. Le dernier modèle phare est `claude-fable-5-1` (1 million de Tokens de contexte, maximum de sortie de 128K Tokens) ; l’ancien `claude-fable-5` reste compatible et conservé. `claude-sonnet-5-5` a rejoint l’interface de la série Messages native, prend en charge l’entrée d’images et la réflexion adaptative ; ses prix de référence officiels pour l’entrée, la sortie et la lecture du cache sont respectivement de 2, 10 et 0,20 dollars par million de Tokens. -- `messages` : le tableau des messages d’entrée, chaque message contenant `role` (rôle) et `content` (contenu), où `role` prend en charge `user` et `assistant`. -- `max_tokens` : le nombre maximal de tokens de sortie, utilisé pour limiter la longueur d’une réponse unique. +- `model` : sélectionne le modèle Claude à utiliser. `claude-opus-5-5` est uniquement disponible via l’API Messages, prend en charge un contexte d’un million de Token, une sortie maximale de 128K Token, et active toujours la réflexion adaptative. Le dernier modèle phare est `claude-fable-5-1` (contexte d’un million de Token, sortie maximale de 128K Token) ; l’ancien `claude-fable-5` reste compatible et conservé. `claude-sonnet-5-5` a rejoint l’interface de la série Messages native, prend en charge l’entrée d’images et la réflexion adaptative ; ses prix de référence officiels pour l’entrée, la sortie et la lecture du cache sont respectivement de 2, 10 et 0,20 dollars par million de Token. +- `messages` : le tableau des messages en entrée, chaque message contenant `role` (rôle) et `content` (contenu), où `role` prend en charge `user` et `assistant`. +- `max_tokens` : le nombre maximal de token en sortie, utilisé pour limiter la longueur d’une réponse unique. Paramètres optionnels courants : - `system` : l’invite système, utilisée pour définir le comportement et le rôle du modèle. - `temperature` : le caractère aléatoire de la génération, entre 0 et 1 ; plus la valeur est élevée, plus les réponses divergent. -- `stream` : indique s’il faut utiliser une réponse en flux ; le définir sur `true` permet un effet de retour mot par mot. -- `stop_sequences` : séquences d’arrêt personnalisées ; le modèle s’arrête de générer lorsqu’il rencontre ces textes. -- `top_p` : paramètre d’échantillonnage par noyau, qui contrôle le caractère aléatoire de la génération avec temperature. +- `stream` : indique si une réponse en flux est utilisée ; définie sur `true`, elle permet un retour caractère par caractère. +- `stop_sequences` : séquences d’arrêt personnalisées ; le modèle cesse de générer lorsqu’il rencontre ces textes. +- `top_p` : paramètre d’échantillonnage nucléaire, contrôlant le caractère aléatoire de la génération avec temperature. - `top_k` : échantillonne uniquement parmi les K options ayant les probabilités les plus élevées. -- `tools` : définitions d’outils, utilisées pour permettre au modèle d’appeler des fonctions externes. +- `tools` : définition des outils, utilisée pour permettre au modèle d’appeler des fonctions externes. - `tool_choice` : contrôle la manière dont le modèle utilise les outils fournis. - `cache_control` : crée automatiquement un point d’arrêt de cache au dernier bloc de contenu pouvant être mis en cache dans la requête ; peut également être écrit sur un bloc de contenu spécifique. +- `metadata` : objet de métadonnées de requête facultatif. `metadata.user_id` est une chaîne de caractères et peut transmettre l’identifiant utilisateur personnalisé de l’appelant, par exemple `{"user_id":"example-user-001"}` ; il est recommandé d’utiliser un identifiant stable ne contenant pas d’informations personnelles. Il ne remplace pas l’authentification `Authorization` et n’a pas besoin d’être écrit dans le contenu de conversation de `messages`. ### Exemple cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Après l’appel, le résultat renvoyé est le suivant : +Après l’appel, le résultat retourné est le suivant : ```json { @@ -106,25 +109,25 @@ Après l’appel, le résultat renvoyé est le suivant : } ``` -Description des champs du résultat renvoyé : - -- `id` : l’identifiant unique de ce message. -- `type` : toujours `message`. -- `role` : toujours `assistant`. -- `content` : le tableau du contenu de la réponse, chaque élément contenant `type` (tel que `text`) et le contenu correspondant. -- `model` : le nom du modèle qui traite la requête. -- `stop_reason` : la raison de l’arrêt. Les valeurs stables incluent `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (le contenu actuel de l’assistant peut être renvoyé tel quel pour continuer), `refusal` et `model_context_window_exceeded`. -- `stop_sequence` : si l’arrêt est dû à une séquence d’arrêt personnalisée, affiche le texte de la séquence d’arrêt correspondante. -- `stop_details` : lorsque `stop_reason` est `refusal`, peut contenir la catégorie et l’explication du refus. -- `usage` : statistiques d’utilisation des tokens. `input_tokens` correspond aux entrées non mises en cache ; `cache_creation_input_tokens` et `cache_read_input_tokens` correspondent respectivement à l’écriture et à la lecture du cache ; `output_tokens` est le nombre total de tokens de sortie. Si `output_tokens_details.thinking_tokens` est renvoyé, cette valeur est un sous-ensemble de `output_tokens` ; ne l’ajoutez pas de nouveau lors du calcul du total ou du coût. Ce détail peut être `null` ou omis lorsqu’aucun comptage faisant autorité n’est disponible. -- `usage.cache_creation` : détail facultatif du TTL d’écriture du cache, contenant `ephemeral_5m_input_tokens` et `ephemeral_1h_input_tokens`. Lorsque l’objet existe, la somme des deux est égale à `cache_creation_input_tokens` ; un champ à `null` ou omis indique qu’aucune ventilation TTL n’est disponible dans la réponse actuelle et ne doit pas être interprété comme `0`. -- `usage.cost` : les réponses non diffusées en flux peuvent inclure un objet de consommation de quota enregistré par Ace Data Cloud, où `amount` est la consommation réelle de cette requête, `currency` est l’unité de mesure, et `list_amount` est le montant avant réduction (le cas échéant). Le prix de base officiel de lecture du cache de Fable 5.1 est de 0,25 $/million de Tokens, et les prix de base d’écriture du cache de 5 minutes et de 1 heure sont respectivement de 12,50 $ et 20 $/million de Tokens ; les prix réels de la plateforme sont convertis selon les remises du forfait. +Description des champs du résultat retourné : +- `id`：l’identifiant unique de ce message. +- `type`：toujours `message`. +- `role`：toujours `assistant`. +- `content`：tableau du contenu de la réponse, chaque élément contenant `type` (tel que `text`) et le contenu correspondant. +- `model`：le nom du modèle qui traite la requête. +- `stop_reason`：la raison de l’arrêt. Les valeurs stables incluent `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (vous pouvez renvoyer tel quel le contenu actuel de l’assistant afin de continuer), `refusal` et `model_context_window_exceeded`. +- `stop_sequence`：si l’arrêt est dû à une séquence d’arrêt personnalisée, affiche le texte de la séquence d’arrêt correspondante. +- `stop_details`：lorsque `stop_reason` vaut `refusal`, peut contenir la catégorie et l’explication du refus. +- `usage`：statistiques d’utilisation des tokens. `input_tokens` correspond à l’entrée non mise en cache ; `cache_creation_input_tokens` et `cache_read_input_tokens` correspondent respectivement à l’écriture et à la lecture du cache ; `output_tokens` correspond au nombre total de tokens de sortie. Si `output_tokens_details.thinking_tokens` est renvoyé, cette valeur est un sous-ensemble de `output_tokens` et ne doit pas être ajoutée une nouvelle fois lors du calcul du total ou du coût. Ce détail peut être `null` ou omis lorsqu’aucun comptage faisant autorité n’est disponible. +- `usage.cache_creation`：détail optionnel du TTL d’écriture du cache, incluant `ephemeral_5m_input_tokens` et `ephemeral_1h_input_tokens`. Lorsque l’objet est présent, la somme des deux est égale à `cache_creation_input_tokens` ; un champ à `null` ou omis indique qu’aucune ventilation TTL n’est disponible pour la réponse actuelle et ne doit pas être interprété comme `0`. +- `usage.cost`：les réponses non diffusées en streaming peuvent inclure un objet de consommation de crédits enregistré par Ace Data Cloud, où `amount` correspond à la consommation réelle de cette requête, `currency` est l’unité de mesure, et `list_amount` est le montant avant remise (le cas échéant). Le prix officiel de base de lecture du cache de Fable 5.1 est de 0,25 $/million de tokens, et les prix de base d’écriture du cache de 5 minutes et 1 heure sont respectivement de 12,50 $ et 20 $/million de tokens ; les prix réels de la plateforme sont convertis selon les remises du forfait. ## Invite système -L’API Claude Messages prend en charge la définition d’une invite système via le champ `system`, utilisée pour définir le comportement, le rôle et le contexte du modèle. +L’API Claude Messages prend en charge la définition d’invites système via le champ `system`, utilisées pour définir le comportement, le rôle et le contexte du modèle. ### Exemple Python + ```python import requests @@ -149,11 +152,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -En définissant l’invite `system`, vous pouvez contrôler précisément le rôle et le comportement de Claude. +En définissant l’invite `system`, il est possible de contrôler précisément le rôle et le comportement de Claude. -## Réponse en flux +## Réponse en streaming -Cette interface prend également en charge les réponses en flux ; définissez le paramètre `stream` sur `true` pour obtenir un retour progressif, ce qui convient parfaitement à l’implémentation d’un affichage caractère par caractère sur une page web. +Cette interface prend également en charge les réponses en streaming : définissez le paramètre `stream` sur `true` afin d’obtenir un retour progressif, ce qui convient parfaitement à l’implémentation d’un affichage caractère par caractère sur une page web. ### Exemple Python @@ -183,14 +186,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Les réponses en flux sont renvoyées au format Server-Sent Events (SSE), chaque ligne étant préfixée par `event:` et `data:`. Les types d’événements en flux incluent : +Les réponses en streaming sont renvoyées au format Server-Sent Events (SSE), chaque ligne étant préfixée par `event:` et `data:`. Les types d’événements de streaming incluent : -- `message_start` : début du message, contenant les informations de base du message et le nom du modèle. -- `content_block_start` : début du bloc de contenu. -- `content_block_delta` : mise à jour incrémentielle du bloc de contenu, contenant les nouveaux fragments de texte générés. -- `content_block_stop` : fin du bloc de contenu. -- `message_delta` : mise à jour incrémentielle au niveau du message, contenant `stop_reason` et les informations finales de `usage`. La valeur de référence de `output_tokens_details.thinking_tokens` ne doit être lue que depuis le dernier `message_delta.usage`, sans être cumulée entre les événements. -- `message_stop` : fin du message. +- `message_start`：début du message, incluant les informations de base du message et le nom du modèle. +- `content_block_start`：début du bloc de contenu. +- `content_block_delta`：mise à jour incrémentielle du bloc de contenu, incluant le fragment de texte nouvellement généré. +- `content_block_stop`：fin du bloc de contenu. +- `message_delta`：mise à jour incrémentielle au niveau du message, incluant `stop_reason` et les informations finales de `usage`. La valeur faisant autorité de `output_tokens_details.thinking_tokens` doit uniquement être lue à partir du dernier `message_delta.usage`, et ne doit pas être cumulée entre les événements. +- `message_stop`：fin du message. L’effet de sortie est le suivant : @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Comme vous pouvez le voir, l’événement `content_block_delta` dans la réponse en flux contient le contenu textuel généré progressivement ; en concaténant tous les `text_delta`, vous pouvez obtenir la réponse complète. +On peut voir que, dans les réponses en streaming, l’événement `content_block_delta` contient le contenu textuel généré progressivement ; il suffit de concaténer tous les `text_delta` pour obtenir la réponse complète. ### Exemple JavaScript @@ -253,7 +256,7 @@ while (true) { ## Conversation à plusieurs tours -Si vous souhaitez intégrer une fonctionnalité de conversation à plusieurs tours, vous devez alterner les messages des rôles `user` et `assistant` dans le tableau `messages`, et transmettre également l’historique des conversations précédentes. +Si vous souhaitez intégrer une fonctionnalité de conversation à plusieurs tours, vous devez alterner les messages aux rôles `user` et `assistant` dans le tableau `messages`, et transmettre ensemble l’historique des conversations précédentes. ### Exemple Python @@ -282,8 +285,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Le résultat renvoyé est le suivant : - +Le résultat retourné est le suivant : ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ Le résultat renvoyé est le suivant : } ``` -En transmettant l’historique complet de la conversation dans `messages`, Claude peut fournir des réponses précises en tenant compte du contexte. +En transmettant l'historique complet de la conversation dans `messages`, Claude peut fournir des réponses précises en tenant compte du contexte. -## Modèle de réflexion approfondie +## Modèles de réflexion approfondie -Le thinking et le thinking summary de Claude sont deux concepts différents : le modèle peut effectuer un raisonnement interne, mais l’API ne renvoie pas la chaîne de pensée brute. Lorsqu’il est nécessaire d’afficher le processus de raisonnement, l’API renvoie un résumé traité. +Le thinking et le thinking summary de Claude sont deux concepts différents : le modèle peut effectuer un raisonnement interne, mais l'API ne renvoie pas la chaîne de pensée brute. Lorsqu'il est nécessaire d'afficher le processus de raisonnement, l'API renvoie un résumé traité. -Il est actuellement recommandé d’utiliser adaptive thinking et de contrôler l’investissement global de raisonnement via `output_config.effort` : +Les modèles actuels recommandent d'utiliser l'adaptive thinking, et de contrôler l'investissement global dans le raisonnement via `output_config.effort` : ```python import requests @@ -350,24 +352,25 @@ Le bloc thinking dans la réponse se présente comme suit : "signature": "opaque-signature" } ``` -- `display: "summarized"` renvoie un résumé lisible de la réflexion ; ce n’est pas la chaîne de pensée brute. -- `display: "omitted"` renvoie `thinking: ""`, tout en conservant une `signature` opaque pour prendre en charge les conversations ultérieures. -- `display: "updates"` est le mode bêta d’Anthropic, qui nécessite d’inclure `anthropic-beta: thinking-display-updates-2026-08-18`. La définition officielle consiste à masquer le texte du raisonnement et à afficher de brèves mises à jour de progression entre les appels d’outils. La plateforme transmet ce paramètre et cet en-tête de requête bêta tels quels, et ne les réécrit pas de force en `summarized` ; le contenu réel de la sortie dépend de la prise en charge du modèle sélectionné. -- `thinking`, `output_config`, effort, les paramètres d’échantillonnage et les nouveaux champs d’extension sont transmis tels quels. La plateforme ne maintient pas d’énumérations de valeurs ni de restrictions de combinaison codées en dur par modèle, et ne réécrit pas automatiquement le mode thinking ; le modèle sélectionné détermine s’il accepte ces paramètres, et les erreurs de paramètres renvoyées par le modèle sont retransmises au client. -- Les valeurs par défaut de display pour Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 et Opus 4.7 sont `omitted` ; Opus 4.6, Sonnet 4.6 et les modèles antérieurs prenant en charge thinking utilisent `summarized` par défaut. -- Display affecte uniquement le contenu renvoyé et la latence en streaming ; il ne désactive pas le raisonnement et ne réduit pas la facturation des tokens thinking. -- L’activation par défaut de thinking et la valeur par défaut de display sont deux questions indépendantes. Opus 5 et Sonnet 5 activent adaptive thinking par défaut ; pour Opus 5, omettre `thinking` équivaut à adaptive, et omettre `output_config.effort` équivaut à `high`. Opus 4.8, 4.7 et 4.6 nécessitent une activation explicite. -- Thinking et le texte final partagent le budget de sortie `max_tokens`. Si le budget est trop faible, thinking peut consommer la majeure partie de l’allocation, laissant le texte vide ou tronqué ; augmentez `max_tokens`, ou utilisez l’effort `low` / `medium` pour contrôler l’investissement de raisonnement. -- Pour les modèles permettant de désactiver thinking, vous pouvez transmettre `thinking: {"type":"disabled"}`. Les nouveaux modes tels que `between_tools` ainsi que les combinaisons d’effort dépendent du modèle sélectionné ; la plateforme ne les rejette pas à l’avance selon les anciennes règles de modèle. -- Un budget de réflexion fixe peut être transmis via `budget_tokens` ; les nouveaux modèles utilisent généralement `thinking.type=adaptive` et `output_config.effort`. La prise en charge d’un budget fixe ou de la désactivation de la réflexion dépend des capacités actuelles du modèle sélectionné. -- Lors de conversations multi-tours et d’appels d’outils, vous devez renvoyer tels quels le bloc thinking complet et la signature retournés par l’assistant ; ne modifiez pas et ne générez pas vous-même la signature. + +- `display: "summarized"` renvoie un résumé de réflexion lisible ; il ne s'agit pas de la chaîne de pensée brute. +- `display: "omitted"` renvoie `thinking: ""`, tout en conservant l'`signature` opaque pour prendre en charge les conversations ultérieures. +- `display: "updates"` est le mode beta d'Anthropic et nécessite `anthropic-beta: thinking-display-updates-2026-08-18`. La définition officielle est de masquer le corps du raisonnement et d'afficher de brèves mises à jour de progression entre les appels d'outils. La plateforme transmet ce paramètre et l'en-tête de requête beta tels quels, sans forcer leur réécriture en `summarized` ; le contenu réel de la sortie dépend de la prise en charge du modèle sélectionné. +- `thinking`, `output_config`, effort, les paramètres d'échantillonnage et les nouveaux champs d'extension sont transmis tels quels. La plateforme ne maintient pas d'énumérations de valeurs codées en dur par modèle ni de restrictions de combinaison, et ne réécrit pas automatiquement le mode thinking ; l'acceptation de ces paramètres est déterminée par le modèle sélectionné, et les erreurs de paramètres renvoyées par le modèle sont transmises au client. +- La valeur par défaut de display pour Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 et Opus 4.7 est `omitted` ; les modèles Opus 4.6, Sonnet 4.6 et les modèles antérieurs prenant en charge thinking utilisent par défaut `summarized`. +- Display affecte uniquement le contenu retourné et la latence du streaming ; il ne désactive pas le raisonnement et ne réduit pas la facturation des thinking tokens. +- L'activation par défaut de thinking et la valeur par défaut de display sont deux questions distinctes. Opus 5 et Sonnet 5 activent adaptive thinking par défaut ; pour Opus 5, omettre `thinking` équivaut à adaptive, et omettre `output_config.effort` équivaut à `high`. Opus 4.8, 4.7 et 4.6 nécessitent une activation explicite. +- Thinking et le texte final partagent le budget de sortie de `max_tokens`. Si le budget est trop faible, thinking peut utiliser la majeure partie du quota, laissant le texte vide ou tronqué ; veuillez augmenter `max_tokens`, ou utiliser l'effort `low` / `medium` pour contrôler l'investissement dans le raisonnement. +- Pour les modèles qui permettent de désactiver thinking, vous pouvez transmettre `thinking: {"type":"disabled"}`. Les nouveaux modes tels que `between_tools` ainsi que les combinaisons d'effort dépendent du modèle sélectionné ; la plateforme ne les rejette pas à l'avance selon les anciennes règles de modèles. +- Un budget de réflexion fixe peut être transmis via `budget_tokens` ; les nouveaux modèles utilisent généralement `thinking.type=adaptive` et `output_config.effort`. La prise en charge d'un budget fixe ou de la désactivation de la réflexion dépend des capacités actuelles du modèle sélectionné. +- Lors de conversations multi-tours et d'appels d'outils, le bloc thinking complet et la signature renvoyés par l'assistant doivent être retransmis tels quels ; ne modifiez pas et ne générez pas vous-même de signature. - La transmission transparente des paramètres ne signifie pas que chaque modèle prend en charge toutes les fonctionnalités. Les appels inter-protocoles nécessitent toujours une conversion, et la prise en charge ainsi que les erreurs pour des contenus tels que `redacted_thinking` sont déterminées par le service de modèle qui traite réellement la requête. Dans les requêtes en streaming, `summarized` produit `thinking_delta` ; `omitted` ne produit pas `thinking_delta`, et conserve uniquement le cycle de vie du bloc thinking et `signature_delta`. ## Modèles visuels -Claude prend en charge les entrées multimodales et peut traiter simultanément du texte et des images. Dans l’API Messages, les capacités visuelles peuvent être utilisées en définissant `content` au format tableau et en transmettant des blocs de contenu d’image. +Claude prend en charge les entrées multimodales et peut traiter simultanément du texte et des images. Dans l'API Messages, les capacités visuelles peuvent être utilisées en définissant `content` au format tableau et en transmettant des blocs de contenu image. ### Utiliser des images encodées en Base64 @@ -456,7 +459,6 @@ print(response.json()) ``` ### Exemple cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -519,11 +521,11 @@ payload = { } ``` -La source URL s’écrit `{"type":"url","url":"https://example.com/report.pdf"}`. `document` prend également en charge `text/plain` et les sources `content` composées de blocs text/image ; les champs facultatifs incluent `title`, `context` et `citations`. La source `file_id` de l’API Files est une fonctionnalité bêta distincte et ne fait pas partie du contrat stable de cette interface. +Les sources URL s’écrivent sous la forme `{"type":"url","url":"https://example.com/report.pdf"}`. `document` prend également en charge `text/plain` et les sources `content` composées de blocs text/image ; les champs facultatifs incluent `title`, `context` et `citations`. La source `file_id` de l’API Files est une fonctionnalité bêta indépendante et ne fait pas partie du contrat stable de cette interface. -## Cache de prompts +## Mise en cache des prompts -Le `cache_control` de niveau supérieur place automatiquement le point d’arrêt du cache sur le dernier bloc pouvant être mis en cache : +Le `cache_control` de niveau supérieur place automatiquement le point de rupture du cache sur le dernier bloc pouvant être mis en cache : ```python payload = { @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Lorsqu’un contrôle précis de la position est nécessaire, vous pouvez également écrire le même `cache_control` sur les blocs de contenu text, image, document, tool_use, tool_result ou sur les définitions d’outils. `ttl` prend en charge `5m` (par défaut) et `1h` ; veuillez utiliser `usage.cache_creation_input_tokens` et `usage.cache_read_input_tokens` pour déterminer l’écriture et les accès au cache. -Lorsque la réponse fournit `usage.cache_creation`, alors `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` est `null` ou omis, cela signifie qu’il n’existe que le volume total d’écritures en cache, sans ventilation TTL faisant autorité ; dans ce cas, ne considérez aucun bucket comme étant connu à 0, la facturation et les totaux restent basés sur le champ aggregate. +Lorsqu’un contrôle précis de la position est nécessaire, le même `cache_control` peut également être écrit sur les blocs de contenu text, image, document, tool_use, tool_result ou sur les définitions d’outils. `ttl` prend en charge `5m` (par défaut) et `1h` ; veuillez utiliser `usage.cache_creation_input_tokens` et `usage.cache_read_input_tokens` pour déterminer l’écriture dans le cache et les accès au cache. + +Lorsque la réponse fournit `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Si `cache_creation` est `null` ou omis, cela indique qu’il n’existe qu’un total des écritures dans le cache, sans ventilation TTL faisant autorité ; dans ce cas, ne considérez aucun bucket comme étant à 0 connu, et la facturation ainsi que les totaux restent basés sur le champ agrégé. -Exemple de résultat retourné : +Exemple de résultat renvoyé : ```json { @@ -563,7 +566,7 @@ Exemple de résultat retourné : ## Appel d’outils (Tool Use) -L’API Claude Messages prend nativement en charge les appels d’outils, permettant au modèle d’appeler vos outils/fonctions prédéfinis lorsque nécessaire. +L’API Claude Messages prend nativement en charge la fonctionnalité d’appel d’outils, permettant au modèle d’appeler vos outils/fonctions prédéfinis lorsque nécessaire. ### Exemple Python @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Lorsque le modèle décide d’appeler un outil, le `content` du résultat retourné contient un bloc de contenu de type `tool_use` : +Lorsque le modèle décide d’appeler un outil, le `content` dans le résultat renvoyé inclut un bloc de contenu de type `tool_use` : ```json { @@ -637,7 +640,7 @@ Lorsque le modèle décide d’appeler un outil, le `content` du résultat retou } ``` -Notez que `stop_reason` est `tool_use`, ce qui indique que le modèle doit appeler un outil. Après avoir reçu ce résultat, vous devez exécuter la fonction outil et renvoyer le résultat au modèle sous la forme d’un `tool_result` : +Notez que `stop_reason` est `tool_use`, ce qui indique que le modèle doit appeler un outil. Après avoir reçu ce résultat, vous devez exécuter la fonction outil et renvoyer le résultat au modèle sous la forme de `tool_result` : ```python payload = { @@ -691,33 +694,32 @@ Le modèle générera une réponse finale en langage naturel sur la base du rés Ace Data Cloud fournit simultanément deux formats d’API Claude, dont les principales différences sont les suivantes : -Le `usage.input_tokens` de l’API Messages représente uniquement les entrées non mises en cache ; `cache_read_input_tokens` et `cache_creation_input_tokens` sont des buckets de facturation indépendants ; les trois sont calculés séparément selon les tarifs correspondants. - -| Caractéristique | API Messages (`/v1/messages`) | API Chat Completion (`/v1/chat/completions`) | +Dans l’API Messages, `usage.input_tokens` représente uniquement les entrées non mises en cache, tandis que `cache_read_input_tokens` et `cache_creation_input_tokens` sont des catégories de facturation indépendantes ; les trois sont calculés séparément selon les prix correspondants. +| Fonctionnalité | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Format | Format natif Anthropic | Format compatible OpenAI | -| Invite système | Champ `system` indépendant | Transmise via `role: "system"` dans `messages` | +| Invite système | Champ `system` indépendant | Transmis via `role: "system"` dans `messages` | | Structure de réponse | Tableau `content` (prend en charge plusieurs types) | Tableau `choices` (contient `message`) | -| Format de flux | Événements SSE (plusieurs types d’événements) | Lignes SSE `data` | -| Raisonnement approfondi | `thinking` natif et `output_config.effort` | Stratégie par défaut du modèle et paramètres compatibles | -| Appel d’outils | `tools` natif + `input_schema` | Format `tools` compatible OpenAI | -| Statistiques de tokens | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | +| Format de streaming | Événements SSE (plusieurs types d'événements) | Lignes SSE `data` | +| Raisonnement approfondi | `thinking` natif et `output_config.effort` | Stratégie par défaut du modèle et paramètres de compatibilité | +| Appels d'outils | `tools` natif + `input_schema` | Format `tools` compatible OpenAI | +| Statistiques Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Si votre système est déjà intégré à une API au format OpenAI, vous pouvez utiliser l’API Chat Completion pour effectuer une transition transparente. Si vous devez utiliser toutes les capacités natives de Claude, il est recommandé d’utiliser l’API Messages. +Si votre système est déjà intégré à une API au format OpenAI, vous pouvez utiliser la Chat Completion API pour basculer de manière transparente. Si vous avez besoin d'utiliser toutes les capacités natives de Claude, il est recommandé d'utiliser la Messages API. ## Gestion des erreurs -Les réponses d’erreur de l’interface publique utilisent l’envelope de la plateforme Ace Data Cloud : `error.code` est un code d’erreur stable, `error.message` est une description, et `trace_id` est utilisé pour diagnostiquer les requêtes. Les statuts HTTP courants incluent : +Les réponses d'erreur de l'interface publique utilisent l'enveloppe de la plateforme Ace Data Cloud : `error.code` est un code d'erreur stable, `error.message` est une description, et `trace_id` est utilisé pour diagnostiquer les requêtes. Les statuts HTTP courants incluent : -- `400` : les paramètres de la requête ou le contenu du protocole sont invalides. -- `401` : le jeton d’autorisation est invalide, absent ou expiré. -- `403` : accès interdit, solde insuffisant ou quota limité. -- `404` : l’API ou le modèle n’existe pas. -- `413` : le corps de la requête est trop volumineux. -- `429` : trop de requêtes. -- `500` / `503` / `504` : erreur de service, indisponibilité temporaire ou délai de traitement dépassé. +- `400` : Les paramètres de la requête ou le contenu du protocole sont invalides. +- `401` : Le jeton d'autorisation est invalide, manquant ou expiré. +- `403` : Accès interdit, solde insuffisant ou quota limité. +- `404` : L'API ou le modèle n'existe pas. +- `413` : Le corps de la requête est trop volumineux. +- `429` : Trop de requêtes. +- `500` / `503` / `504` : Erreur de service, indisponibilité temporaire ou délai de traitement dépassé. -### Exemple de réponse d’erreur +### Exemple de réponse d'erreur ```json { @@ -729,7 +731,8 @@ Les réponses d’erreur de l’interface publique utilisent l’envelope de la } ``` -Cette structure d’erreur constitue le contrat d’exécution d’Ace Data Cloud et n’est pas équivalente à l’envelope d’erreur officiel d’Anthropic ; veuillez la traiter selon le statut HTTP et `error.code`. +Cette structure d'erreur constitue le contrat d'exécution d'Ace Data Cloud et n'est pas équivalente à l'enveloppe d'erreur officielle d'Anthropic ; veuillez la traiter selon le statut HTTP et `error.code`. ## Conclusion -À travers ce document, vous avez déjà appris à utiliser l’API Claude Messages pour appeler les fonctionnalités conversationnelles de Claude au format natif d’Anthropic. L’API Messages prend en charge des fonctionnalités riches telles que les conversations de base, les prompts système, les réponses en streaming, les conversations à plusieurs tours, la réflexion approfondie, la compréhension visuelle, les PDF, la mise en cache des prompts et les appels d’outils. Si vous avez la moindre question, n’hésitez pas à contacter notre équipe de support technique. + +Grâce à ce document, vous avez appris à utiliser la Claude Messages API afin d'appeler les fonctionnalités conversationnelles de Claude au format natif Anthropic. La Messages API prend en charge de nombreuses fonctionnalités, telles que les conversations de base, les invites système, les réponses en streaming, les conversations multi-tours, le raisonnement approfondi, la compréhension visuelle, les PDF, la mise en cache des invites et les appels d'outils. Si vous avez des questions, veuillez contacter notre équipe de support technique à tout moment. diff --git a/fr/guides/openai/openai_embeddings.mdx b/fr/guides/openai/openai_embeddings.mdx index 890eedba0..42ffaded6 100644 --- a/fr/guides/openai/openai_embeddings.mdx +++ b/fr/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API demande et utilisation" +title: "Demande et utilisation de l’API OpenAI Embeddings" description: "OpenAI generation API guide - Ace Data Cloud" --- -Le service de vecteurs de mots d'OpenAI, utilisé pour générer des résultats de vecteurs de mots représentant le texte d'entrée. +Le service de vecteurs de mots OpenAI est utilisé pour générer des résultats de vecteurs de mots représentant le texte d’entrée. -Ce document présente principalement le processus d'utilisation de l'API OpenAI Embeddings, grâce à laquelle nous pouvons créer des vecteurs d'embedding représentant le texte d'entrée. +Ce document présente principalement le processus d’utilisation de l’API OpenAI Embeddings. Grâce à elle, nous pouvons créer des vecteurs d’intégration représentant le texte d’entrée. ## Processus de demande -Pour utiliser l'API OpenAI Embeddings, commencez par obtenir votre token API sur le [tableau de bord Ace Data Cloud](https://platform.acedata.cloud/console/applications) pour le garder en réserve. +Pour utiliser l’API OpenAI Embeddings, rendez-vous d’abord sur la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) pour obtenir votre API Token et le conserver en réserve. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Si vous n'êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion vous invitant à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle. +Si vous ne vous êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion afin de vous inviter à vous inscrire et à vous connecter ; une fois terminé, vous reviendrez automatiquement sur la page actuelle. -**Un seul token API suffit pour appeler tous les services de la plateforme, sans avoir besoin de demander séparément pour chaque service.** La première demande vous donnera un quota gratuit, vous permettant de l'essayer gratuitement ; si le quota est insuffisant, vous pouvez recharger le solde général dans le [tableau de bord](https://platform.acedata.cloud/console/coin). +**Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service.** La première demande offre un quota gratuit permettant une utilisation d’essai gratuite ; lorsque le quota est insuffisant, vous pouvez recharger le solde universel dans la [console](https://platform.acedata.cloud/console/coin). > 📘 Documentation complète : [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) ## Utilisation de base -Vous pouvez ensuite remplir le contenu correspondant sur l'interface, comme indiqué sur l'image : +Vous pouvez ensuite renseigner le contenu correspondant dans l’interface, comme indiqué sur l’image :

-Lors de la première utilisation de cette interface, nous devons remplir au moins trois éléments : l'un est `authorization`, que vous pouvez sélectionner directement dans la liste déroulante. L'autre paramètre est `model`, `model` est la catégorie de modèle que nous choisissons d'utiliser sur le site officiel d'OpenAI, ici nous avons principalement 3 types de modèles, les détails peuvent être consultés dans les modèles que nous fournissons. Le dernier paramètre est `input`, `input` est le texte de vecteur de mots que nous devons convertir. +Lors de la première utilisation de cette interface, nous devons remplir au moins trois éléments. Le premier est `authorization`, que vous pouvez sélectionner directement dans la liste déroulante. Un autre paramètre est `model` ; `model` correspond à la catégorie de modèle du site officiel d’OpenAI que nous choisissons d’utiliser. Les modèles actuellement disponibles sont `text-embedding-3-small` et `text-embedding-3-large`. `text-embedding-ada-002` n’est plus fourni ; si un index vectoriel existant utilise cet ancien modèle, les vecteurs des nouveaux modèles ne peuvent pas être mélangés directement avec lui et l’index doit être recréé. Le dernier paramètre est `input`, `input` étant le texte dont nous devons convertir les vecteurs de mots. -Vous pouvez également remarquer qu'il y a un code d'appel correspondant généré à droite, que vous pouvez copier et exécuter directement, ou vous pouvez simplement cliquer sur le bouton « Essayer » pour effectuer un test. +Vous pouvez également remarquer qu’un code d’appel correspondant est généré à droite ; vous pouvez copier le code et l’exécuter directement, ou cliquer directement sur le bouton « Try » pour effectuer un test. -Paramètres optionnels : +Paramètres facultatifs : -- `dimensions` : découper la dimension du vecteur, la sortie par défaut est la dimension complète. -- `encoding_format` : format de retour, optionnel `float` ou `base64`. +- `dimensions` : tronque les dimensions du vecteur, la dimension complète est renvoyée par défaut. +- `encoding_format` : format de retour, `float` ou `base64` au choix.

-Exemple de code d'appel Python : +Exemple de code d’appel Python : ```python import requests @@ -50,8 +50,8 @@ headers = { } payload = { - "input": "La nourriture était délicieuse et le serveur...", - "model": "text-embedding-ada-002", + "input": "The food was delicious and the waiter...", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Après l'appel, nous constatons que le résultat retourné est le suivant : +Après l’appel, nous constatons que le résultat renvoyé est le suivant : ```json { @@ -97,7 +97,7 @@ Après l'appel, nous constatons que le résultat retourné est le suivant : ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,32 +105,32 @@ Après l'appel, nous constatons que le résultat retourné est le suivant : } ``` -Le résultat retourné contient plusieurs champs, décrits comme suit : +Le résultat renvoyé comporte plusieurs champs, présentés ci-dessous : -- `model`, le modèle utilisé pour la conversion du texte en vecteur de mots. -- `usage`, les informations sur les tokens utilisés pour la conversion du texte en vecteur de mots. -- `data`, le résultat du vecteur de mots après conversion du texte. +- `model`, le modèle utilisé pour cette conversion de texte en vecteurs de mots. +- `usage`, les informations de token utilisées pour cette conversion de texte en vecteurs de mots. +- `data`, le résultat des vecteurs de mots après la conversion du texte. -Parmi eux, `data` contient des informations spécifiques sur le vecteur de mots correspondant au texte, où `embedding` est le résultat concret du vecteur de mots généré. +Parmi eux, `data` contient les informations spécifiques sur les vecteurs de mots correspondant au texte, et son `embedding` est le résultat concret des vecteurs de mots générés. ## Gestion des erreurs -Lors de l'appel de l'API, si une erreur se produit, l'API renverra le code d'erreur et les informations correspondantes. Par exemple : +Lors de l’appel de l’API, si une erreur survient, l’API renvoie le code et les informations d’erreur correspondants. Par exemple : -- `400 token_mismatched` : Mauvaise demande, probablement en raison de paramètres manquants ou invalides. -- `400 api_not_implemented` : Mauvaise demande, probablement en raison de paramètres manquants ou invalides. -- `401 invalid_token` : Non autorisé, token d'autorisation invalide ou manquant. -- `429 too_many_requests` : Trop de demandes, vous avez dépassé la limite de taux. -- `500 api_error` : Erreur interne du serveur, quelque chose s'est mal passé sur le serveur. +- `400 token_mismatched` : Mauvaise requête, possiblement en raison de paramètres manquants ou non valides. +- `400 api_not_implemented` : Mauvaise requête, possiblement en raison de paramètres manquants ou non valides. +- `401 invalid_token` : Non autorisé, token d’autorisation non valide ou manquant. +- `429 too_many_requests` : Trop de requêtes, vous avez dépassé la limite de débit. +- `500 api_error` : Erreur interne du serveur, un problème est survenu sur le serveur. -### Exemple de réponse d'erreur +### Exemple de réponse d’erreur ```json { "success": false, "error": { "code": "api_error", - "message": "échec de la récupération" + "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } @@ -138,4 +138,4 @@ Lors de l'appel de l'API, si une erreur se produit, l'API renverra le code d'err ## Conclusion -Grâce à ce document, vous avez compris comment utiliser l'API OpenAI Embeddings pour profiter facilement de la fonctionnalité de génération de vecteurs de mots d'OpenAI. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, n'hésitez pas à contacter notre équipe de support technique. +Grâce à ce document, vous avez compris comment utiliser facilement, avec l’API OpenAI Embeddings, la fonctionnalité officielle de génération de vecteurs de mots d’OpenAI. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, veuillez contacter à tout moment notre équipe de support technique. diff --git a/fr/guides/platform/wework_bot.mdx b/fr/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..a7b44a1b6 --- /dev/null +++ b/fr/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "Robot WeCom" +description: "Platform API guide - Ace Data Cloud" +--- + +Déployez votre propre instance de compte WeCom, connectez-vous en scannant le code avec l’application mobile WeCom, puis lisez le compte, les contacts, les conversations et les messages synchronisés localement via REST API ou MCP. L’instance correspond à un compte WeCom ordinaire, sans nécessiter de serveur privé ni de configuration de domaine d’e-mail d’entreprise. + +Actuellement en Alpha. La lecture du compte a terminé une validation sur des conversations réelles ; l’envoi de texte par le titulaire et la relecture des événements ont terminé une validation réelle ; les opérations sur les autres contacts, les groupes et la restauration de nouvelles instances doivent encore terminer la validation de l’environnement de déploiement. L’envoi de médias, les réponses avec citation, les véritables @, la gestion des membres de groupe et les accusés de réception ne sont pas encore ouverts. Veuillez vous référer à la valeur renvoyée par `/api/capabilities` de l’instance. + +## Déploiement et connexion + +Activez le service dans la catégorie Deployment et choisissez une formule de durée d’instance. Après le déploiement, ouvrez la page de gestion et utilisez le compte WeCom concerné pour scanner le code ; si une confirmation sur téléphone ou d’autres étapes de connexion sont requises, ouvrez le bureau à distance et saisissez le mot de passe de bureau de cette instance. Les identifiants API et le mot de passe de bureau sont indépendants. Les données de connexion sont enregistrées sur le disque de l’instance ; la reconstruction du conteneur conserve le disque ; la suppression du disque supprimera les sessions locales. + +Chaque instance est facturée indépendamment et fonctionne selon la durée achetée. Les appels REST / MCP ne sont pas facturés séparément par message ; le prix réel est celui affiché sur la page de la formule. La référence par défaut actuelle est la formule de durée des robots WeChat ; avant l’ouverture finale, la tarification doit être confirmée en fonction des ressources d’exécution. + +## API et MCP + +Utilisez l’adresse API de l’instance sur la page de gestion ; toutes les interfaces de compte doivent inclure `Authorization: Bearer `. Ces chemins appartiennent à l’instance dédiée et ne sont pas une passerelle API partagée. L’adresse MCP est l’adresse de l’instance suivie de `/mcp/`, avec le même token Bearer. + +| Interface | Fonction | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Disponibilité du compte et liste des capacités | +| `GET /api/auth/qr` | PNG Base64 du code QR de connexion actuel | +| `GET /api/account` | Compte actuel | +| `GET /api/contacts?kind=all` | Collègues internes et contacts externes ; internal / external peut être spécifié | +| `GET /api/conversations` | Conversations locales, conservation des ID de conversation d’origine | +| `GET /api/messages` | Messages synchronisés localement ; paramètres conversation_id, after_rowid, limit | +| `POST /api/search` | Recherche locale de contacts, de conversations et de texte | +| `POST /api/messages` | Tâche asynchrone d’envoi de texte ; Idempotency-Key est obligatoire | +| `POST /api/messages/send` | Même point d’entrée d’envoi, prend en charge une ou plusieurs cibles | +| `GET /api/groups/{conversation_id}` | Informations et membres des groupes synchronisés localement | +| `GET /api/tasks` | Tâches récentes et résultat de chaque cible | +| `GET /api/tasks/{id}` | Consulter le résultat d’envoi | +| `POST /api/tasks/{id}/cancel` | Annuler une tâche qui n’a pas encore commencé | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Mettre l’automatisation en pause ; reprendre après vérification par le titulaire | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | État de l’instance et écran actuel, tous deux nécessitent une authentification | +| `GET /api/events?after=0` | Événements de messages avec curseur récupérable | +| `WS /ws` | Flux d’événements de messages, authentification Bearer | + +Le corps d’envoi contient `target`, `type: "text"` et `text`. `target` accepte un ID de conversation, un ID de contact, un ID d’utilisateur d’entreprise ou un nom complet unique ; privilégiez les ID ; lorsqu’un nom affiché ne permet toujours pas une identification unique, l’instance refusera l’opération et ne devinera pas l’objet. Pour un contact sans conversation locale, le client ouvrira d’abord une conversation, puis enverra après avoir vérifié l’ID réel de la conversation. L’en-tête de requête `Idempotency-Key` contient 8 à 128 lettres, chiffres ou `_.:-`. Les requêtes répétées pour la même opération doivent réutiliser la même clé et le même corps de requête. + +Remplacez `target` par le tableau `targets` pour envoyer en série à 1–50 cibles explicitement spécifiées. Les deux ne peuvent pas être fournis simultanément. Toutes les cibles terminent d’abord la résolution d’identité ; différents alias pointant vers le même objet seront refusés. Après l’échec d’une cible, les envois suivants s’arrêtent ; le résultat de la tâche enregistre pour chaque élément `succeeded`, `failed`, `unknown` ou `not_attempted` ; ne considérez pas un succès partiel comme un succès total. Ce processus doit également terminer une validation réelle auprès des contacts désignés dans l’environnement de déploiement. + +Les tâches peuvent être dans l’état queued, running, submitting, succeeded, failed, unknown ou cancelled. `succeeded` signifie qu’après soumission, le texte exact et l’ID de message serveur ont été trouvés dans l’enregistrement de la conversation correspondante ; `delivered` reste null et ne signifie pas que l’autre partie l’a reçu. unknown signifie que le résultat n’est pas clair ; vérifiez l’historique et ne répétez pas l’envoi avec une nouvelle clé. L’instance ne renvoie pas automatiquement les tâches interrompues. + +L’historique ne contient que le contenu déjà synchronisé par le client et ne peut pas garantir l’intégralité de l’historique. Les messages non textuels peuvent renvoyer le type unknown ; le téléchargement des pièces jointes n’est pas encore ouvert. Les événements conservent les 10 000 plus récents ; `gap` indique que le curseur a dépassé la fenêtre de conservation. La première connexion ne rejouera pas l’ancien historique comme de nouveaux messages. + +`server_accepted` et `server_id` dans l’historique des messages peuvent être utilisés pour vérifier si le serveur a accepté le message local ; lorsqu’il n’existe qu’un enregistrement local sans ID serveur, l’envoi ne peut pas être considéré comme réussi. Ces champs ne signifient pas que le destinataire a reçu ou lu le message. Les enregistrements d’événements conservent l’état au moment de leur génération ; pour consulter l’état de confirmation actuel, utilisez l’interface d’historique des messages. + +## Compte et identifiants + +Connectez-vous uniquement à des comptes que vous êtes autorisé à utiliser. Configurez le token API dans des applications fiables ; il peut accéder aux données de compte de cette instance. Ne publiez pas les mots de passe, codes QR ou captures d’écran de conversation dans des lieux publics. Mettre l’instance en pause interrompra les événements en temps réel. Après la déconnexion du compte ou le retrait de l’appareil depuis le téléphone, vous devrez vous reconnecter. + +La saisie de texte actuelle ne prend en charge qu’une seule ligne ; les sauts de ligne seront explicitement refusés avant l’envoi. Lorsque le client exige une vérification de sécurité ou une nouvelle connexion, le titulaire du compte doit l’effectuer dans le bureau à distance ; l’instance ne contournera pas la vérification. Les tâches après une interruption de vérification peuvent renvoyer unknown ; consultez d’abord les enregistrements de messages, ne renvoyez pas avec une nouvelle clé d’idempotence. + +Lorsque des invites de vérification de sécurité, une déconnexion de compte ou des modifications sont détectées, la file d’automatisation sera mise en pause de manière persistante. Après avoir terminé la vérification sur téléphone, vous pouvez continuer les tâches non encore exécutées via « Reprendre après vérification » dans la console de l’instance ; les tâches déjà soumises mais dont le résultat est incertain ne seront pas renvoyées. Le travail à distance normal peut également déclencher la vérification de sécurité WeCom. La fenêtre indiquée officiellement selon laquelle aucun verrouillage ne se produit pendant 24 heures après la vérification ne signifie pas que la détection a été éliminée, ni que l’instance peut garantir un fonctionnement sans surveillance à long terme. diff --git a/it/guides/claude/claude_messages.mdx b/it/guides/claude/claude_messages.mdx index 1f300fb67..ccf2142ce 100644 --- a/it/guides/claude/claude_messages.mdx +++ b/it/guides/claude/claude_messages.mdx @@ -3,41 +3,42 @@ title: "Richiesta e utilizzo della Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude è un sistema di conversazione AI molto potente: basta inserire un prompt per generare risposte fluide e naturali in pochi secondi. La Claude Messages API è il formato API nativo ufficiale di Anthropic; diversamente dal formato compatibile con OpenAI (Chat Completion), adotta una struttura di richiesta e risposta proprietaria di Anthropic, consentendo di sfruttare meglio le capacità uniche di Claude, come l'input di contenuti multimodali, la chiamata di strumenti, il ragionamento approfondito (Extended Thinking) e altre funzionalità avanzate. +Anthropic Claude è un sistema di conversazione AI molto potente: basta inserire un prompt per generare risposte fluide e naturali in pochi secondi. Claude Messages API è il formato API nativo ufficiale di Anthropic; diversamente dal formato compatibile con OpenAI (Chat Completion), adotta la propria struttura di richieste e risposte di Anthropic, consentendo di sfruttare meglio le capacità uniche di Claude, come l'input di contenuti multimodali, la chiamata di strumenti, il ragionamento approfondito (Extended Thinking) e altre funzionalità avanzate. -Questo documento presenta principalmente il flusso di utilizzo delle operazioni della Claude Messages API; tramite essa possiamo utilizzare un'interfaccia nativa coerente con quella ufficiale di Anthropic per richiamare le funzionalità conversazionali di Claude. +Questo documento introduce principalmente il flusso di utilizzo delle operazioni della Claude Messages API. Utilizzandola, possiamo chiamare le funzionalità di conversazione di Claude tramite un'interfaccia nativa coerente con quella ufficiale di Anthropic. ## Procedura di richiesta -Per utilizzare la Claude Messages API, per prima cosa vai alla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token e conservalo come riserva. +Per utilizzare la Claude Messages API, per prima cosa vai alla [Console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token e conservalo per l'uso successivo. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Se non hai ancora effettuato l'accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per registrarti ed effettuare l'accesso; al termine, tornerai automaticamente alla pagina corrente. +Se non hai ancora effettuato l'accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per registrarti e accedere; una volta completato, tornerai automaticamente alla pagina corrente. -**Un solo API Token può richiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ogni servizio.** Alla prima richiesta verrà offerta una quota gratuita, utilizzabile per una prova gratuita; quando la quota non è sufficiente, puoi ricaricare il saldo generico nella [console](https://platform.acedata.cloud/console/coin). +**Un solo API Token consente di chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ciascun servizio.** La prima richiesta include crediti gratuiti, consentendo una prova gratuita; quando i crediti sono insufficienti, puoi ricaricare il saldo universale nella [console](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Utilizzo di base -Il percorso di richiesta della Claude Messages API è `/v1/messages`, coerente con l'API ufficiale di Anthropic. Dobbiamo fornire almeno tre parametri obbligatori: +Il percorso della richiesta della Claude Messages API è `/v1/messages`, coerente con l'API ufficiale di Anthropic. Dobbiamo fornire almeno tre parametri obbligatori: -- `model`: seleziona il modello Claude da utilizzare. `claude-opus-5-5` è disponibile solo tramite la Messages API, supporta un contesto di 1 milione di Token, un output massimo di 128K Token e abilita sempre il ragionamento adattivo. L'ultimo modello di punta è `claude-fable-5-1` (contesto di 1 milione di Token, output massimo di 128K Token); il precedente `claude-fable-5` resta compatibile e disponibile. `claude-sonnet-5-5` è stato aggiunto all'interfaccia della serie Messages nativa, supporta l'input di immagini e il ragionamento adattivo; i suoi prezzi di riferimento ufficiali per input, output e lettura della cache sono rispettivamente 2, 10 e 0,20 dollari per milione di Token. -- `messages`: l'array dei messaggi di input; ogni messaggio include `role` (ruolo) e `content` (contenuto), dove `role` supporta `user` e `assistant`. +- `model`: seleziona il modello Claude da utilizzare. `claude-opus-5-5` viene fornito solo tramite Messages API, supporta un contesto di 1 milione di Token, un output massimo di 128K Token e abilita sempre il ragionamento adattivo. L'ultimo modello di punta è `claude-fable-5-1` (contesto di 1 milione di Token, output massimo di 128K Token); il precedente `claude-fable-5` rimane compatibile e disponibile. `claude-sonnet-5-5` è stato aggiunto all'interfaccia della serie nativa Messages, supporta l'input di immagini e il ragionamento adattivo; i suoi prezzi di riferimento ufficiali per input, output e lettura della cache sono rispettivamente 2, 10 e 0,20 dollari per milione di Token. +- `messages`: l'array dei messaggi di input, ogni messaggio contiene `role` (ruolo) e `content` (contenuto), dove `role` supporta `user` e `assistant`. - `max_tokens`: il numero massimo di token in output, utilizzato per limitare la lunghezza di una singola risposta. Parametri opzionali comuni: - `system`: prompt di sistema, utilizzato per impostare il comportamento e il ruolo del modello. - `temperature`: casualità della generazione, compresa tra 0 e 1; maggiore è il valore, più divergente sarà la risposta. -- `stream`: se utilizzare risposte in streaming; impostandolo su `true` è possibile ottenere un effetto di restituzione parola per parola. -- `stop_sequences`: sequenze di arresto personalizzate; il modello interromperà la generazione quando incontrerà questi testi. -- `top_p`: parametro di campionamento nucleus, utilizzato insieme a temperature per controllare la casualità della generazione. -- `top_k`: campiona solo tra le K opzioni con la probabilità più alta. -- `tools`: definizione degli strumenti, utilizzata per consentire al modello di richiamare funzioni esterne. +- `stream`: se utilizzare risposte in streaming; impostandolo su `true` è possibile ottenere un effetto di restituzione carattere per carattere. +- `stop_sequences`: sequenze di arresto personalizzate; il modello smetterà di generare quando incontrerà questi testi. +- `top_p`: parametro di campionamento nucleare, che controlla la casualità della generazione insieme a temperature. +- `top_k`: esegue il campionamento solo tra le K opzioni con probabilità più alta. +- `tools`: definizioni degli strumenti, utilizzate per consentire al modello di chiamare funzioni esterne. - `tool_choice`: controlla come il modello utilizza gli strumenti forniti. -- `cache_control`: crea automaticamente un punto di interruzione della cache nell'ultimo blocco di contenuto memorizzabile nella cache della richiesta; può anche essere scritto sul blocco di contenuto specifico. +- `cache_control`: crea automaticamente un punto di interruzione della cache nell'ultimo blocco di contenuto memorizzabile nella richiesta; può anche essere scritto sul blocco di contenuto specifico. +- `metadata`: oggetto opzionale di metadati della richiesta. `metadata.user_id` è una stringa e può trasmettere un identificatore utente personalizzato dal chiamante, ad esempio `{"user_id":"example-user-001"}`; si consiglia di utilizzare un identificatore stabile che non contenga informazioni personali. Non sostituisce l'autenticazione `Authorization` e non deve essere scritto nel contenuto della conversazione `messages`. ### Esempio cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -107,24 +110,24 @@ Dopo la chiamata, il risultato restituito è il seguente: ``` Descrizione dei campi del risultato restituito: - -- `id`: identificatore univoco di questo messaggio. +- `id`: l'identificatore univoco di questo messaggio. - `type`: è sempre `message`. - `role`: è sempre `assistant`. -- `content`: array del contenuto della risposta; ogni elemento include `type` (ad esempio `text`) e il contenuto corrispondente. -- `model`: nome del modello che elabora la richiesta. -- `stop_reason`: motivo dell'arresto. I valori stabili includono `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (puoi ritrasmettere il contenuto corrente di assistant senza modifiche per continuare), `refusal` e `model_context_window_exceeded`. -- `stop_sequence`: se l'arresto avviene a causa di una sequenza di arresto personalizzata, mostra il testo della sequenza di arresto corrispondente. -- `stop_details`: quando `stop_reason` è `refusal`, può includere la categoria del rifiuto e una descrizione. -- `usage`: statistiche sull'utilizzo dei token. `input_tokens` è l'input non memorizzato nella cache; `cache_creation_input_tokens` e `cache_read_input_tokens` rappresentano rispettivamente la scrittura e la lettura della cache; `output_tokens` è il numero totale di token in output. Se viene restituito `output_tokens_details.thinking_tokens`, questo valore è un sottoinsieme di `output_tokens`; non aggiungerlo nuovamente nel calcolo del totale o dei costi. Questo dettaglio può essere `null` o omesso quando non è disponibile un conteggio autorevole. -- `usage.cache_creation`: dettaglio opzionale del TTL di scrittura della cache, che include `ephemeral_5m_input_tokens` e `ephemeral_1h_input_tokens`. Quando l'oggetto è presente, la somma dei due equivale a `cache_creation_input_tokens`; se il campo è `null` o omesso, indica che la risposta corrente non dispone di una ripartizione TTL utilizzabile e non può essere interpretato come `0`. -- `usage.cost`: le risposte non in streaming possono includere un oggetto di consumo della quota registrato da Ace Data Cloud, dove `amount` è il consumo effettivo di questa chiamata, `currency` è l'unità di misura e `list_amount` è l'importo prima dello sconto (se presente). Il prezzo base ufficiale di Fable 5.1 per la lettura della cache è $0.25/milione di Token, mentre i prezzi base per la scrittura della cache di 5 minuti e di 1 ora sono rispettivamente $12.50 e $20/milione di Token; il prezzo effettivo della piattaforma viene calcolato in base agli sconti del piano. +- `content`: array del contenuto della risposta, ogni elemento include `type` (come `text`) e il contenuto corrispondente. +- `model`: il nome del modello che elabora la richiesta. +- `stop_reason`: il motivo dell'interruzione. I valori stabili includono `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (può ritrasmettere invariato il contenuto corrente dell'assistant per continuare), `refusal` e `model_context_window_exceeded`. +- `stop_sequence`: se l'interruzione avviene a causa di una sequenza di arresto personalizzata, mostra il testo della sequenza di arresto corrispondente. +- `stop_details`: quando `stop_reason` è `refusal`, può contenere la categoria e la descrizione del rifiuto. +- `usage`: statistiche sull'utilizzo dei token. `input_tokens` è l'input non memorizzato nella cache; `cache_creation_input_tokens` e `cache_read_input_tokens` sono rispettivamente la scrittura e la lettura della cache; `output_tokens` è il numero totale di token in output. Se viene restituito `output_tokens_details.thinking_tokens`, questo valore è un sottoinsieme di `output_tokens`, quindi non sommarlo nuovamente nel calcolo del totale o del costo. Questo dettaglio può essere `null` o omesso quando non è disponibile un conteggio autorevole. +- `usage.cache_creation`: dettagli opzionali sul TTL della scrittura in cache, inclusi `ephemeral_5m_input_tokens` e `ephemeral_1h_input_tokens`. Quando l'oggetto è presente, la somma dei due è uguale a `cache_creation_input_tokens`; un campo `null` o omesso indica che la risposta corrente non dispone di una suddivisione TTL utilizzabile e non deve essere interpretato come `0`. +- `usage.cost`: le risposte non in streaming possono includere un oggetto di consumo delle quote registrato da Ace Data Cloud, in cui `amount` è il consumo effettivo di questa richiesta, `currency` è l'unità di misura e `list_amount` è l'importo prima dello sconto (se presente). Il prezzo base ufficiale per le letture della cache di Fable 5.1 è $0,25/milione di token, mentre i prezzi base per la scrittura nella cache di 5 minuti e 1 ora sono rispettivamente $12,50 e $20/milione di token; il prezzo effettivo della piattaforma viene calcolato in base allo sconto del piano. ## Prompt di sistema -La Claude Messages API supporta l'impostazione del prompt di sistema tramite il campo `system`, utilizzato per definire il comportamento, il ruolo e il contesto del modello. +Claude Messages API supporta l'impostazione dei prompt di sistema tramite il campo `system`, utilizzato per definire il comportamento, il ruolo e il contesto del modello. ### Esempio Python + ```python import requests @@ -153,7 +156,7 @@ Impostando il prompt `system`, è possibile controllare con precisione il ruolo ## Risposta in streaming -Questa interfaccia supporta anche le risposte in streaming: impostando il parametro `stream` su `true` è possibile ottenere un effetto di restituzione progressiva, particolarmente adatto per implementare la visualizzazione carattere per carattere nelle pagine web. +Questa interfaccia supporta anche le risposte in streaming: basta impostare il parametro `stream` su `true` per ottenere un effetto di restituzione progressiva, particolarmente adatto per implementare la visualizzazione parola per parola nelle pagine web. ### Esempio Python @@ -183,7 +186,7 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -La risposta in streaming viene restituita nel formato Server-Sent Events (SSE), con ogni riga preceduta da `event:` e `data:`. I tipi di eventi in streaming includono: +Le risposte in streaming vengono restituite nel formato Server-Sent Events (SSE), con ogni riga preceduta da `event:` e `data:`. I tipi di eventi in streaming includono: - `message_start`: inizio del messaggio, include le informazioni di base del messaggio e il nome del modello. - `content_block_start`: inizio del blocco di contenuto. @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Come si può vedere, nella risposta in streaming l'evento `content_block_delta` contiene il contenuto testuale generato progressivamente; concatenando tutti i `text_delta` è possibile ottenere la risposta completa. +Come si può vedere, nella risposta in streaming l'evento `content_block_delta` contiene il contenuto testuale generato progressivamente; concatenando tutti i `text_delta` si ottiene la risposta completa. ### Esempio JavaScript @@ -253,7 +256,7 @@ while (true) { ## Conversazione multi-turno -Se si desidera integrare la funzionalità di conversazione multi-turno, è necessario disporre alternativamente i messaggi con i ruoli `user` e `assistant` nell'array `messages`, trasmettendo insieme anche la cronologia delle conversazioni precedenti. +Se desideri integrare la funzionalità di conversazione multi-turno, devi disporre alternativamente i messaggi con ruolo `user` e `assistant` nell'array `messages`, includendo anche la cronologia delle conversazioni precedenti. ### Esempio Python @@ -283,7 +286,6 @@ print(response.json()) ``` Il risultato restituito è il seguente: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ Il risultato restituito è il seguente: } ``` -Trasmettendo la cronologia completa della conversazione in `messages`, Claude può fornire risposte accurate tenendo conto del contesto. +Passando la cronologia completa della conversazione in `messages`, Claude può combinare il contesto per fornire risposte accurate. -## Modello di ragionamento approfondito +## Modelli di ragionamento profondo -Il thinking e il thinking summary di Claude sono due concetti diversi: il modello può svolgere un ragionamento interno, ma l'API non restituisce la catena di pensiero originale. Quando è necessario mostrare il processo di ragionamento, l'API restituisce un riepilogo elaborato. +Il thinking e il thinking summary di Claude sono due concetti diversi: il modello può effettuare ragionamenti interni, ma l'API non restituisce la catena di pensiero originale. Quando è necessario mostrare il processo di ragionamento, l'API restituisce un riepilogo elaborato. -Per il modello attuale si consiglia di utilizzare adaptive thinking e di controllare l'impegno complessivo di ragionamento tramite `output_config.effort`: +I modelli attuali consigliano di usare adaptive thinking e di controllare l'investimento complessivo nel ragionamento tramite `output_config.effort`: ```python import requests @@ -341,7 +343,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Il blocco thinking nella risposta ha la seguente forma: +Il blocco thinking nella risposta ha la forma seguente: ```json { @@ -350,26 +352,27 @@ Il blocco thinking nella risposta ha la seguente forma: "signature": "opaque-signature" } ``` + - `display: "summarized"` restituisce un riepilogo leggibile del ragionamento; non è la catena di pensiero originale. -- `display: "omitted"` restituisce `thinking: ""`, ma conserva comunque una `signature` opaca per supportare le conversazioni successive. -- `display: "updates"` è la modalità beta di Anthropic e richiede l'inclusione di `anthropic-beta: thinking-display-updates-2026-08-18`. La definizione ufficiale è nascondere il corpo del ragionamento e mostrare brevi aggiornamenti sullo stato tra le chiamate agli strumenti. La piattaforma trasmette questo parametro e l'header beta con il loro valore originale e non li riscrive forzatamente come `summarized`; il contenuto effettivo dell'output dipende dal supporto del modello selezionato. -- `thinking`, `output_config`, effort, i parametri di campionamento e i nuovi campi di estensione vengono trasmessi con i loro valori originali. La piattaforma non mantiene enumerazioni di valori o restrizioni di combinazione codificate per modello e non riscrive automaticamente le modalità thinking; spetta al modello selezionato stabilire se accettare questi parametri, e gli errori sui parametri restituiti dal modello vengono ritrasmessi al client. +- `display: "omitted"` restituisce `thinking: ""`, ma mantiene comunque una `signature` opaca per supportare le conversazioni successive. +- `display: "updates"` è una modalità beta di Anthropic e richiede `anthropic-beta: thinking-display-updates-2026-08-18`. La definizione ufficiale consiste nel nascondere il testo del ragionamento e mostrare brevi aggiornamenti di avanzamento tra le chiamate agli strumenti. La piattaforma passa questo parametro e l'intestazione della richiesta beta con i valori originali e non lo riscrive forzatamente in `summarized`; il contenuto effettivo dell'output dipende dal supporto del modello selezionato. +- `thinking`, `output_config`, effort, parametri di campionamento e nuovi campi di estensione vengono passati con i valori originali. La piattaforma non mantiene enumerazioni di valori o limitazioni di combinazione codificate per modello, né riscrive automaticamente le modalità thinking; spetta al modello selezionato stabilire se accettare questi parametri, e gli errori dei parametri restituiti dal modello vengono inoltrati al client. - I valori predefiniti di display per Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 sono `omitted`; Opus 4.6, Sonnet 4.6 e i modelli precedenti che supportano thinking usano `summarized` per impostazione predefinita. -- Display influisce soltanto sul contenuto restituito e sulla latenza dello streaming, non disabilita il ragionamento né riduce la fatturazione dei token thinking. -- L'abilitazione predefinita di thinking e il valore predefinito di display sono due questioni indipendenti. Opus 5 e Sonnet 5 abilitano adaptive thinking per impostazione predefinita; per Opus 5, omettere `thinking` equivale a adaptive, e omettere `output_config.effort` equivale a `high`. Opus 4.8, 4.7 e 4.6 richiedono un'abilitazione esplicita. -- Thinking e il corpo finale condividono il budget di output `max_tokens`. Se il budget è troppo ridotto, thinking può consumarne la maggior parte, lasciando il corpo vuoto o troncato; aumenta `max_tokens`, oppure usa effort `low` / `medium` per controllare l'investimento nel ragionamento. -- Per i modelli che consentono di disabilitare thinking, puoi passare `thinking: {"type":"disabled"}`. Le nuove modalità come `between_tools` e le combinazioni con effort dipendono dal modello selezionato; la piattaforma non le rifiuta anticipatamente in base alle vecchie regole dei modelli. -- Il budget di ragionamento fisso può essere trasmesso tramite `budget_tokens`; i nuovi modelli in genere usano `thinking.type=adaptive` e `output_config.effort`. Il supporto per budget fissi o per la disabilitazione del ragionamento dipende dalle capacità correnti del modello selezionato. -- Nelle conversazioni multi-turno e nelle chiamate agli strumenti, devi ritrasmettere invariati il blocco thinking completo e la signature restituiti dall'assistant; non modificare né generare autonomamente la signature. -- La trasmissione dei parametri non significa che ogni modello supporti tutte le funzionalità. Le chiamate tra protocolli richiedono comunque conversione; l'ambito di supporto e gli errori per contenuti come `redacted_thinking` sono determinati dal servizio del modello che elabora effettivamente la richiesta. +- Display influisce solo sul contenuto restituito e sulla latenza dello streaming, non disabilita il ragionamento né riduce la fatturazione dei token thinking. +- L'abilitazione predefinita di thinking e il valore predefinito di display sono due questioni indipendenti. Opus 5 e Sonnet 5 abilitano adaptive thinking per impostazione predefinita; per Opus 5, omettere `thinking` equivale ad adaptive, mentre omettere `output_config.effort` equivale a `high`. Opus 4.8, 4.7 e 4.6 richiedono l'abilitazione esplicita. +- Thinking e il testo finale condividono il budget di output `max_tokens`. Quando il budget è troppo ridotto, thinking può consumare gran parte della quota, lasciando il testo vuoto o troncato; aumentare `max_tokens` oppure usare effort `low` / `medium` per controllare l'investimento nel ragionamento. +- Per i modelli che consentono di disabilitare thinking, è possibile passare `thinking: {"type":"disabled"}`. Nuove modalità come `between_tools` e le combinazioni con effort dipendono dal modello selezionato; la piattaforma non rifiuta preventivamente in base alle vecchie regole dei modelli. +- Un budget di ragionamento fisso può essere passato tramite `budget_tokens`; i nuovi modelli usano in genere `thinking.type=adaptive` e `output_config.effort`. Il supporto per un budget fisso o per la disabilitazione del ragionamento dipende dalle capacità attuali del modello selezionato. +- Nelle conversazioni multi-turno e nelle chiamate agli strumenti, è necessario restituire invariati il blocco thinking completo e la signature restituiti dall'assistant; non modificare né generare autonomamente la signature. +- Il passaggio trasparente dei parametri non significa che ogni modello supporti tutte le funzionalità. Le chiamate tra protocolli richiedono comunque una conversione; l'ambito di supporto e gli errori per contenuti come `redacted_thinking` sono determinati dal servizio del modello che elabora effettivamente la richiesta. -Nelle richieste in streaming, `summarized` produce `thinking_delta`; `omitted` non produce `thinking_delta`, conservando soltanto il ciclo di vita del blocco thinking e `signature_delta`. +Nelle richieste in streaming, `summarized` genera `thinking_delta`; `omitted` non genera `thinking_delta`, mantenendo solo il ciclo di vita del blocco thinking e `signature_delta`. ## Modelli visivi -Claude supporta input multimodali e può elaborare contemporaneamente testo e immagini. Nella Messages API, le capacità visive possono essere utilizzate impostando `content` in formato array e passando blocchi di contenuto immagine. +Claude supporta input multimodali e può elaborare contemporaneamente testo e immagini. Nella Messages API, è possibile utilizzare le capacità visive impostando `content` in formato array e passando blocchi di contenuto immagine. -### Utilizzare immagini con codifica Base64 +### Utilizzare immagini codificate in Base64 ```python import base64 @@ -456,7 +459,6 @@ print(response.json()) ``` ### Esempio cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -486,11 +488,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -I formati di immagine supportati includono: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +I formati immagine supportati includono: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. ## Documenti e PDF -I PDF utilizzano blocchi di contenuto `document` e supportano due sorgenti stabili: Base64 e URL. Le sorgenti Base64 devono utilizzare `application/pdf`: +I PDF utilizzano il blocco di contenuto `document`, supportando due fonti stabili: Base64 e URL. Le fonti Base64 devono utilizzare `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -Le sorgenti URL si scrivono come `{"type":"url","url":"https://example.com/report.pdf"}`. `document` supporta inoltre `text/plain` e sorgenti `content` composte da blocchi text/image; i campi facoltativi includono `title`, `context` e `citations`. La sorgente `file_id` della Files API appartiene a una funzionalità beta indipendente e non rientra nel contratto stabile di questa interfaccia. +La fonte URL si scrive come `{"type":"url","url":"https://example.com/report.pdf"}`. `document` supporta inoltre `text/plain` e fonti `content` composte da blocchi text/image; i campi opzionali includono `title`, `context` e `citations`. La fonte `file_id` della Files API appartiene a una funzionalità beta separata e non rientra nel contratto stabile di questa interfaccia. ## Cache dei prompt -`cache_control` di livello superiore posiziona automaticamente il punto di interruzione della cache sull'ultimo blocco memorizzabile nella cache: +Il `cache_control` di primo livello posiziona automaticamente il punto di interruzione della cache sull'ultimo blocco memorizzabile nella cache: ```python payload = { @@ -534,9 +536,10 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Quando è necessario controllare con precisione la posizione, è anche possibile inserire lo stesso `cache_control` nei blocchi di contenuto `text`, `image`, `document`, `tool_use`, `tool_result` o nella definizione dello strumento. `ttl` supporta `5m` (predefinito) e `1h`; verificare la scrittura e il raggiungimento della cache tramite `usage.cache_creation_input_tokens` e `usage.cache_read_input_tokens`. -Quando la risposta fornisce `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Se `cache_creation` è `null` o omesso, significa che è disponibile solo la quantità totale di scrittura nella cache e non una suddivisione TTL autorevole; in questo caso non considerare nessun bucket come 0 noto, e utilizzare comunque i campi aggregati come riferimento per la fatturazione e il totale. +Quando è necessario un controllo preciso della posizione, lo stesso `cache_control` può anche essere scritto sui blocchi di contenuto text, image, document, tool_use, tool_result o sulle definizioni degli strumenti. `ttl` supporta `5m` (predefinito) e `1h`; utilizzare `usage.cache_creation_input_tokens` e `usage.cache_read_input_tokens` per determinare la scrittura e il hit della cache. + +Quando la risposta fornisce `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Se `cache_creation` è `null` o viene omesso, ciò indica che esiste solo il totale delle scritture nella cache, senza una suddivisione TTL autorevole; in questo caso non trattare nessun bucket come uno 0 noto, e la fatturazione e il totale devono comunque basarsi sul campo aggregato. Esempio di risultato restituito: @@ -561,9 +564,9 @@ Esempio di risultato restituito: } ``` -## Chiamata degli strumenti (Tool Use) +## Chiamate agli strumenti (Tool Use) -Claude Messages API supporta nativamente la funzionalità di chiamata degli strumenti, consentendo al modello di chiamare strumenti/funzioni predefiniti dall'utente quando necessario. +La Claude Messages API supporta nativamente la funzionalità di chiamata agli strumenti, consentendo al modello di chiamare strumenti/funzioni da voi predefiniti quando necessario. ### Esempio Python @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Quando il modello decide di chiamare uno strumento, il risultato restituito conterrà blocchi di contenuto di tipo `tool_use` in `content`: +Quando il modello decide di chiamare uno strumento, `content` nel risultato restituito conterrà un blocco di contenuto di tipo `tool_use`: ```json { @@ -637,7 +640,7 @@ Quando il modello decide di chiamare uno strumento, il risultato restituito cont } ``` -Notare che `stop_reason` è `tool_use`, indicando che il modello deve chiamare uno strumento. Dopo aver ricevuto questo risultato, è necessario eseguire la funzione dello strumento e restituire il risultato al modello sotto forma di `tool_result`: +Si noti che `stop_reason` è `tool_use`, il che indica che il modello deve chiamare lo strumento. Dopo aver ricevuto questo risultato, è necessario eseguire la funzione dello strumento e restituire il risultato al modello sotto forma di `tool_result`: ```python payload = { @@ -685,29 +688,28 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Il modello genererà la risposta finale in linguaggio naturale sulla base del risultato restituito dallo strumento. +Il modello genererà la risposta finale in linguaggio naturale sulla base dei risultati restituiti dallo strumento. ## Differenze rispetto alla Chat Completion API -Ace Data Cloud fornisce contemporaneamente due formati API Claude; le principali differenze tra i due sono le seguenti: +Ace Data Cloud fornisce contemporaneamente due formati di Claude API, le cui principali differenze sono le seguenti: -L'`usage.input_tokens` della Messages API indica solo gli input non memorizzati nella cache, mentre `cache_read_input_tokens` e `cache_creation_input_tokens` sono bucket di fatturazione separati; tutti e tre vengono calcolati in base ai rispettivi prezzi. - -| Caratteristica | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +`usage.input_tokens` della Messages API indica solo l'input non memorizzato nella cache; `cache_read_input_tokens` e `cache_creation_input_tokens` sono bucket di fatturazione indipendenti; tutti e tre verranno calcolati separatamente ai prezzi corrispondenti. +| Caratteristica | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Formato | Formato nativo Anthropic | Formato compatibile OpenAI | -| Prompt di sistema | Campo `system` separato | Passato tramite `role: "system"` in `messages` | -| Struttura della risposta | Array `content` (supporta diversi tipi) | Array `choices` (contenente `message`) | -| Formato streaming | Eventi SSE (diversi tipi di eventi) | Righe SSE `data` | -| Ragionamento approfondito | `thinking` nativo e `output_config.effort` | Strategia predefinita del modello e parametri compatibili | -| Chiamata degli strumenti | `tools` nativo + `input_schema` | Formato `tools` compatibile OpenAI | +| Formato | Formato nativo Anthropic | Formato compatibile con OpenAI | +| Prompt di sistema | Campo `system` indipendente | Trasferito tramite `role: "system"` in `messages` | +| Struttura della risposta | Array `content` (supporta più tipi) | Array `choices` (include `message`) | +| Formato streaming | Eventi SSE (molteplici tipi di eventi) | Righe SSE `data` | +| Ragionamento approfondito | `thinking` nativo e `output_config.effort` | Strategia predefinita del modello e parametri compatibili | +| Chiamata di strumenti | `tools` nativo + `input_schema` | Formato `tools` compatibile con OpenAI | | Statistiche Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Se il sistema è già integrato con un'API in formato OpenAI, è possibile utilizzare la Chat Completion API per una transizione senza interruzioni. Se è necessario utilizzare tutte le capacità native di Claude, si consiglia di usare la Messages API. +Se il vostro sistema è già integrato con API in formato OpenAI, potete usare la Chat Completion API per passare senza interruzioni. Se avete bisogno di utilizzare tutte le capacità native di Claude, si consiglia di utilizzare la Messages API. ## Gestione degli errori -Le risposte di errore dell'interfaccia pubblica utilizzano l'envelope della piattaforma Ace Data Cloud: `error.code` è il codice di errore stabile, `error.message` è la descrizione e `trace_id` viene utilizzato per analizzare le richieste. Gli stati HTTP comuni includono: +Le risposte di errore dell'interfaccia pubblica utilizzano l'envelope della piattaforma Ace Data Cloud: `error.code` è un codice di errore stabile, `error.message` è una descrizione e `trace_id` viene utilizzato per analizzare la richiesta. Gli stati HTTP comuni includono: - `400`: parametri della richiesta o contenuto del protocollo non validi. - `401`: token di autorizzazione non valido, mancante o scaduto. @@ -729,7 +731,8 @@ Le risposte di errore dell'interfaccia pubblica utilizzano l'envelope della piat } ``` -Questa struttura degli errori è il contratto runtime di Ace Data Cloud e non equivale all'envelope degli errori ufficiale di Anthropic; gestirla in base allo stato HTTP e a `error.code`. +Questa struttura di errore è il contratto runtime di Ace Data Cloud e non equivale all'envelope di errore ufficiale di Anthropic; gestitela in base allo stato HTTP e a `error.code`. ## Conclusione -Attraverso questo documento, hai già appreso come utilizzare la Claude Messages API per richiamare le funzionalità di conversazione di Claude nel formato nativo di Anthropic. La Messages API supporta numerose funzionalità avanzate, tra cui conversazioni di base, prompt di sistema, risposte in streaming, conversazioni multi-turno, ragionamento approfondito, comprensione visiva, PDF, caching dei prompt e chiamate di strumenti. In caso di domande, non esitare a contattare il nostro team di supporto tecnico. + +Attraverso questo documento, avete già appreso come utilizzare la Claude Messages API per chiamare le funzionalità di conversazione di Claude nel formato nativo Anthropic. La Messages API supporta numerose funzionalità, tra cui conversazioni di base, prompt di sistema, risposte in streaming, conversazioni multi-turno, ragionamento approfondito, comprensione visiva, PDF, cache dei prompt e chiamate di strumenti. Per qualsiasi domanda, non esitate a contattare il nostro team di supporto tecnico. diff --git a/it/guides/openai/openai_embeddings.mdx b/it/guides/openai/openai_embeddings.mdx index c7939283d..62e1539d0 100644 --- a/it/guides/openai/openai_embeddings.mdx +++ b/it/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API richiesta e utilizzo" +title: "Richiesta e utilizzo dell'API OpenAI Embeddings" description: "OpenAI generation API guide - Ace Data Cloud" --- -Il servizio di vettori di parole di OpenAI è utilizzato per generare risultati di vettori di parole che rappresentano il testo di input. +Servizio di vettori di parole OpenAI, utilizzato per generare risultati di vettori di parole che rappresentano il testo di input. -Questo documento descrive principalmente il processo di utilizzo dell'API OpenAI Embeddings, grazie al quale possiamo creare vettori di embedding che rappresentano il testo di input. +Questo documento presenta principalmente il processo di utilizzo delle operazioni dell'API OpenAI Embeddings, attraverso la quale possiamo creare vettori di embedding che rappresentano il testo di input。。 -## Processo di richiesta +## Procedura di richiesta -Per utilizzare l'API OpenAI Embeddings, prima di tutto vai al [Pannello di controllo di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro. +Per utilizzare l'API OpenAI Embeddings, per prima cosa vai alla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare come riserva. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. +Se non hai ancora effettuato l'accesso o la registrazione, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e ad accedere; al termine, tornerai automaticamente alla pagina corrente. -**Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza dover richiedere separatamente per ogni servizio.** La prima richiesta ti darà un credito gratuito, per un'esperienza senza costi; se il credito è insufficiente, puoi ricaricare il saldo generale nel [pannello di controllo](https://platform.acedata.cloud/console/coin). +**Un solo API Token può richiamare tutti i servizi della piattaforma, senza la necessità di richiederne uno separatamente per ogni servizio.** Alla prima richiesta verrà fornito un credito gratuito, che può essere utilizzato per una prova gratuita; quando il credito è insufficiente, puoi ricaricare il saldo universale dalla [console](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) ## Utilizzo di base -Ora puoi compilare i contenuti corrispondenti nell'interfaccia, come mostrato nell'immagine: +Successivamente puoi compilare i contenuti corrispondenti nell'interfaccia, come mostrato nell'immagine:

-Quando utilizzi per la prima volta questa interfaccia, devi compilare almeno tre contenuti: uno è `authorization`, che puoi selezionare direttamente dal menu a discesa. Un altro parametro è `model`, `model` è la categoria del modello che scegli di utilizzare dal sito ufficiale di OpenAI; qui abbiamo principalmente 3 modelli, i dettagli possono essere consultati nei modelli forniti. L'ultimo parametro è `input`, `input` è il testo del vettore di parole che desideriamo convertire. +Quando utilizzi questa interfaccia per la prima volta, dobbiamo compilare almeno tre contenuti: uno è `authorization`, che può essere selezionato direttamente nell'elenco a discesa. Un altro parametro è `model`, `model` è la categoria di modello del sito ufficiale OpenAI che scegliamo di utilizzare; i modelli attualmente disponibili sono `text-embedding-3-small` e `text-embedding-3-large`. `text-embedding-ada-002` non viene più fornito; se un indice vettoriale esistente utilizza questo vecchio modello, non può mescolare direttamente i vettori dei nuovi modelli e deve essere ricreato. L'ultimo parametro è `input`, `input` è il testo del vettore di parole che dobbiamo convertire. -Puoi anche notare che a destra c'è un codice di chiamata corrispondente generato, puoi copiare il codice e eseguirlo direttamente, oppure puoi semplicemente cliccare sul pulsante "Try" per testarlo. +Allo stesso tempo, puoi notare che sulla destra viene generato il codice di chiamata corrispondente; puoi copiare il codice ed eseguirlo direttamente, oppure fare clic direttamente sul pulsante «Try» per effettuare un test. Parametri opzionali: -- `dimensions`: ridimensiona la dimensione del vettore, l'output predefinito è la dimensione completa. -- `encoding_format`: formato di ritorno, opzioni `float` o `base64`. +- `dimensions`: riduce le dimensioni del vettore, per impostazione predefinita restituisce le dimensioni complete. +- `encoding_format`: formato di restituzione, può essere `float` o `base64`.

-Esempio di codice di chiamata in Python: +Codice di chiamata di esempio Python: ```python import requests @@ -50,8 +50,8 @@ headers = { } payload = { - "input": "Il cibo era delizioso e il cameriere...", - "model": "text-embedding-ada-002", + "input": "The food was delicious and the waiter...", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Dopo la chiamata, abbiamo trovato il risultato di ritorno come segue: +Dopo la chiamata, scopriamo che il risultato restituito è il seguente: ```json { @@ -97,7 +97,7 @@ Dopo la chiamata, abbiamo trovato il risultato di ritorno come segue: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,22 +105,22 @@ Dopo la chiamata, abbiamo trovato il risultato di ritorno come segue: } ``` -Il risultato di ritorno ha diversi campi, descritti come segue: +Il risultato restituito contiene diversi campi, presentati di seguito: -- `model`, il modello utilizzato per convertire il testo in vettori di parole. -- `usage`, le informazioni sui token utilizzati per convertire il testo in vettori di parole. -- `data`, il risultato dei vettori di parole dopo la conversione del testo. +- `model`, il modello utilizzato per questa conversione del testo in vettori di parole. +- `usage`, le informazioni sui token utilizzati per questa conversione del testo in vettori di parole. +- `data`, il risultato del vettore di parole dopo la conversione del testo. -Dove `data` contiene le informazioni specifiche sui vettori di parole corrispondenti al testo, e `embedding` è il risultato specifico dei vettori di parole generati. +Tra questi, `data` contiene le informazioni specifiche relative ai vettori di parole corrispondenti al testo, e il suo `embedding` è il risultato specifico del vettore di parole generato. ## Gestione degli errori -Quando chiami l'API, se si verifica un errore, l'API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio: +Quando si richiama l'API, se si verifica un errore, l'API restituisce il codice e le informazioni di errore corrispondenti. Ad esempio: - `400 token_mismatched`: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi. - `400 api_not_implemented`: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi. - `401 invalid_token`: Non autorizzato, token di autorizzazione non valido o mancante. -- `429 too_many_requests`: Troppe richieste, hai superato il limite di frequenza. +- `429 too_many_requests`: Troppe richieste, hai superato il limite di velocità. - `500 api_error`: Errore interno del server, qualcosa è andato storto sul server. ### Esempio di risposta di errore @@ -138,4 +138,4 @@ Quando chiami l'API, se si verifica un errore, l'API restituirà il codice di er ## Conclusione -Attraverso questo documento, hai appreso come utilizzare facilmente l'API OpenAI Embeddings per generare vettori di parole ufficiali di OpenAI. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico. +Attraverso questo documento, hai già appreso come utilizzare l'API OpenAI Embeddings per usare facilmente la funzionalità ufficiale di OpenAI per la generazione di vettori di parole. Ci auguriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Per qualsiasi domanda, non esitare a contattare il nostro team di supporto tecnico. diff --git a/it/guides/platform/wework_bot.mdx b/it/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..ca871bc12 --- /dev/null +++ b/it/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "Robot WeCom" +description: "Platform API guide - Ace Data Cloud" +--- + +Distribuisci la tua istanza dell'account WeCom, accedi tramite scansione del codice con WeCom mobile e leggi account, contatti, conversazioni e messaggi sincronizzati localmente tramite REST API o MCP. L'istanza corrisponde a un normale account WeCom, senza necessità di server privatizzato o configurazione del dominio email aziendale. + +Attualmente è in Alpha. La lettura dell'account ha completato la verifica su conversazioni reali; l'invio di testi da parte dell'utente e la rilettura degli eventi hanno completato il collaudo reale; le operazioni su altri contatti, gruppi e il ripristino di nuove istanze devono ancora completare il collaudo dell'ambiente di distribuzione. L'invio di media, le risposte con citazione, i @ reali, la gestione dei membri del gruppo e le conferme di consegna non sono ancora aperti. Fare riferimento al valore restituito da `/api/capabilities` dell'istanza. + +## Distribuzione e accesso + +Attiva il servizio nella categoria Deployment e seleziona il pacchetto di durata dell'istanza. Dopo la distribuzione, apri la pagina di gestione e usa WeCom dell'account stesso per scansionare il codice; se è necessaria una conferma sul telefono o altri passaggi di accesso, apri il desktop remoto e inserisci la password del desktop di quell'istanza. Le credenziali API e la password del desktop sono indipendenti. I dati di accesso vengono salvati sul disco dell'istanza; la ricostruzione del container conserva il disco; l'eliminazione del disco elimina la sessione locale. + +Ogni istanza viene addebitata separatamente e funziona in base alla durata acquistata. Le chiamate REST / MCP non vengono addebitate separatamente per messaggio; i prezzi effettivi sono soggetti alla pagina del pacchetto. Attualmente viene fatto riferimento per impostazione predefinita ai pacchetti di durata del robot WeChat; prima dell'apertura finale, la determinazione dei prezzi deve essere confermata in combinazione con le risorse di esecuzione. + +## API e MCP + +Usa l'indirizzo API dell'istanza nella pagina di gestione; tutte le interfacce dell'account includono `Authorization: Bearer `. Questi percorsi appartengono a istanze dedicate e non sono un gateway API condiviso. L'indirizzo MCP è l'indirizzo dell'istanza più `/mcp/`, utilizzando lo stesso token Bearer. + +| Interfaccia | Funzione | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Se l'account è pronto e l'elenco delle capacità | +| `GET /api/auth/qr` | PNG Base64 del codice QR di accesso corrente | +| `GET /api/account` | Account corrente | +| `GET /api/contacts?kind=all` | Colleghi interni e contatti esterni; è possibile specificare internal / external | +| `GET /api/conversations` | Conversazioni locali, con conservazione dell'ID conversazione originale | +| `GET /api/messages` | Messaggi sincronizzati localmente; parametri conversation_id, after_rowid, limit | +| `POST /api/search` | Ricerca di contatti, conversazioni e testi locali | +| `POST /api/messages` | Attività asincrona di invio testo, deve fornire Idempotency-Key | +| `POST /api/messages/send` | Stesso punto di ingresso per l'invio, supporta uno o più destinatari | +| `GET /api/groups/{conversation_id}` | Informazioni e membri dei gruppi sincronizzati localmente | +| `GET /api/tasks` | Attività recenti e risultati di ciascun destinatario | +| `GET /api/tasks/{id}` | Interroga il risultato dell'invio | +| `POST /api/tasks/{id}/cancel` | Annulla le attività non ancora avviate | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Sospende l'automazione; riprende dopo la verifica dell'utente | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Stato dell'istanza e schermata corrente, entrambi richiedono autenticazione | +| `GET /api/events?after=0` | Eventi messaggio con cursore ripristinabile | +| `WS /ws` | Flusso di eventi messaggio, autenticazione Bearer | + +Il corpo dell'invio include `target`, `type: "text"` e `text`. `target` accetta ID conversazione, ID contatto, ID utente aziendale o nome completo univoco; usa preferibilmente gli ID; quando il nome visualizzato non può ancora identificare univocamente il destinatario, l'istanza rifiuterà l'operazione e non indovinerà il destinatario. Per i contatti senza una conversazione locale, il client aprirà prima la conversazione e invierà dopo aver verificato l'ID conversazione effettivo. L'header della richiesta `Idempotency-Key` è composto da 8–128 lettere, numeri o `_.:-`. Le richieste ripetute per la stessa operazione devono riutilizzare la stessa chiave e lo stesso corpo della richiesta. + +Sostituendo `target` con l'array `targets`, è possibile inviare in serie a 1–50 destinatari specificati in modo esplicito. I due non possono essere forniti contemporaneamente. Tutti i destinatari completano prima la risoluzione dell'identità e diversi alias che puntano allo stesso oggetto verranno rifiutati. Dopo il fallimento di un destinatario, gli invii successivi si interrompono; il risultato dell'attività registra per ogni elemento `succeeded`, `failed`, `unknown` o `not_attempted`; non considerare il successo parziale come successo totale. Questo flusso deve inoltre completare il collaudo reale dei contatti specificati nell'ambiente di distribuzione. + +Le attività possono trovarsi in queued, running, submitting, succeeded, failed, unknown o cancelled. `succeeded` indica che, dopo l'invio, sono stati trovati il testo esatto e l'ID messaggio del server nel record della conversazione corrispondente; `delivered` rimane null e non indica che l'altra parte abbia ricevuto il messaggio. unknown indica che il risultato non è chiaro; controlla la cronologia e non ripetere l'invio con una nuova chiave. L'istanza non ritrasmette automaticamente le attività interrotte. + +La cronologia include solo i contenuti già sincronizzati dal client e non può garantire tutta la cronologia. I messaggi non testuali possono restituire un tipo unknown; il download degli allegati non è ancora aperto. Gli eventi conservano gli ultimi 10.000 elementi; `gap` indica che il cursore ha superato la finestra di conservazione. La prima connessione non riproduce la vecchia cronologia come nuovi messaggi. + +`server_accepted` e `server_id` nella cronologia dei messaggi possono essere usati per verificare se il server ha accettato il messaggio locale; quando appare solo un record locale senza ID server, non è possibile considerare l'invio riuscito. Questi campi non indicano che il destinatario abbia ricevuto o letto il messaggio. I record degli eventi conservano lo stato al momento della generazione; per interrogare lo stato di conferma corrente, usa l'interfaccia della cronologia dei messaggi. + +## Account e credenziali + +Accedi solo ad account sui quali hai l'autorizzazione a operare. Configura il token API in applicazioni affidabili; esso può accedere ai dati dell'account di quell'istanza. Non pubblicare password, codici QR o screenshot delle chat in luoghi pubblici. La sospensione dell'istanza interrompe gli eventi in tempo reale. Dopo il logout dell'account o la rimozione del dispositivo dal telefono, è necessario effettuare nuovamente l'accesso. + +L'input di testo corrente supporta solo una singola riga; le interruzioni di riga verranno esplicitamente rifiutate prima dell'invio. Quando il client richiede una verifica di sicurezza o un nuovo accesso, l'utente dell'account deve completarlo nel desktop remoto; l'istanza non aggirerà la verifica. Le attività dopo l'interruzione della verifica potrebbero restituire unknown; interroga prima i record dei messaggi e non ritrasmettere con una nuova chiave di idempotenza. + +Dopo il rilevamento di un avviso di verifica di sicurezza, del logout dell'account o di modifiche, la coda di automazione verrà sospesa in modo persistente. Dopo aver completato la verifica sul telefono, puoi continuare le attività non ancora eseguite tramite “Riprendi dopo la verifica” nella console dell'istanza; le attività già inviate ma con risultato incerto non verranno ritrasmesse. Anche il normale lavoro remoto può attivare la verifica di sicurezza di WeCom. La finestra di 24 ore senza ulteriore blocco dopo la verifica indicata nella documentazione ufficiale non significa che il rilevamento sia già stato eliminato, né significa che l'istanza possa garantire un funzionamento non presidiato a lungo termine. diff --git a/ja/guides/claude/claude_messages.mdx b/ja/guides/claude/claude_messages.mdx index 15ab5abc1..d6baa0503 100644 --- a/ja/guides/claude/claude_messages.mdx +++ b/ja/guides/claude/claude_messages.mdx @@ -3,41 +3,42 @@ title: "Claude Messages API の申請および使用" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude は非常に強力な AI 対話システムであり、プロンプトを入力するだけで、わずか数秒で流暢で自然な返信を生成できます。Claude Messages API は Anthropic 公式ネイティブの API 形式であり、OpenAI 互換形式（Chat Completion）とは異なり、Anthropic 独自のリクエストおよびレスポンス構造を採用しています。これにより、マルチモーダルコンテンツ入力、ツール呼び出し、深い思考（Extended Thinking）などの高度な機能といった、Claude の独自の能力をより活用できます。 +Anthropic Claude は非常に強力な AI 対話システムであり、プロンプトを入力するだけで、わずか数秒で流暢かつ自然な返信を生成できます。Claude Messages API は Anthropic 公式ネイティブの API 形式であり、OpenAI 互換形式（Chat Completion）とは異なり、Anthropic 独自のリクエストおよびレスポンス構造を採用しています。これにより、マルチモーダルコンテンツ入力、ツール呼び出し、拡張思考（Extended Thinking）などの高度な機能といった、Claude 独自の能力をより活用できます。 -本ドキュメントでは主に Claude Messages API 操作の使用フローを紹介します。これを利用することで、Anthropic 公式と一致するネイティブインターフェースを使用して、Claude の対話機能を呼び出すことができます。 +本ドキュメントでは主に Claude Messages API 操作の使用フローを紹介します。これを利用することで、Anthropic 公式と一致するネイティブインターフェースを使用して Claude の対話機能を呼び出せます。 ## 申請フロー -Claude Messages API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。 +Claude Messages API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして API Token を取得し、控えておいてください。 ![](https://cdn.acedata.cloud/dvc3cg.jpg) -まだログインまたは登録していない場合は、自動的にログインページへ移動し、登録とログインを促されます。完了後、自動的に現在のページへ戻ります。 +まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインを案内します。完了後は自動的に現在のページへ戻ります。 -**1 つの API Token だけでプラットフォームのすべてのサービスを呼び出せるため、サービスごとに個別に申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で試すことができます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。 +**1 つの API Token でプラットフォームのすべてのサービスを呼び出せるため、サービスごとに個別で申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で試用できます。クレジットが不足した場合は [コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。 > 📘 完全なドキュメント：[Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## 基本的な使用方法 -Claude Messages API のリクエストパスは `/v1/messages` であり、Anthropic 公式 API と一致しています。少なくとも以下の 3 つの必須パラメータを提供する必要があります。 +Claude Messages API のリクエストパスは `/v1/messages` であり、Anthropic 公式 API と一致しています。少なくとも以下の 3 つの必須パラメータを指定する必要があります。 -- `model`：使用する Claude モデルを選択します。`claude-opus-5-5` は Messages API を通じてのみ提供され、100 万 Token のコンテキスト、最大出力 128K Token をサポートし、常に適応型思考を有効にします。最新のフラッグシップは `claude-fable-5-1`（100 万 Token のコンテキスト、最大出力 128K Token）です。従来の `claude-fable-5` も引き続き互換性を維持しています。`claude-sonnet-5-5` はネイティブ Messages シリーズインターフェースに追加され、画像入力と適応型思考をサポートしています。その入力、出力、およびキャッシュ読み取りの公式参考価格は、100 万 Token あたりそれぞれ 2、10、および 0.20 米ドルです。 -- `messages`：入力メッセージの配列です。各メッセージには `role`（役割）と `content`（内容）が含まれ、`role` は `user` と `assistant` をサポートします。 -- `max_tokens`：最大出力 token 数であり、1 回の返信の長さを制限するために使用します。 +- `model`：使用する Claude モデルを選択します。`claude-opus-5-5` は Messages API でのみ提供され、100 万 Token のコンテキスト、最大 128K Token の出力をサポートし、常に適応型思考を有効にします。最新フラッグシップは `claude-fable-5-1`（100 万 Token のコンテキスト、最大 128K Token の出力）です。旧 `claude-fable-5` も引き続き互換性を維持しています。`claude-sonnet-5-5` はネイティブ Messages シリーズインターフェースに追加され、画像入力と適応型思考をサポートしています。その入力、出力、およびキャッシュ読み取りの公式参考価格は、100 万 Token あたりそれぞれ 2、10、および 0.20 米ドルです。 +- `messages`：入力メッセージの配列で、各メッセージには `role`（役割）と `content`（内容）が含まれます。`role` は `user` と `assistant` をサポートします。 +- `max_tokens`：最大出力 token 数で、1 回の返信の長さを制限するために使用します。 -よく使用されるオプションパラメータ： +一般的な任意パラメータ： -- `system`：システムプロンプトであり、モデルの動作と役割を設定するために使用します。 -- `temperature`：生成のランダム性です。0～1 の間で、値が大きいほど返信はより発散的になります。 -- `stream`：ストリーミングレスポンスを使用するかどうかです。`true` に設定すると、逐次返却効果を実現できます。 -- `stop_sequences`：カスタム停止シーケンスです。モデルはこれらのテキストに遭遇すると生成を停止します。 -- `top_p`：核サンプリングパラメータであり、temperature と組み合わせて生成のランダム性を制御します。 +- `system`：モデルの動作と役割を設定するためのシステムプロンプト。 +- `temperature`：生成のランダム性。0～1 の間で、値が大きいほど返信はより発散的になります。 +- `stream`：ストリーミングレスポンスを使用するかどうか。`true` に設定すると、逐次返却の効果を実現できます。 +- `stop_sequences`：カスタム停止シーケンス。モデルはこれらのテキストに遭遇すると生成を停止します。 +- `top_p`：核サンプリングパラメータ。temperature と組み合わせて生成のランダム性を制御します。 - `top_k`：確率が最も高い K 個の選択肢からのみサンプリングします。 -- `tools`：ツール定義であり、モデルが外部関数を呼び出せるようにするために使用します。 +- `tools`：モデルに外部関数を呼び出させるためのツール定義。 - `tool_choice`：モデルが提供されたツールをどのように使用するかを制御します。 -- `cache_control`：リクエスト内の最後のキャッシュ可能なコンテンツブロックにキャッシュチェックポイントを自動的に作成します。具体的なコンテンツブロックに記述することもできます。 +- `cache_control`：リクエスト内の最後のキャッシュ可能なコンテンツブロックにキャッシュブレークポイントを自動作成します。具体的なコンテンツブロックに記述することもできます。 +- `metadata`：任意のリクエストメタデータオブジェクト。`metadata.user_id` は文字列であり、`{"user_id":"example-user-001"}` のように、呼び出し元がカスタマイズしたユーザー識別子を渡せます。個人情報を含まない安定した識別子の使用を推奨します。これは `Authorization` 認証の代わりにはならず、`messages` の対話内容に記述する必要もありません。 ### cURL の例 @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -呼び出し後、返される結果は以下のとおりです。 +呼び出し後、返却結果は以下のとおりです。 ```json { @@ -107,24 +110,24 @@ print(response.json()) ``` 返却結果フィールドの説明： - -- `id`：今回のメッセージの一意識別子です。 -- `type`：常に `message` です。 -- `role`：常に `assistant` です。 -- `content`：返信内容の配列であり、各要素には `type`（例：`text`）と対応する内容が含まれます。 -- `model`：リクエストを処理したモデル名です。 -- `stop_reason`：停止理由です。安定した値には `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（現在の assistant 内容をそのまま返送して継続可能）、`refusal`、および `model_context_window_exceeded` が含まれます。 -- `stop_sequence`：カスタム停止シーケンスによって停止した場合、一致した停止シーケンステキストを表示します。 -- `stop_details`：`stop_reason` が `refusal` の場合、拒否カテゴリおよび説明を含む可能性があります。 -- `usage`：token 使用統計です。`input_tokens` はキャッシュされていない入力です。`cache_creation_input_tokens` と `cache_read_input_tokens` はそれぞれキャッシュ書き込みと読み取りです。`output_tokens` はすべての出力 token 数です。`output_tokens_details.thinking_tokens` が返される場合、この値は `output_tokens` のサブセットであるため、合計または料金を計算する際に再度加算しないでください。この内訳は権威ある計数がない場合、`null` または省略される可能性があります。 -- `usage.cache_creation`：オプションのキャッシュ書き込み TTL 内訳であり、`ephemeral_5m_input_tokens` と `ephemeral_1h_input_tokens` が含まれます。オブジェクトが存在する場合、両者の合計は `cache_creation_input_tokens` と等しくなります。フィールドが `null` または省略されている場合は、現在のレスポンスに利用可能な TTL 内訳がないことを示し、`0` と解釈することはできません。 -- `usage.cost`：非ストリーミングレスポンスには、Ace Data Cloud が記録したクレジット消費オブジェクトが含まれる可能性があります。`amount` は今回の実際の消費量、`currency` は計量単位、`list_amount` は割引前の金額（該当する場合）です。Fable 5.1 の公式キャッシュ読み取り基本価格は 100 万 Token あたり $0.25 であり、5 分および 1 時間のキャッシュ書き込み基本価格はそれぞれ $12.50 および $20/100 万 Token です。プラットフォームの実際の価格はプラン割引に基づいて換算されます。 +- `id`：今回のメッセージの一意の識別子。 +- `type`：常に `message`。 +- `role`：常に `assistant`。 +- `content`：応答内容の配列。各要素には `type`（例：`text`）と対応する内容が含まれる。 +- `model`：リクエストを処理するモデル名。 +- `stop_reason`：停止理由。安定した値には `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（現在の assistant 内容をそのまま返すことで継続可能）、`refusal`、および `model_context_window_exceeded` が含まれる。 +- `stop_sequence`：カスタム停止シーケンスによって停止した場合、一致した停止シーケンスのテキストを表示する。 +- `stop_details`：`stop_reason` が `refusal` の場合、拒否カテゴリと説明が含まれることがある。 +- `usage`：token 使用量の統計。`input_tokens` はキャッシュされていない入力、`cache_creation_input_tokens` と `cache_read_input_tokens` はそれぞれキャッシュの書き込みと読み取り、`output_tokens` はすべての出力 token 数。`output_tokens_details.thinking_tokens` が返される場合、この値は `output_tokens` のサブセットであり、合計または料金を計算する際に再度加算してはならない。この内訳は権威あるカウントがない場合、`null` であるか省略されることがある。 +- `usage.cache_creation`：オプションのキャッシュ書き込み TTL 内訳。`ephemeral_5m_input_tokens` と `ephemeral_1h_input_tokens` を含む。オブジェクトが存在する場合、両者の合計は `cache_creation_input_tokens` と等しい。フィールドが `null` または省略されている場合、現在の応答には利用可能な TTL 内訳がないことを意味し、`0` と解釈してはならない。 +- `usage.cost`：非ストリーミング応答には、Ace Data Cloud によって記録されたクレジット消費オブジェクトが含まれる場合がある。`amount` は今回の実際の消費量、`currency` は計測単位、`list_amount` は割引前の金額（該当する場合）。Fable 5.1 の公式キャッシュ読み取り基本価格は $0.25/100万 Token、5 分間および1時間のキャッシュ書き込み基本価格はそれぞれ $12.50 および $20/100万 Token。プラットフォームの実際の価格はプランの割引に応じて換算される。 ## システムプロンプト -Claude Messages API は `system` フィールドを通じてシステムプロンプトを設定することをサポートしており、モデルの動作、役割、およびコンテキストを定義するために使用します。 +Claude Messages API は、モデルの動作、役割、コンテキストを定義するために、`system` フィールドによるシステムプロンプトの設定をサポートしている。 ### Python の例 + ```python import requests @@ -149,11 +152,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -`system` プロンプトを設定することで、Claude の役割と動作方法を正確に制御できます。 +`system` プロンプトを設定することで、Claude の役割と動作方式を正確に制御できる。 ## ストリーミング応答 -このインターフェースはストリーミング応答もサポートしており、`stream` パラメータを `true` に設定すると段階的に返される効果を得られ、Web ページでの一文字ずつの表示を実装するのに非常に適しています。 +このインターフェースはストリーミング応答にも対応しており、`stream` パラメータを `true` に設定すると段階的に返される効果を得られるため、ウェブページでの逐次表示の実装に非常に適している。 ### Python の例 @@ -183,16 +186,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -ストリーミング応答は Server-Sent Events (SSE) 形式で返され、各行は `event:` と `data:` で始まります。ストリーミングイベントの種類には以下が含まれます。 +ストリーミング応答は Server-Sent Events (SSE) 形式で返され、各行は `event:` と `data:` で始まる。ストリーミングイベントの種類には以下が含まれる： -- `message_start`：メッセージの開始。メッセージの基本情報とモデル名を含みます。 -- `content_block_start`：コンテンツブロックの開始。 -- `content_block_delta`：コンテンツブロックの増分更新。新たに生成されたテキスト断片を含みます。 -- `content_block_stop`：コンテンツブロックの終了。 -- `message_delta`：メッセージレベルの増分更新。`stop_reason` と最終的な `usage` 情報を含みます。`output_tokens_details.thinking_tokens` の信頼できる値は、最後の `message_delta.usage` からのみ読み取るべきであり、イベントをまたいで累積しないでください。 -- `message_stop`：メッセージの終了。 +- `message_start`：メッセージ開始。メッセージの基本情報とモデル名を含む。 +- `content_block_start`：コンテンツブロック開始。 +- `content_block_delta`：コンテンツブロックの増分更新。新たに生成されたテキスト断片を含む。 +- `content_block_stop`：コンテンツブロック終了。 +- `message_delta`：メッセージレベルの増分更新。`stop_reason` と最終的な `usage` 情報を含む。`output_tokens_details.thinking_tokens` の権威ある値は、最後の `message_delta.usage` からのみ読み取るべきであり、イベントをまたいで累積してはならない。 +- `message_stop`：メッセージ終了。 -出力結果は以下のとおりです。 +出力結果は以下のとおり： ``` event: message_start @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -ご覧のとおり、ストリーミング応答内の `content_block_delta` イベントには段階的に生成されたテキストコンテンツが含まれており、すべての `text_delta` を連結することで完全な応答を取得できます。 +確認できるように、ストリーミング応答の `content_block_delta` イベントには段階的に生成されるテキスト内容が含まれており、すべての `text_delta` を連結することで完全な応答を取得できる。 ### JavaScript の例 @@ -251,9 +254,9 @@ while (true) { } ``` -## マルチターン対話 +## マルチターン会話 -マルチターン対話機能を連携したい場合は、`messages` 配列内で `user` と `assistant` の役割のメッセージを交互に配置し、これまでの会話履歴をあわせて渡す必要があります。 +マルチターン会話機能を連携したい場合は、`messages` 配列内で `user` と `assistant` ロールのメッセージを交互に並べ、これまでの会話履歴をまとめて渡す必要がある。 ### Python の例 @@ -282,8 +285,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -返される結果は以下のとおりです。 - +返却結果は以下のとおり： ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ print(response.json()) } ``` -`messages` で完全な会話履歴を渡すことで、Claude はコンテキストを組み合わせて正確に回答できます。 +`messages` で完全な会話履歴を渡すことで、Claude はコンテキストを踏まえて正確に回答できます。 ## 深い思考モデル -Claude の thinking と thinking summary は異なる二つの概念です。モデルは内部推論を行えますが、API は生の思考連鎖を返しません。推論過程を表示する必要がある場合、API が返すのは処理済みの要約です。 +Claude の thinking と thinking summary は異なる概念です。モデルは内部推論を行えますが、API は元の思考連鎖を返しません。推論プロセスを表示する必要がある場合、API が返すのは処理済みの要約です。 -現在のモデルでは adaptive thinking の使用が推奨されており、`output_config.effort` を通じて全体的な推論投入量を制御します。 +現在のモデルでは adaptive thinking の使用が推奨されており、`output_config.effort` によって全体的な推論投入量を制御します。 ```python import requests @@ -341,7 +343,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -応答内の thinking ブロックは以下のような形式です。 +レスポンス内の thinking ブロックは以下のような形式です。 ```json { @@ -350,26 +352,27 @@ print(response.json()) "signature": "opaque-signature" } ``` -- `display: "summarized"` は読みやすい思考要約を返します；これは生の思考連鎖ではありません。 -- `display: "omitted"` は `thinking: ""` を返しますが、後続の会話をサポートするため opaque な `signature` は保持されます。 -- `display: "updates"` は Anthropic の beta モードであり、`anthropic-beta: thinking-display-updates-2026-08-18` を含める必要があります。公式の定義では、推論本文を隠し、ツール呼び出しの間に短い進捗更新を表示します。プラットフォームはこのパラメータと beta リクエストヘッダーを元の値のまま渡し、強制的に `summarized` へ書き換えることはありません；実際の出力内容は選択したモデルのサポート状況に依存します。 -- `thinking`、`output_config`、effort、サンプリングパラメータおよび新規拡張フィールドは元の値のまま渡されます。プラットフォームはモデルごとにハードコードされた値の列挙や組み合わせ制限を管理せず、thinking モードを自動的に書き換えることもありません；これらのパラメータを受け入れるかどうかは選択したモデルが判断し、モデルが返すパラメータエラーはクライアントへ返されます。 -- Fable 5.1、Fable 5、Opus 5、Sonnet 5、Opus 4.8 および Opus 4.7 の display デフォルト値は `omitted` です；Opus 4.6、Sonnet 4.6 およびそれ以前の thinking をサポートするモデルは、デフォルトで `summarized` を使用します。 -- Display は返される内容とストリーミング遅延にのみ影響し、推論を無効にすることも、thinking token の課金を減らすこともありません。 -- thinking がデフォルトで有効かどうかと display のデフォルト値は、2つの独立した問題です。Opus 5、Sonnet 5 はデフォルトで adaptive thinking を有効にします；Opus 5 では、`thinking` を省略することは adaptive と同等であり、`output_config.effort` を省略することは `high` と同等です。Opus 4.8、4.7 および 4.6 では明示的に有効化する必要があります。 -- Thinking と最終本文は共同で `max_tokens` の出力予算を使用します。予算が小さすぎる場合、thinking が大部分の枠を消費し、本文が空になるか切り詰められる可能性があります；`max_tokens` を増やすか、`low` / `medium` effort を使用して推論投入量を制御してください。 -- thinking を無効にできるモデルでは、`thinking: {"type":"disabled"}` を渡せます。`between_tools` などの新しいモードおよび effort の組み合わせは、選択したモデルに依存します；プラットフォームは古いモデル規則に基づいて事前に拒否しません。 -- 固定の思考予算は `budget_tokens` を通じて渡せます；新しいモデルは通常、`thinking.type=adaptive` と `output_config.effort` を使用します。固定予算または思考の無効化をサポートするかどうかは、選択したモデルの現在の能力に従います。 -- 複数ターンの会話およびツール呼び出しでは、assistant が返した完全な thinking ブロックおよび signature をそのまま返すべきです；signature を変更したり、自分で生成したりしないでください。 -- パラメータ透過は、すべてのモデルがすべての機能をサポートすることを意味しません。プロトコルをまたぐ呼び出しでは依然として変換が必要であり、`redacted_thinking` などの内容のサポート範囲とエラーは、実際にリクエストを処理するモデルサービスによって決定されます。 -ストリーミングリクエストでは、`summarized` は `thinking_delta` を生成します；`omitted` は `thinking_delta` を生成せず、thinking ブロックのライフサイクルと `signature_delta` のみを保持します。 +- `display: "summarized"` は読みやすい思考の要約を返します。これは元の思考連鎖ではありません。 +- `display: "omitted"` は `thinking: ""` を返しますが、後続の会話をサポートするため opaque `signature` は保持されます。 +- `display: "updates"` は Anthropic の beta モードであり、`anthropic-beta: thinking-display-updates-2026-08-18` を付加する必要があります。公式の定義では、推論本文を隠し、ツール呼び出しの間に短い進捗更新を表示します。プラットフォームはこのパラメータと beta リクエストヘッダーを元の値のまま渡し、`summarized` へ強制的に書き換えることはありません。実際の出力内容は、選択したモデルのサポート状況に依存します。 +- `thinking`、`output_config`、effort、サンプリングパラメータ、および追加の拡張フィールドは元の値のまま渡されます。プラットフォームは、モデルごとにハードコードされた値の列挙や組み合わせ制限を維持せず、thinking モードを自動的に書き換えることもありません。これらのパラメータを受け入れるかどうかは選択したモデルが判断し、モデルが返すパラメータエラーはクライアントへ返送されます。 +- Fable 5.1、Fable 5、Opus 5、Sonnet 5、Opus 4.8、および Opus 4.7 の display のデフォルト値は `omitted` です。Opus 4.6、Sonnet 4.6、およびそれ以前の thinking をサポートするモデルは、デフォルトで `summarized` を使用します。 +- Display は返される内容とストリーミング遅延にのみ影響し、推論を無効にしたり、thinking token の課金を減らしたりすることはありません。 +- thinking をデフォルトで有効にするかどうかと、display のデフォルト値は二つの独立した問題です。Opus 5 と Sonnet 5 はデフォルトで adaptive thinking を有効にします。Opus 5 では、`thinking` を省略することは adaptive と同等であり、`output_config.effort` を省略することは `high` と同等です。Opus 4.8、4.7、および 4.6 では明示的に有効にする必要があります。 +- Thinking と最終本文はともに `max_tokens` の出力予算を消費します。予算が小さすぎる場合、thinking が大部分の枠を消費し、本文が空になるか切り詰められる可能性があります。`max_tokens` を増やすか、`low` / `medium` effort を使用して推論投入量を制御してください。 +- thinking を無効にできるモデルでは、`thinking: {"type":"disabled"}` を渡せます。`between_tools` などの新しいモードおよび effort の組み合わせは、選択したモデルに依存します。プラットフォームは古いモデル規則に基づいて事前に拒否しません。 +- 固定の思考予算は `budget_tokens` を介して渡せます。新しいモデルでは通常、`thinking.type=adaptive` と `output_config.effort` を使用します。固定予算または思考の無効化をサポートするかどうかは、選択したモデルの現在の機能に依存します。 +- マルチターン会話およびツール呼び出しでは、assistant が返した完全な thinking ブロックと signature をそのまま返す必要があります。signature を変更したり、自分で生成したりしないでください。 +- パラメータの透過は、すべてのモデルがすべての機能をサポートすることを意味しません。プロトコルをまたぐ呼び出しでは依然として変換が必要であり、`redacted_thinking` などのコンテンツのサポート範囲とエラーは、実際にリクエストを処理するモデルサービスによって決まります。 + +ストリーミングリクエストでは、`summarized` は `thinking_delta` を生成します。`omitted` は `thinking_delta` を生成せず、thinking ブロックのライフサイクルと `signature_delta` のみを保持します。 -## ビジョンモデル +## ビジュアルモデル -Claude はマルチモーダル入力をサポートし、テキストと画像を同時に処理できます。Messages API では、`content` を配列形式に設定し、画像コンテンツブロックを渡すことでビジョン機能を使用できます。 +Claude はマルチモーダル入力をサポートしており、テキストと画像を同時に処理できます。Messages API では、`content` を配列形式に設定し、画像コンテンツブロックを渡すことでビジュアル機能を使用できます。 -### Base64 エンコード画像の使用 +### Base64 エンコード画像を使用する ```python import base64 @@ -415,7 +418,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### URL 画像の使用 +### URL 画像を使用する ```python import requests @@ -456,7 +459,6 @@ print(response.json()) ``` ### cURL の例 - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -486,11 +488,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -サポートされる画像形式には、`image/jpeg`、`image/png`、`image/gif`、`image/webp` が含まれます。 +サポートされている画像形式には、`image/jpeg`、`image/png`、`image/gif`、`image/webp` が含まれます。 ## ドキュメントと PDF -PDF は `document` コンテンツブロックを使用し、Base64 と URL の2種類の安定したソースをサポートします。Base64 ソースでは必ず `application/pdf` を使用する必要があります： +PDF では `document` コンテンツブロックを使用し、Base64 と URL の 2 種類の安定したソースをサポートします。Base64 ソースでは必ず `application/pdf` を使用する必要があります。 ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -URL ソースは `{"type":"url","url":"https://example.com/report.pdf"}` と記述します。`document` は `text/plain` および text/image ブロックで構成される `content` ソースもサポートします；任意フィールドには `title`、`context`、`citations` が含まれます。Files API の `file_id` ソースは独立した beta 機能に属しており、本インターフェースの安定した契約には含まれません。 +URL ソースは `{"type":"url","url":"https://example.com/report.pdf"}` と記述します。`document` はさらに `text/plain` および text/image ブロックで構成される `content` ソースをサポートします。任意フィールドには `title`、`context`、`citations` が含まれます。Files API の `file_id` ソースは独立した beta 機能に属し、本インターフェースの安定した契約には含まれません。 ## プロンプトキャッシュ -トップレベルの `cache_control` は、最後のキャッシュ可能ブロックにキャッシュブレークポイントを自動的に配置します： +トップレベルの `cache_control` は、最後のキャッシュ可能なブロックにキャッシュブレークポイントを自動的に配置します。 ```python payload = { @@ -534,9 +536,10 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -位置を正確に制御する必要がある場合は、同じ `cache_control` を text、image、document、tool_use、tool_result のコンテンツブロック、またはツール定義に記述することもできます。`ttl` は `5m`（デフォルト）と `1h` をサポートします。`usage.cache_creation_input_tokens` と `usage.cache_read_input_tokens` を通じて、キャッシュの書き込みとヒットを判断してください。 -レスポンスが `usage.cache_creation` を提供する場合、`ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens` です。`cache_creation` が `null` または省略されている場合、キャッシュ書き込み総量のみがあり、信頼できる TTL の内訳はないことを示します。この場合、いずれの bucket も既知の 0 と見なさず、課金と総量は引き続き aggregate フィールドに従ってください。 +位置を正確に制御する必要がある場合は、同じ `cache_control` を text、image、document、tool_use、tool_result コンテンツブロック、またはツール定義に記述することもできます。`ttl` は `5m`（デフォルト）と `1h` をサポートします。キャッシュの書き込みとヒットは `usage.cache_creation_input_tokens` および `usage.cache_read_input_tokens` で判断してください。 + +レスポンスが `usage.cache_creation` を提供する場合、`ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens` です。`cache_creation` が `null` または省略されている場合、キャッシュ書き込みの合計のみで、信頼できる TTL の内訳がないことを示します。この場合、いずれの bucket も既知の 0 と見なさないでください。課金と合計は引き続き aggregate フィールドに基づきます。 返却結果の例： @@ -563,7 +566,7 @@ payload = { ## ツール呼び出し（Tool Use） -Claude Messages API はツール呼び出し機能をネイティブでサポートしており、モデルが必要に応じて事前定義したツール/関数を呼び出すことを可能にします。 +Claude Messages API はツール呼び出し機能をネイティブにサポートしており、モデルは必要に応じて事前定義されたツール/関数を呼び出すことができます。 ### Python の例 @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -モデルがツールを呼び出すことを決定すると、返却結果の `content` には `tool_use` タイプのコンテンツブロックが含まれます。 +モデルがツールの呼び出しを決定すると、返却結果の `content` には `tool_use` タイプのコンテンツブロックが含まれます。 ```json { @@ -685,33 +688,32 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -モデルはツールから返された結果に基づいて、最終的な自然言語の応答を生成します。 +モデルはツールが返した結果に基づいて、最終的な自然言語の応答を生成します。 ## Chat Completion API との違い -Ace Data Cloud は Claude API の形式を 2 種類提供しており、両者の主な違いは以下のとおりです。 - -Messages API の `usage.input_tokens` はキャッシュされていない入力のみを表し、`cache_read_input_tokens` と `cache_creation_input_tokens` は独立した課金バケットです。3 つはそれぞれ対応する価格に基づいて計算されます。 +Ace Data Cloud は 2 種類の Claude API 形式を同時に提供しており、両者の主な違いは以下のとおりです。 +Messages API の `usage.input_tokens` はキャッシュされていない入力のみを示し、`cache_read_input_tokens` と `cache_creation_input_tokens` は独立した課金バケットです。3 つはそれぞれ対応する価格で計算されます。 | 特性 | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | 形式 | Anthropic ネイティブ形式 | OpenAI 互換形式 | | システムプロンプト | 独立した `system` フィールド | `messages` 内の `role: "system"` を通じて渡す | -| 応答構造 | `content` 配列（複数のタイプをサポート） | `choices` 配列（`message` を含む） | +| レスポンス構造 | `content` 配列（複数のタイプをサポート） | `choices` 配列（`message` を含む） | | ストリーミング形式 | SSE イベント（複数のイベントタイプ） | SSE `data` 行 | -| 拡張思考 | ネイティブの `thinking` と `output_config.effort` | モデルのデフォルト戦略と互換パラメータ | +| 深い思考 | ネイティブの `thinking` と `output_config.effort` | モデルのデフォルト戦略と互換パラメータ | | ツール呼び出し | ネイティブの `tools` + `input_schema` | OpenAI 互換の `tools` 形式 | | Token 統計 | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -システムがすでに OpenAI 形式の API に接続されている場合は、Chat Completion API を使用してシームレスに切り替えることができます。Claude のすべてのネイティブ機能を使用する必要がある場合は、Messages API の使用を推奨します。 +お客様のシステムがすでに OpenAI 形式の API に接続されている場合は、Chat Completion API を使用してシームレスに切り替えることができます。Claude のすべてのネイティブ機能を使用する必要がある場合は、Messages API を使用することをお勧めします。 ## エラー処理 -公開インターフェースのエラーレスポンスは Ace Data Cloud プラットフォームの envelope を使用します。`error.code` は安定したエラーコード、`error.message` は説明、`trace_id` はリクエストの調査に使用されます。一般的な HTTP ステータスには以下が含まれます。 +公開インターフェースのエラーレスポンスは Ace Data Cloud プラットフォームの envelope を使用します：`error.code` は安定したエラーコード、`error.message` は説明、`trace_id` はリクエストの調査に使用されます。一般的な HTTP ステータスには以下が含まれます： - `400`：リクエストパラメータまたはプロトコル内容が無効です。 -- `401`：認証トークンが無効、欠落、または期限切れです。 -- `403`：アクセスが禁止されている、残高不足、またはクォータが制限されています。 +- `401`：認可トークンが無効、欠落、または期限切れです。 +- `403`：アクセス禁止、残高不足、またはクォータ制限です。 - `404`：API またはモデルが存在しません。 - `413`：リクエストボディが大きすぎます。 - `429`：リクエストが多すぎます。 @@ -729,7 +731,8 @@ Messages API の `usage.input_tokens` はキャッシュされていない入力 } ``` -このエラー構造は Ace Data Cloud のランタイム契約であり、Anthropic 公式のエラー envelope と同一ではありません。HTTP ステータスと `error.code` に従って処理してください。 +このエラー構造は Ace Data Cloud のランタイム契約であり、Anthropic 公式のエラー envelope と同等ではありません。HTTP ステータスと `error.code` に従って処理してください。 ## 結論 -このドキュメントを通じて、Anthropic ネイティブ形式で Claude Messages API を使用して Claude の会話機能を呼び出す方法をすでに理解しました。Messages API は、基本的な会話、システムプロンプト、ストリーミングレスポンス、マルチターン会話、拡張思考、視覚理解、PDF、プロンプトキャッシュ、ツール呼び出しなどの豊富な機能をサポートしています。ご不明な点がございましたら、いつでも技術サポートチームまでお問い合わせください。 + +本ドキュメントを通じて、Anthropic ネイティブ形式で Claude Messages API を使用して Claude の対話機能を呼び出す方法を理解しました。Messages API は、基本的な対話、システムプロンプト、ストリーミングレスポンス、マルチターン対話、深い思考、視覚理解、PDF、プロンプトキャッシュ、ツール呼び出しなどの豊富な機能をサポートしています。ご不明な点がございましたら、いつでも当社の技術サポートチームまでお問い合わせください。 diff --git a/ja/guides/openai/openai_embeddings.mdx b/ja/guides/openai/openai_embeddings.mdx index 822c452c0..cb5f3f1a0 100644 --- a/ja/guides/openai/openai_embeddings.mdx +++ b/ja/guides/openai/openai_embeddings.mdx @@ -1,37 +1,37 @@ --- -title: "OpenAI Embeddings API 申請及び使用" +title: "OpenAI Embeddings API の申請および使用" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI の単語ベクトルサービスは、入力テキストを表す単語ベクトル結果を生成するためのものです。 +OpenAI の単語ベクトルサービスで、入力テキストを表す単語ベクトル結果を生成するために使用します。 -この文書では、OpenAI Embeddings API の操作の使用プロセスについて主に説明します。これを利用して、入力テキストを表す埋め込みベクトルを作成できます。 +本ドキュメントでは主に OpenAI Embeddings API 操作の使用手順を紹介し、これを利用して入力テキストを表す埋め込みベクトルを作成できます。。 -## 申請プロセス +## 申請手順 -OpenAI Embeddings API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして、API トークンを取得し、保管してください。 +OpenAI Embeddings API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。 ![](https://cdn.acedata.cloud/dvc3cg.jpg) -まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。 +まだログインまたは登録していない場合は、ログインページに自動的にリダイレクトされ、登録とログインを求められます。完了すると自動的に現在のページに戻ります。 -**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で一般的な残高をチャージできます。 +**1 つの API Token でプラットフォームのすべてのサービスを呼び出すことができ、サービスごとに個別に申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。 -> 📘 完全な文書：[OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) +> 📘 完全なドキュメント：[OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## 基本使用 +## 基本的な使用方法 -次に、画面上に対応する内容を入力します。以下の図のように： +続いて、画面上で対応する内容を入力できます。図のとおりです：

-このインターフェースを初めて使用する際には、少なくとも3つの内容を入力する必要があります。1つは `authorization` で、ドロップダウンリストから選択できます。もう1つのパラメータは `model` で、`model` は OpenAI の公式モデルカテゴリを選択するものです。ここでは主に3種類のモデルがあります。詳細は提供されたモデルをご覧ください。最後のパラメータは `input` で、`input` は変換する単語ベクトルテキストです。 +このインターフェースを初めて使用する際には、少なくとも 3 つの内容を入力する必要があります。1 つは `authorization` で、ドロップダウンリストから直接選択できます。もう 1 つのパラメータは `model` です。`model` は OpenAI 公式サイトのモデルカテゴリから選択して使用するもので、現在利用可能なモデルは `text-embedding-3-small` と `text-embedding-3-large` です。`text-embedding-ada-002` は提供を終了しています。既存のベクトルインデックスでこの旧モデルを使用している場合、新しいモデルのベクトルを直接混在させることはできず、インデックスを再作成する必要があります。最後のパラメータは `input` で、`input` は単語ベクトルに変換する必要があるテキストです。 -また、右側には対応する呼び出しコードが生成されていることに注意してください。コードをコピーして直接実行することも、直接「Try」ボタンをクリックしてテストすることもできます。 +同時に、右側には対応する呼び出しコードが生成されていることに気付くでしょう。コードをコピーして直接実行することも、「Try」ボタンを直接クリックしてテストすることもできます。 -オプションのパラメータ： +オプションパラメータ： -- `dimensions`：ベクトルの次元を切り詰める。デフォルトでは完全な次元を出力します。 +- `dimensions`：ベクトル次元を切り詰めます。デフォルトでは完全な次元を出力します。 - `encoding_format`：返却形式。`float` または `base64` を選択できます。

@@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -呼び出し後、返された結果は以下の通りです： +呼び出し後、返却結果は以下のとおりです： ```json { @@ -97,7 +97,7 @@ print(response.text) ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,25 +105,25 @@ print(response.text) } ``` -返された結果には複数のフィールドがあり、以下のように説明されます： +返却結果には複数のフィールドがあり、以下のとおりです： -- `model`、今回のテキストを単語ベクトルに変換するために使用されたモデル。 -- `usage`、今回のテキストを単語ベクトルに変換するために使用されたトークン情報。 +- `model`、今回テキストを単語ベクトルに変換する際に使用したモデル。 +- `usage`、今回テキストを単語ベクトルに変換する際に使用した token 情報。 - `data`、テキスト変換後の単語ベクトル結果。 -その中で `data` はテキストに対応する単語ベクトルの具体的な情報を含んでおり、その中の `embedding` は生成された単語ベクトルの具体的な結果です。 +このうち `data` にはテキストに対応する単語ベクトルの詳細情報が含まれており、その中の `embedding` が生成された単語ベクトルの具体的な結果です。 ## エラー処理 -API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば： +API 呼び出し時にエラーが発生した場合、API は対応するエラーコードと情報を返します。例： -- `400 token_mismatched`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。 -- `400 api_not_implemented`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。 -- `401 invalid_token`：未認証、無効または不足している認証トークン。 -- `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。 -- `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。 +- `400 token_mismatched`：不正なリクエスト。パラメータの欠落または無効が原因である可能性があります。 +- `400 api_not_implemented`：不正なリクエスト。パラメータの欠落または無効が原因である可能性があります。 +- `401 invalid_token`：認証されていません。認証トークンが無効または欠落しています。 +- `429 too_many_requests`：リクエストが多すぎます。レート制限を超えています。 +- `500 api_error`：内部サーバーエラー。サーバー側で問題が発生しました。 -### エラー応答の例 +### エラー応答例 ```json { @@ -138,4 +138,4 @@ API を呼び出す際にエラーが発生した場合、API は対応するエ ## 結論 -この文書を通じて、OpenAI Embeddings API を使用して公式の OpenAI の単語ベクトル生成機能を簡単に利用する方法を理解しました。この文書が、API の接続と使用をより良くする手助けとなることを願っています。何か問題があれば、いつでも技術サポートチームにお問い合わせください。 +本ドキュメントを通じて、OpenAI Embeddings API を使用して、公式 OpenAI の単語ベクトル生成機能を簡単に利用する方法を理解できました。本ドキュメントが、この API の連携および使用により役立つことを願っています。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。 diff --git a/ja/guides/platform/wework_bot.mdx b/ja/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..c57ecc1c9 --- /dev/null +++ b/ja/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "WeCom ボット" +description: "Platform API guide - Ace Data Cloud" +--- + +自分専用の WeCom アカウントインスタンスをデプロイし、スマートフォンの WeCom で QR コードをスキャンしてログインし、REST API または MCP を通じてアカウント、連絡先、会話、およびローカル同期メッセージを読み取ります。インスタンスは通常の WeCom アカウントに対応し、オンプレミスサーバーや企業メールドメインの設定は不要です。 + +現在は Alpha です。アカウント読み取りは実際の会話での検証を完了しています。本人へのテキスト送信およびイベント読み戻しは実際の受け入れを完了しています。その他の連絡先、グループ操作、および新しいインスタンスの復元は、引き続きデプロイ環境での受け入れを完了する必要があります。メディア送信、引用返信、実際の @、グループメンバー管理、および配達確認はまだ公開されていません。インスタンスの `/api/capabilities` の戻り値を基準としてください。 + +## デプロイとログイン + +Deployment カテゴリでサービスを有効化し、インスタンスの期間プランを選択します。デプロイ後、管理ページを開き、アカウント本人の WeCom でスキャンしてください。スマートフォンでの確認またはその他のログイン手順が必要な場合は、リモートデスクトップを開き、そのインスタンスのデスクトップパスワードを入力してください。API 認証情報とデスクトップパスワードは独立しています。ログイン情報はインスタンスのディスクに保存され、コンテナを再作成してもディスクは保持されます。ディスクを削除するとローカルセッションが削除されます。 + +各インスタンスは個別に課金され、購入済みの期間に応じて稼働します。REST / MCP 呼び出しにはメッセージごとの追加料金はかかりません。実際の価格はプランページを基準としてください。現在は WeChat ボットの期間プランをデフォルトの参考としており、正式公開前に実行リソースと合わせて価格確認を完了する必要があります。 + +## API と MCP + +管理ページ内のインスタンス API アドレスを使用し、すべてのアカウントインターフェースで `Authorization: Bearer <インスタンス API token>` を付与します。これらのパスは専用インスタンスに属しており、共有 API ゲートウェイではありません。MCP アドレスはインスタンスアドレスに `/mcp/` を追加したものであり、同じ Bearer token を使用します。 + +| インターフェース | 役割 | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | アカウントの準備状況と機能一覧 | +| `GET /api/auth/qr` | 現在のログイン QR コード PNG Base64 | +| `GET /api/account` | 現在のアカウント | +| `GET /api/contacts?kind=all` | 社内同僚および外部連絡先。internal / external を指定可能 | +| `GET /api/conversations` | ローカル会話。元の会話 ID を保持 | +| `GET /api/messages` | ローカル同期メッセージ。conversation_id、after_rowid、limit パラメータ | +| `POST /api/search` | 連絡先、会話、およびローカルテキスト検索 | +| `POST /api/messages` | テキスト送信の非同期タスク。Idempotency-Key の指定が必須 | +| `POST /api/messages/send` | 同じ送信エントリ。単一または複数の対象をサポート | +| `GET /api/groups/{conversation_id}` | ローカル同期されたグループ情報およびメンバー | +| `GET /api/tasks` | 最近のタスクおよび各対象の結果 | +| `GET /api/tasks/{id}` | 送信結果の照会 | +| `POST /api/tasks/{id}/cancel` | まだ開始していないタスクをキャンセル | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | 自動化を一時停止。本人確認後に再開 | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | インスタンス状態と現在の画面。いずれも認証が必要 | +| `GET /api/events?after=0` | 再開可能なカーソルを持つメッセージイベント | +| `WS /ws` | メッセージイベントストリーム。Bearer 認証 | + +送信ボディには `target`、`type: "text"`、および `text` が含まれます。`target` は会話 ID、連絡先 ID、企業ユーザー ID、または一意の完全名を受け付けます。ID を優先して使用してください。表示名でなお一意に特定できない場合、インスタンスは操作を拒否し、対象を推測しません。ローカル会話がない連絡先については、まずクライアント経由で会話を開き、実際の会話 ID を確認してから送信します。リクエストヘッダーの `Idempotency-Key` は 8～128 文字の英字、数字、または `_.:-` です。同一操作への重複リクエストでは、同じキーと同じリクエストボディを再利用する必要があります。 + +`target` を `targets` 配列に置き換えると、明確に指定された 1～50 件の対象へ順番に送信できます。両方を同時に指定することはできません。すべての対象は先にID解決を完了し、同一オブジェクトを指す異なる別名は拒否されます。ある対象で失敗した後は後続の送信を停止し、タスク結果には対象ごとに `succeeded`、`failed`、`unknown`、または `not_attempted` が記録されます。部分的な成功を完全な成功として扱わないでください。このフローは、デプロイ環境において指定された連絡先での実際の受け入れも完了する必要があります。 + +タスクは queued、running、submitting、succeeded、failed、unknown、または cancelled の状態になる可能性があります。`succeeded` は、送信後に対応する会話記録で正確なテキストおよびサーバーメッセージ ID が見つかったことを意味します。`delivered` は依然として null であり、相手が受信したことを意味しません。unknown は結果が不明確であることを示します。履歴を確認し、新しいキーで送信を繰り返さないでください。インスタンスは中断したタスクを自動的に再送しません。 + +履歴にはクライアントがすでに同期した内容のみが含まれ、すべての履歴を保証するものではありません。非テキストメッセージは unknown タイプとして返される場合があり、添付ファイルのダウンロードはまだ公開されていません。イベントは直近 10,000 件を保持し、`gap` はカーソルが保持ウィンドウを超えたことを示します。初回接続時に、古い履歴を新しいメッセージとして再生することはありません。 + +メッセージ履歴内の `server_accepted` と `server_id` は、サーバーがローカルメッセージを受け入れたかどうかの照合に使用できます。ローカル記録のみが存在し、サーバー ID がない場合、送信成功と認定することはできません。これらのフィールドは、受信者が受信または既読したことを意味しません。イベント記録は生成時の状態を保持しており、現在の確認状態を照会するにはメッセージ履歴インターフェースを使用してください。 + +## アカウントと認証情報 + +本人が操作する権限を持つアカウントのみでログインしてください。API token は信頼できるアプリケーションに設定してください。これは当該インスタンスのアカウントデータにアクセスできます。パスワード、QR コード、またはチャットのスクリーンショットを公開場所に掲載しないでください。インスタンスを一時停止すると、リアルタイムイベントが中断されます。アカウントからログアウトした場合、またはスマートフォン側でデバイスを削除した場合は、再ログインが必要です。 + +現在、テキスト入力は単一行のみをサポートしており、改行は送信前に明示的に拒否されます。クライアントがセキュリティ認証または再ログインを要求した場合、アカウント本人がリモートデスクトップ上で完了する必要があります。インスタンスが認証を回避することはありません。認証中断後のタスクは unknown を返す可能性があります。まずメッセージ記録を照会し、新しい冪等キーで再送しないでください。 + +セキュリティ認証のプロンプト、アカウントのログアウト、または変更が検出されると、自動化キューは永続的に一時停止されます。スマートフォンでの認証完了後、インスタンスコンソールの「認証後に再開」から、まだ実行されていないタスクを続行できます。すでに送信済みで結果が不確かなタスクは再送されません。通常のリモートワークでも WeCom のセキュリティ認証がトリガーされる場合があります。公式説明にある、認証後 24 時間は再ロックされないウィンドウは、検知がなくなったことを意味せず、インスタンスが長期無人運用を保証できることも意味しません。 diff --git a/ko/guides/claude/claude_messages.mdx b/ko/guides/claude/claude_messages.mdx index 791562efd..b51bfb156 100644 --- a/ko/guides/claude/claude_messages.mdx +++ b/ko/guides/claude/claude_messages.mdx @@ -3,9 +3,9 @@ title: "Claude Messages API 신청 및 사용" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude는 매우 강력한 AI 대화 시스템으로, 프롬프트를 입력하기만 하면 단 몇 초 만에 매끄럽고 자연스러운 응답을 생성할 수 있습니다. Claude Messages API는 Anthropic 공식 네이티브 API 형식으로, OpenAI 호환 형식(Chat Completion)과 달리 Anthropic 자체 요청 및 응답 구조를 채택하여 멀티모달 콘텐츠 입력, 도구 호출, 확장 사고(Extended Thinking) 등의 고급 기능과 같은 Claude의 고유한 역량을 더 잘 활용할 수 있습니다. +Anthropic Claude는 매우 강력한 AI 대화 시스템으로, 프롬프트를 입력하기만 하면 단 몇 초 만에 매끄럽고 자연스러운 응답을 생성할 수 있습니다. Claude Messages API는 Anthropic 공식 네이티브 API 형식으로, OpenAI 호환 형식(Chat Completion)과 달리 Anthropic 자체 요청 및 응답 구조를 채택하여 멀티모달 콘텐츠 입력, 도구 호출, 심층 사고(Extended Thinking) 등의 고급 기능과 같은 Claude의 고유한 능력을 더 잘 활용할 수 있습니다. -본 문서는 주로 Claude Messages API 작업의 사용 절차를 소개하며, 이를 통해 Anthropic 공식과 일치하는 네이티브 인터페이스를 사용하여 Claude의 대화 기능을 호출할 수 있습니다. +이 문서는 주로 Claude Messages API 작업의 사용 절차를 소개하며, 이를 통해 Anthropic 공식과 일치하는 네이티브 인터페이스를 사용하여 Claude의 대화 기능을 호출할 수 있습니다. ## 신청 절차 @@ -13,31 +13,32 @@ Claude Messages API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://pl ![](https://cdn.acedata.cloud/dvc3cg.jpg) -아직 로그인하거나 등록하지 않은 경우, 등록 및 로그인을 안내하는 로그인 페이지로 자동 이동하며, 완료 후 현재 페이지로 자동 돌아옵니다. +아직 로그인하거나 등록하지 않았다면 로그인 페이지로 자동 이동하여 등록 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 반환됩니다. -**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스마다 별도로 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 공통 잔액을 충전할 수 있습니다. +**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 범용 잔액을 충전할 수 있습니다. > 📘 전체 문서: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## 기본 사용 -Claude Messages API의 요청 경로는 Anthropic 공식 API와 동일한 `/v1/messages`입니다. 최소한 다음 세 가지 필수 매개변수를 제공해야 합니다. +Claude Messages API의 요청 경로는 `/v1/messages`이며, Anthropic 공식 API와 일치합니다. 최소한 다음 세 가지 필수 매개변수를 제공해야 합니다: -- `model`: 사용할 Claude 모델을 선택합니다. `claude-opus-5-5`는 Messages API를 통해서만 제공되며, 100만 Token 컨텍스트와 최대 128K Token 출력을 지원하고 항상 적응형 사고를 활성화합니다. 최신 플래그십은 `claude-fable-5-1`(100만 Token 컨텍스트, 최대 128K Token 출력)이며, 기존 `claude-fable-5`도 계속 호환성을 유지합니다. `claude-sonnet-5-5`는 네이티브 Messages 시리즈 인터페이스에 추가되었으며, 이미지 입력과 적응형 사고를 지원합니다. 입력, 출력 및 캐시 읽기에 대한 공식 참고 가격은 각각 백만 Token당 2달러, 10달러 및 0.20달러입니다. -- `messages`: 입력 메시지 배열이며, 각 메시지는 `role`(역할)과 `content`(내용)를 포함하고, `role`은 `user`와 `assistant`를 지원합니다. -- `max_tokens`: 최대 출력 token 수이며, 단일 응답의 길이를 제한하는 데 사용됩니다. +- `model`: 사용할 Claude 모델을 선택합니다. `claude-opus-5-5`는 Messages API를 통해서만 제공되며, 100만 Token 컨텍스트, 최대 출력 128K Token을 지원하고 적응형 사고를 항상 활성화합니다. 최신 플래그십은 `claude-fable-5-1`(100만 Token 컨텍스트, 최대 출력 128K Token)이며, 기존 `claude-fable-5`도 계속 호환 유지됩니다. `claude-sonnet-5-5`는 네이티브 Messages 시리즈 인터페이스에 추가되었으며, 이미지 입력과 적응형 사고를 지원합니다. 입력, 출력 및 캐시 읽기에 대한 공식 참고 가격은 각각 백만 Token당 2, 10 및 0.20달러입니다. +- `messages`: 입력 메시지 배열로, 각 메시지는 `role`(역할)과 `content`(내용)를 포함하며, `role`은 `user`와 `assistant`를 지원합니다. +- `max_tokens`: 최대 출력 token 수로, 단일 응답의 길이를 제한하는 데 사용됩니다. 자주 사용하는 선택적 매개변수: -- `system`: 모델의 행동과 역할을 설정하는 시스템 프롬프트입니다. -- `temperature`: 생성의 무작위성이며, 0-1 사이입니다. 값이 클수록 응답이 더 다양해집니다. -- `stream`: 스트리밍 응답 사용 여부이며, `true`로 설정하면 글자 단위 반환 효과를 구현할 수 있습니다. -- `stop_sequences`: 사용자 정의 중지 시퀀스이며, 모델은 이러한 텍스트를 만나면 생성을 중지합니다. -- `top_p`: temperature와 함께 생성의 무작위성을 제어하는 핵 샘플링 매개변수입니다. -- `top_k`: 확률이 가장 높은 K개의 옵션에서만 샘플링합니다. -- `tools`: 모델이 외부 함수를 호출하도록 하는 도구 정의입니다. +- `system`: 시스템 프롬프트로, 모델의 행동과 역할을 설정하는 데 사용됩니다. +- `temperature`: 생성 무작위성으로, 0-1 사이이며 값이 클수록 응답이 더 발산됩니다. +- `stream`: 스트리밍 응답 사용 여부로, `true`로 설정하면 한 글자씩 반환하는 효과를 구현할 수 있습니다. +- `stop_sequences`: 사용자 지정 중지 시퀀스로, 모델은 이러한 텍스트를 만나면 생성을 중지합니다. +- `top_p`: 핵 샘플링 매개변수로, temperature와 함께 생성의 무작위성을 제어합니다. +- `top_k`: 확률이 가장 높은 K개 옵션에서만 샘플링합니다. +- `tools`: 도구 정의로, 모델이 외부 함수를 호출하도록 하는 데 사용됩니다. - `tool_choice`: 모델이 제공된 도구를 사용하는 방식을 제어합니다. -- `cache_control`: 요청의 마지막 캐시 가능한 콘텐츠 블록 위치에 자동으로 캐시 중단점을 생성합니다. 특정 콘텐츠 블록에 작성할 수도 있습니다. +- `cache_control`: 요청의 마지막 캐시 가능한 콘텐츠 블록에서 자동으로 캐시 중단점을 생성하며, 구체적인 콘텐츠 블록에 작성할 수도 있습니다. +- `metadata`: 선택적 요청 메타데이터 객체입니다. `metadata.user_id`는 문자열로, 예를 들어 `{"user_id":"example-user-001"}`와 같이 호출자 맞춤 사용자 식별자를 전달할 수 있으며, 개인 정보를 포함하지 않는 안정적인 식별자를 사용하는 것이 권장됩니다. 이는 `Authorization` 인증을 대체하지 않으며, `messages` 대화 내용에 작성할 필요도 없습니다. ### cURL 예시 @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -호출 후 반환 결과는 다음과 같습니다. +호출 후 반환 결과는 다음과 같습니다: ```json { @@ -107,24 +110,24 @@ print(response.json()) ``` 반환 결과 필드 설명: - - `id`: 이번 메시지의 고유 식별자입니다. - `type`: 항상 `message`입니다. - `role`: 항상 `assistant`입니다. -- `content`: 응답 콘텐츠 배열이며, 각 요소는 `type`(예: `text`) 및 해당 콘텐츠를 포함합니다. -- `model`: 요청을 처리한 모델 이름입니다. -- `stop_reason`: 중지 사유입니다. 안정적인 값에는 `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn`(계속하려면 현재 assistant 콘텐츠를 원본 그대로 다시 전달할 수 있음), `refusal`, `model_context_window_exceeded`가 포함됩니다. -- `stop_sequence`: 사용자 정의 중지 시퀀스로 인해 중지된 경우, 일치한 중지 시퀀스 텍스트를 표시합니다. -- `stop_details`: `stop_reason`이 `refusal`인 경우, 거부 범주와 설명을 포함할 수 있습니다. -- `usage`: token 사용 통계입니다. `input_tokens`는 캐시되지 않은 입력이며, `cache_creation_input_tokens`와 `cache_read_input_tokens`는 각각 캐시 쓰기와 읽기입니다. `output_tokens`는 전체 출력 token 수입니다. `output_tokens_details.thinking_tokens`가 반환되는 경우, 이 값은 `output_tokens`의 하위 집합이므로 총량이나 비용을 계산할 때 다시 더하지 마세요. 이 세부 정보는 권위 있는 집계가 없을 경우 `null`이거나 생략될 수 있습니다. -- `usage.cache_creation`: 선택적인 캐시 쓰기 TTL 세부 정보이며, `ephemeral_5m_input_tokens`와 `ephemeral_1h_input_tokens`를 포함합니다. 객체가 존재할 경우 두 항목의 합은 `cache_creation_input_tokens`와 같으며, 필드가 `null`이거나 생략된 것은 현재 응답에 사용 가능한 TTL 분할이 없음을 의미하므로 `0`으로 해석할 수 없습니다. -- `usage.cost`: 비스트리밍 응답에는 Ace Data Cloud가 기록한 크레딧 소모 객체가 포함될 수 있으며, 그중 `amount`는 이번 실제 소모량, `currency`는 계량 단위, `list_amount`는 할인 전 금액(있는 경우)입니다. Fable 5.1의 공식 캐시 읽기 기준 가격은 백만 Token당 $0.25이며, 5분 및 1시간 캐시 쓰기 기준 가격은 각각 $12.50 및 $20/백만 Token입니다. 플랫폼 실제 가격은 요금제 할인에 따라 환산됩니다. +- `content`: 응답 내용 배열이며, 각 요소는 `type`(예: `text`)과 해당 내용을 포함합니다. +- `model`: 요청을 처리하는 모델 이름입니다. +- `stop_reason`: 중지 이유입니다. 안정적인 값에는 `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn`(현재 assistant 내용을 원본 그대로 다시 전달하여 계속 진행 가능), `refusal`, `model_context_window_exceeded`가 포함됩니다. +- `stop_sequence`: 사용자 지정 중지 시퀀스로 인해 중지된 경우, 일치한 중지 시퀀스 텍스트를 표시합니다. +- `stop_details`: `stop_reason`이 `refusal`인 경우, 거부 카테고리와 설명을 포함할 수 있습니다. +- `usage`: token 사용 통계입니다. `input_tokens`는 캐시되지 않은 입력이고, `cache_creation_input_tokens`와 `cache_read_input_tokens`는 각각 캐시 쓰기와 읽기이며, `output_tokens`는 전체 출력 token 수입니다. `output_tokens_details.thinking_tokens`가 반환되는 경우, 이 값은 `output_tokens`의 하위 집합이므로 총량 또는 비용 계산 시 다시 더하지 마십시오. 이 세부 정보는 권위 있는 집계가 없을 경우 `null`이거나 생략될 수 있습니다. +- `usage.cache_creation`: 선택적 캐시 쓰기 TTL 세부 정보로, `ephemeral_5m_input_tokens`와 `ephemeral_1h_input_tokens`를 포함합니다. 객체가 존재하는 경우 두 항목의 합은 `cache_creation_input_tokens`와 같으며, 필드가 `null`이거나 생략된 경우 현재 응답에 사용 가능한 TTL 분류가 없다는 의미이지 `0`으로 해석해서는 안 됩니다. +- `usage.cost`: 비스트리밍 응답에는 Ace Data Cloud가 기록한 크레딧 소비 객체가 포함될 수 있으며, 이 중 `amount`는 이번 실제 소비량, `currency`는 측정 단위, `list_amount`는 할인 전 금액(있는 경우)입니다. Fable 5.1의 공식 캐시 읽기 기본 가격은 $0.25/백만 Token이고, 5분 및 1시간 캐시 쓰기 기본 가격은 각각 $12.50 및 $20/백만 Token입니다. 플랫폼 실제 가격은 요금제 할인에 따라 환산됩니다. ## 시스템 프롬프트 -Claude Messages API는 `system` 필드를 통해 시스템 프롬프트를 설정할 수 있으며, 모델의 행동, 역할 및 컨텍스트를 정의하는 데 사용됩니다. +Claude Messages API는 모델의 행동, 역할 및 컨텍스트를 정의하는 데 사용되는 `system` 필드를 통해 시스템 프롬프트 설정을 지원합니다. ### Python 예시 + ```python import requests @@ -149,13 +152,13 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -`system` 프롬프트를 설정하면 Claude의 역할과 행동 방식을 정밀하게 제어할 수 있습니다. +`system` 프롬프트를 설정하면 Claude의 역할과 행동 방식을 정확하게 제어할 수 있습니다. ## 스트리밍 응답 -이 인터페이스는 스트리밍 응답도 지원하며, `stream` 매개변수를 `true`로 설정하면 단계적으로 반환되는 효과를 얻을 수 있어 웹페이지에서 한 글자씩 표시하는 기능을 구현하기에 매우 적합합니다. +이 인터페이스는 스트리밍 응답도 지원하며, `stream` 매개변수를 `true`로 설정하면 점진적으로 반환되는 효과를 얻을 수 있어 웹페이지에서 글자 단위 표시를 구현하는 데 매우 적합합니다. -### Python 예제 +### Python 예시 ```python import requests @@ -185,12 +188,12 @@ for line in response.iter_lines(): 스트리밍 응답은 Server-Sent Events (SSE) 형식으로 반환되며, 각 줄은 `event:` 및 `data:`로 시작합니다. 스트리밍 이벤트 유형에는 다음이 포함됩니다. -- `message_start`: 메시지 시작, 메시지의 기본 정보와 모델 이름을 포함합니다. -- `content_block_start`: 콘텐츠 블록 시작. -- `content_block_delta`: 콘텐츠 블록 증분 업데이트, 새로 생성된 텍스트 조각을 포함합니다. -- `content_block_stop`: 콘텐츠 블록 종료. -- `message_delta`: 메시지 수준의 증분 업데이트로, `stop_reason` 및 최종 `usage` 정보를 포함합니다. `output_tokens_details.thinking_tokens`의 권위 있는 값은 마지막 `message_delta.usage`에서만 읽어야 하며, 이벤트 간에 누적하지 마십시오. -- `message_stop`: 메시지 종료. +- `message_start`: 메시지 시작으로, 메시지의 기본 정보와 모델 이름을 포함합니다. +- `content_block_start`: 콘텐츠 블록 시작입니다. +- `content_block_delta`: 콘텐츠 블록 증분 업데이트로, 새로 생성된 텍스트 조각을 포함합니다. +- `content_block_stop`: 콘텐츠 블록 종료입니다. +- `message_delta`: 메시지 수준의 증분 업데이트로, `stop_reason`과 최종 `usage` 정보를 포함합니다. `output_tokens_details.thinking_tokens`의 권위 있는 값은 마지막 `message_delta.usage`에서만 읽어야 하며, 이벤트 간에 누적하지 마십시오. +- `message_stop`: 메시지 종료입니다. 출력 효과는 다음과 같습니다. @@ -220,9 +223,9 @@ event: message_stop data: {"type":"message_stop"} ``` -보시다시피 스트리밍 응답의 `content_block_delta` 이벤트에는 단계적으로 생성되는 텍스트 내용이 포함되어 있으며, 모든 `text_delta`를 연결하면 완전한 응답을 얻을 수 있습니다. +알 수 있듯이, 스트리밍 응답의 `content_block_delta` 이벤트에는 점진적으로 생성되는 텍스트 내용이 포함되어 있으며, 모든 `text_delta`를 연결하면 완전한 응답을 얻을 수 있습니다. -### JavaScript 예제 +### JavaScript 예시 ```javascript const options = { @@ -253,9 +256,9 @@ while (true) { ## 다중 턴 대화 -다중 턴 대화 기능을 연동하려면 `messages` 배열에서 `user`와 `assistant` 역할의 메시지를 번갈아 배치하고, 이전 대화 기록을 함께 전달해야 합니다. +다중 턴 대화 기능을 연동하려면, `messages` 배열에서 `user`와 `assistant` 역할의 메시지를 번갈아 배치하고 이전 대화 기록을 함께 전달해야 합니다. -### Python 예제 +### Python 예시 ```python import requests @@ -283,7 +286,6 @@ print(response.json()) ``` 반환 결과는 다음과 같습니다. - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,11 +307,11 @@ print(response.json()) } ``` -`messages`에서 전체 대화 기록을 전달하면 Claude는 문맥을 결합하여 정확하게 답변할 수 있습니다. +`messages`에 전체 대화 기록을 전달하면 Claude는 문맥을 결합하여 정확하게 답변할 수 있습니다. ## 심층 사고 모델 -Claude의 thinking과 thinking summary는 서로 다른 두 가지 개념입니다. 모델은 내부 추론을 수행할 수 있지만, API는 원본 사고 사슬을 반환하지 않습니다. 추론 과정을 표시해야 할 때 API가 반환하는 것은 처리된 요약입니다. +Claude의 thinking과 thinking summary는 서로 다른 두 개념입니다. 모델은 내부 추론을 수행할 수 있지만, API는 원본 사고 사슬을 반환하지 않습니다. 추론 과정을 표시해야 할 때 API가 반환하는 것은 처리된 요약입니다. 현재 모델에서는 adaptive thinking 사용을 권장하며, `output_config.effort`를 통해 전체 추론 투입량을 제어합니다. @@ -350,20 +352,21 @@ print(response.json()) "signature": "opaque-signature" } ``` -- `display: "summarized"`는 읽을 수 있는 사고 요약을 반환합니다. 원시 사고 체인은 아닙니다. -- `display: "omitted"`는 `thinking: ""`를 반환하지만, 후속 대화를 지원하기 위해 opaque `signature`는 계속 유지합니다. -- `display: "updates"`는 Anthropic의 beta 모드이며, `anthropic-beta: thinking-display-updates-2026-08-18`를 포함해야 합니다. 공식 정의는 추론 본문을 숨기고 도구 호출 사이에 짧은 진행 상황 업데이트를 표시하는 것입니다. 플랫폼은 해당 매개변수와 beta 요청 헤더를 원래 값대로 전달하며, 강제로 `summarized`로 다시 작성하지 않습니다. 실제 출력 내용은 선택한 모델의 지원 여부에 따라 달라집니다. -- `thinking`, `output_config`, effort, 샘플링 매개변수 및 새 확장 필드는 원래 값대로 전달됩니다. 플랫폼은 모델별로 하드코딩된 값 열거형이나 조합 제한을 유지하지 않으며, thinking 모드를 자동으로 다시 작성하지도 않습니다. 이러한 매개변수를 수락할지 여부는 선택한 모델이 판단하며, 모델이 반환한 매개변수 오류는 클라이언트로 전달됩니다. -- Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 및 Opus 4.7의 display 기본값은 `omitted`입니다. Opus 4.6, Sonnet 4.6 및 그 이전의 thinking 지원 모델은 기본적으로 `summarized`를 사용합니다. -- Display는 반환 내용과 스트리밍 지연에만 영향을 미치며, 추론을 끄거나 thinking token 청구를 줄이지 않습니다. -- thinking이 기본적으로 활성화되는지 여부와 display 기본값은 두 가지 별개의 문제입니다. Opus 5, Sonnet 5는 기본적으로 adaptive thinking을 활성화합니다. Opus 5의 경우 `thinking`을 생략하는 것은 adaptive와 같고, `output_config.effort`를 생략하는 것은 `high`와 같습니다. Opus 4.8, 4.7 및 4.6은 명시적으로 활성화해야 합니다. -- Thinking과 최종 본문은 함께 `max_tokens` 출력 예산을 사용합니다. 예산이 너무 작으면 thinking이 대부분의 한도를 차지하여 본문이 비어 있거나 잘릴 수 있습니다. `max_tokens`를 늘리거나 `low` / `medium` effort를 사용하여 추론 투입량을 제어하세요. -- thinking을 끌 수 있는 모델의 경우 `thinking: {"type":"disabled"}`를 전달할 수 있습니다. `between_tools` 등의 새 모드 및 effort 조합은 선택한 모델에 따라 달라집니다. 플랫폼은 이전 모델 규칙에 따라 미리 거부하지 않습니다. -- 고정 사고 예산은 `budget_tokens`를 통해 전달할 수 있습니다. 새 모델은 일반적으로 `thinking.type=adaptive` 및 `output_config.effort`를 사용합니다. 고정 예산 또는 사고 비활성화 지원 여부는 선택한 모델의 현재 기능을 기준으로 합니다. -- 여러 차례의 대화 및 도구 호출 시 assistant가 반환한 완전한 thinking 블록과 signature를 원래대로 다시 전달해야 합니다. signature를 수정하거나 직접 생성하지 마세요. -- 매개변수 전달이 모든 모델이 모든 기능을 지원한다는 의미는 아닙니다. 프로토콜 간 호출은 여전히 변환이 필요하며, `redacted_thinking` 등의 콘텐츠 지원 범위와 오류는 실제로 요청을 처리하는 모델 서비스가 결정합니다. - -스트리밍 요청에서 `summarized`는 `thinking_delta`를 생성합니다. `omitted`는 `thinking_delta`를 생성하지 않고, thinking 블록 수명 주기와 `signature_delta`만 유지합니다. + +- `display: "summarized"`는 읽을 수 있는 사고 요약을 반환합니다. 이는 원본 사고 사슬이 아닙니다. +- `display: "omitted"`는 `thinking: ""`를 반환하지만, 이후 대화를 지원하기 위해 opaque `signature`는 유지합니다. +- `display: "updates"`는 Anthropic의 beta 모드이며, `anthropic-beta: thinking-display-updates-2026-08-18`를 포함해야 합니다. 공식 정의는 추론 본문을 숨기고 도구 호출 사이의 짧은 진행 업데이트를 표시하는 것입니다. 플랫폼은 이 파라미터와 beta 요청 헤더를 원래 값 그대로 전달하며, `summarized`로 강제 변경하지 않습니다. 실제 출력 내용은 선택한 모델의 지원 여부에 따라 달라집니다. +- `thinking`, `output_config`, effort, 샘플링 파라미터 및 새 확장 필드는 원래 값 그대로 전달됩니다. 플랫폼은 모델별로 하드코딩된 값 열거나 조합 제한을 유지하지 않으며, thinking 모드를 자동으로 변경하지도 않습니다. 이 파라미터를 수락할지는 선택한 모델이 판단하며, 모델이 반환한 파라미터 오류는 클라이언트에 전달됩니다. +- Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 및 Opus 4.7의 display 기본값은 `omitted`이며, Opus 4.6, Sonnet 4.6 및 그 이전의 thinking 지원 모델은 기본적으로 `summarized`를 사용합니다. +- Display는 반환 내용과 스트리밍 지연에만 영향을 미치며, 추론을 끄거나 thinking token 청구량을 줄이지 않습니다. +- thinking이 기본적으로 활성화되는지와 display 기본값은 서로 독립적인 두 문제입니다. Opus 5와 Sonnet 5는 기본적으로 adaptive thinking을 활성화하며, Opus 5의 경우 `thinking`을 생략하는 것은 adaptive와 같고, `output_config.effort`를 생략하는 것은 `high`와 같습니다. Opus 4.8, 4.7 및 4.6은 명시적으로 활성화해야 합니다. +- Thinking과 최종 본문은 함께 `max_tokens` 출력 예산을 사용합니다. 예산이 너무 작으면 thinking이 대부분의 할당량을 차지하여 본문이 비어 있거나 잘릴 수 있습니다. `max_tokens`를 늘리거나 `low` / `medium` effort를 사용하여 추론 투입량을 제어하십시오. +- thinking을 끌 수 있는 모델의 경우 `thinking: {"type":"disabled"}`를 전달할 수 있습니다. `between_tools` 등의 새 모드와 effort 조합은 선택한 모델에 따라 달라지며, 플랫폼은 이전 모델 규칙에 따라 사전에 거부하지 않습니다. +- 고정 사고 예산은 `budget_tokens`를 통해 전달할 수 있습니다. 새 모델은 일반적으로 `thinking.type=adaptive`와 `output_config.effort`를 사용합니다. 고정 예산 또는 사고 비활성화 지원 여부는 선택한 모델의 현재 기능을 기준으로 합니다. +- 다중 턴 대화 및 도구 호출 시 assistant가 반환한 전체 thinking 블록과 signature를 원래대로 다시 전달해야 합니다. signature를 수정하거나 직접 생성하지 마십시오. +- 파라미터 전달이 모든 모델이 모든 기능을 지원한다는 의미는 아닙니다. 프로토콜 간 호출은 여전히 변환이 필요하며, `redacted_thinking` 등의 내용 지원 범위와 오류는 실제로 요청을 처리하는 모델 서비스가 결정합니다. + +스트리밍 요청에서 `summarized`는 `thinking_delta`를 생성하며, `omitted`는 `thinking_delta`를 생성하지 않고 thinking 블록 수명 주기와 `signature_delta`만 유지합니다. ## 비전 모델 @@ -456,7 +459,6 @@ print(response.json()) ``` ### cURL 예시 - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -490,7 +492,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ ## 문서 및 PDF -PDF는 `document` 콘텐츠 블록을 사용하며, Base64와 URL의 두 가지 안정적인 소스를 지원합니다. Base64 소스는 반드시 `application/pdf`를 사용해야 합니다. +PDF는 `document` 콘텐츠 블록을 사용하며, Base64와 URL이라는 두 가지 안정적인 소스를 지원합니다. Base64 소스는 반드시 `application/pdf`를 사용해야 합니다: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -URL 소스는 `{"type":"url","url":"https://example.com/report.pdf"}`로 작성합니다. `document`는 `text/plain` 및 text/image 블록으로 구성된 `content` 소스도 지원합니다. 선택적 필드에는 `title`, `context`, `citations`가 포함됩니다. Files API의 `file_id` 소스는 별도의 beta 기능에 속하며, 이 인터페이스의 안정적인 계약에 포함되지 않습니다. +URL 소스는 `{"type":"url","url":"https://example.com/report.pdf"}`로 작성합니다. `document`는 `text/plain`과 text/image 블록으로 구성된 `content` 소스도 지원합니다. 선택적 필드에는 `title`, `context`, `citations`가 포함됩니다. Files API의 `file_id` 소스는 독립적인 beta 기능에 속하며, 본 인터페이스의 안정적인 계약에 포함되지 않습니다. ## 프롬프트 캐싱 -최상위 `cache_control`은 캐시 중단점을 마지막 캐시 가능 블록에 자동으로 배치합니다. +최상위 `cache_control`은 마지막 캐시 가능한 블록에 캐시 중단점을 자동으로 배치합니다: ```python payload = { @@ -534,9 +536,10 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -정확한 위치 제어가 필요할 때는 동일한 `cache_control`을 text, image, document, tool_use, tool_result 콘텐츠 블록 또는 도구 정의에 작성할 수도 있습니다. `ttl`은 `5m`(기본값) 및 `1h`를 지원합니다. `usage.cache_creation_input_tokens` 및 `usage.cache_read_input_tokens`를 통해 캐시 쓰기와 적중을 판단하십시오. -응답이 `usage.cache_creation`을 제공할 때, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`입니다. `cache_creation`이 `null`이거나 생략된 경우, 캐시 쓰기 총량만 있고 권위 있는 TTL 분할은 없음을 의미합니다. 이때 어떤 bucket도 알려진 0으로 간주하지 마십시오. 과금과 총량은 여전히 aggregate 필드를 기준으로 합니다. +위치를 정확하게 제어해야 하는 경우, 동일한 `cache_control`을 text, image, document, tool_use, tool_result 콘텐츠 블록 또는 도구 정의에 작성할 수도 있습니다. `ttl`은 `5m`(기본값) 및 `1h`를 지원합니다. `usage.cache_creation_input_tokens` 및 `usage.cache_read_input_tokens`를 통해 캐시 쓰기 및 적중 여부를 판단하십시오. + +응답이 `usage.cache_creation`을 제공하는 경우, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`입니다. `cache_creation`이 `null`이거나 생략된 경우, 캐시 쓰기 총량만 있고 권위 있는 TTL 분할이 없음을 의미합니다. 이때 어느 bucket도 알려진 0으로 간주하지 마십시오. 과금 및 총량은 여전히 aggregate 필드를 기준으로 합니다. 반환 결과 예시: @@ -561,9 +564,9 @@ payload = { } ``` -## 도구 호출（Tool Use） +## 도구 호출(Tool Use) -Claude Messages API는 도구 호출 기능을 기본으로 지원하며, 모델이 필요할 때 미리 정의한 도구/함수를 호출할 수 있도록 합니다. +Claude Messages API는 도구 호출 기능을 기본적으로 지원하며, 모델이 필요할 때 사전 정의한 도구/함수를 호출할 수 있도록 합니다. ### Python 예시 @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -모델이 도구 호출을 결정하면, 반환 결과의 `content`에는 `tool_use` 유형의 콘텐츠 블록이 포함됩니다: +모델이 도구 호출을 결정하면 반환 결과의 `content`에는 `tool_use` 유형의 콘텐츠 블록이 포함됩니다: ```json { @@ -637,7 +640,7 @@ print(response.json()) } ``` -`stop_reason`이 `tool_use`인 것에 유의하십시오. 이는 모델이 도구를 호출해야 함을 나타냅니다. 이 결과를 받은 후, 도구 함수를 실행하고 결과를 `tool_result` 형식으로 모델에 다시 전달해야 합니다: +`stop_reason`이 `tool_use`인 점에 유의하십시오. 이는 모델이 도구를 호출해야 함을 의미합니다. 해당 결과를 받은 후에는 도구 함수를 실행하고 결과를 `tool_result` 형식으로 모델에 다시 전달해야 합니다: ```python payload = { @@ -691,31 +694,30 @@ print(response.json()) Ace Data Cloud는 두 가지 Claude API 형식을 동시에 제공하며, 두 형식의 주요 차이점은 다음과 같습니다: -Messages API의 `usage.input_tokens`는 캐시되지 않은 입력만을 나타내며, `cache_read_input_tokens`와 `cache_creation_input_tokens`는 독립적인 과금 버킷입니다. 세 항목은 각각 해당 가격에 따라 계산됩니다. - +Messages API의 `usage.input_tokens`는 캐시되지 않은 입력만 나타내며, `cache_read_input_tokens`와 `cache_creation_input_tokens`는 독립적인 과금 버킷입니다. 세 항목은 각각 해당 가격에 따라 계산됩니다. | 특성 | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | 형식 | Anthropic 네이티브 형식 | OpenAI 호환 형식 | -| 시스템 프롬프트 | 독립적인 `system` 필드 | `messages`의 `role: "system"`을 통해 전달 | +| 시스템 프롬프트 | 독립적인 `system` 필드 | `messages` 내의 `role: "system"`을 통해 전달 | | 응답 구조 | `content` 배열(여러 유형 지원) | `choices` 배열(`message` 포함) | | 스트리밍 형식 | SSE 이벤트(여러 이벤트 유형) | SSE `data` 행 | -| 심층 사고 | 네이티브 `thinking` 및 `output_config.effort` | 모델 기본 전략 및 호환 파라미터 | +| 심층 사고 | 네이티브 `thinking` 및 `output_config.effort` | 모델 기본 정책 및 호환 파라미터 | | 도구 호출 | 네이티브 `tools` + `input_schema` | OpenAI 호환 `tools` 형식 | | Token 통계 | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -시스템이 이미 OpenAI 형식의 API와 연동되어 있다면 Chat Completion API를 사용하여 원활하게 전환할 수 있습니다. Claude의 모든 네이티브 기능을 사용해야 한다면 Messages API 사용을 권장합니다. +시스템이 이미 OpenAI 형식의 API와 연동되어 있다면 Chat Completion API를 사용하여 원활하게 전환할 수 있습니다. Claude의 모든 네이티브 기능을 사용해야 하는 경우 Messages API 사용을 권장합니다. ## 오류 처리 -공개 인터페이스의 오류 응답은 Ace Data Cloud 플랫폼 envelope를 사용합니다: `error.code`는 안정적인 오류 코드이고, `error.message`는 설명이며, `trace_id`는 요청을 조사하는 데 사용됩니다. 일반적인 HTTP 상태는 다음과 같습니다: +공개 인터페이스의 오류 응답은 Ace Data Cloud 플랫폼 envelope를 사용합니다. `error.code`는 안정적인 오류 코드이고, `error.message`는 설명이며, `trace_id`는 요청을 조사하는 데 사용됩니다. 일반적인 HTTP 상태는 다음과 같습니다. -- `400`: 요청 파라미터 또는 프로토콜 콘텐츠가 유효하지 않습니다. +- `400`: 요청 파라미터 또는 프로토콜 내용이 유효하지 않습니다. - `401`: 인증 토큰이 유효하지 않거나, 누락되었거나, 만료되었습니다. - `403`: 접근이 금지되었거나, 잔액이 부족하거나, 할당량이 제한되었습니다. - `404`: API 또는 모델이 존재하지 않습니다. - `413`: 요청 본문이 너무 큽니다. - `429`: 요청이 너무 많습니다. -- `500` / `503` / `504`: 서비스 오류, 일시적으로 사용할 수 없거나 처리 시간이 초과되었습니다. +- `500` / `503` / `504`: 서비스 오류, 일시적 사용 불가 또는 처리 시간 초과입니다. ### 오류 응답 예시 @@ -729,7 +731,8 @@ Messages API의 `usage.input_tokens`는 캐시되지 않은 입력만을 나타 } ``` -이 오류 구조는 Ace Data Cloud의 런타임 계약이며, Anthropic 공식 오류 envelope와 동일하지 않습니다. HTTP 상태 및 `error.code`에 따라 처리하십시오. +이 오류 구조는 Ace Data Cloud의 런타임 계약이며, Anthropic 공식 오류 envelope와 동일하지 않습니다. HTTP 상태와 `error.code`에 따라 처리하십시오. ## 결론 -이 문서를 통해 Anthropic 네이티브 형식으로 Claude Messages API를 사용하여 Claude의 대화 기능을 호출하는 방법을 이미 알아보았습니다. Messages API는 기본 대화, 시스템 프롬프트, 스트리밍 응답, 다중 턴 대화, 확장 사고, 시각적 이해, PDF, 프롬프트 캐싱 및 도구 호출 등 풍부한 기능을 지원합니다. 궁금한 점이 있으시면 언제든지 기술 지원팀에 문의해 주세요. + +이 문서를 통해 Anthropic 네이티브 형식으로 Claude Messages API를 사용하여 Claude의 대화 기능을 호출하는 방법을 이해했습니다. Messages API는 기본 대화, 시스템 프롬프트, 스트리밍 응답, 멀티턴 대화, 심층 사고, 시각적 이해, PDF, 프롬프트 캐싱 및 도구 호출 등의 풍부한 기능을 지원합니다. 궁금한 사항이 있으면 언제든지 기술 지원 팀에 문의하십시오. diff --git a/ko/guides/openai/openai_embeddings.mdx b/ko/guides/openai/openai_embeddings.mdx index b2fe8540d..6a978e5d7 100644 --- a/ko/guides/openai/openai_embeddings.mdx +++ b/ko/guides/openai/openai_embeddings.mdx @@ -3,40 +3,40 @@ title: "OpenAI Embeddings API 신청 및 사용" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI 단어 벡터 서비스는 입력 텍스트를 나타내는 단어 벡터 결과를 생성하는 데 사용됩니다. +입력 텍스트를 나타내는 임베딩 결과를 생성하는 데 사용되는 OpenAI 임베딩 서비스입니다. -이 문서는 OpenAI Embeddings API 작업의 사용 프로세스를 주로 설명하며, 이를 통해 입력 텍스트를 나타내는 임베딩 벡터를 생성할 수 있습니다. +이 문서는 주로 OpenAI Embeddings API 작업의 사용 절차를 소개하며, 이를 통해 입력 텍스트를 나타내는 임베딩 벡터를 생성할 수 있습니다。。 -## 신청 프로세스 +## 신청 절차 -OpenAI Embeddings API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 받아야 합니다. 이를 보관해 두세요. +OpenAI Embeddings API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 발급받아 예비용으로 보관하세요. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -로그인 또는 등록이 되어 있지 않은 경우, 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. +아직 로그인하거나 등록하지 않은 경우, 등록 및 로그인을 안내하는 로그인 페이지로 자동 이동하며, 완료 후 현재 페이지로 자동 반환됩니다. -**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다.** 처음 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있습니다; 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 일반 잔액을 충전할 수 있습니다. +**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다.** 최초 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있으며, 할당량이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 공용 잔액을 충전할 수 있습니다. > 📘 전체 문서: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) ## 기본 사용 -이제 인터페이스에 해당 내용을 입력할 수 있습니다. 아래 그림과 같이 진행하세요: +이제 화면에서 해당 내용을 입력할 수 있으며, 아래 그림과 같습니다:

-이 인터페이스를 처음 사용할 때는 최소한 세 가지 내용을 입력해야 합니다. 하나는 `authorization`으로, 드롭다운 목록에서 선택하면 됩니다. 다른 매개변수는 `model`로, `model`은 OpenAI 공식 모델 카테고리를 선택하는 것입니다. 여기에는 주로 3가지 모델이 있으며, 자세한 내용은 제공된 모델을 참조하세요. 마지막 매개변수는 `input`으로, `input`은 변환할 단어 벡터 텍스트입니다. +이 인터페이스를 처음 사용할 때는 최소 세 가지 내용을 입력해야 합니다. 하나는 `authorization`이며, 드롭다운 목록에서 직접 선택하면 됩니다. 또 다른 매개변수는 `model`이며, `model`은 OpenAI 공식 웹사이트 모델 유형 중에서 선택하여 사용하는 것입니다. 현재 사용 가능한 모델은 `text-embedding-3-small` 및 `text-embedding-3-large`입니다. `text-embedding-ada-002`는 제공이 중단되었습니다. 기존 벡터 인덱스에서 해당 이전 모델을 사용하는 경우 새 모델의 벡터와 직접 혼용할 수 없으며, 인덱스를 다시 생성해야 합니다. 마지막 매개변수는 `input`이며, `input`은 변환해야 하는 임베딩 텍스트입니다. -또한 오른쪽에 해당 호출 코드 생성이 있으며, 코드를 복사하여 직접 실행할 수도 있고, "Try" 버튼을 클릭하여 테스트할 수도 있습니다. +동시에 오른쪽에 해당 호출 코드가 생성되는 것을 확인할 수 있으며, 코드를 복사하여 직접 실행하거나 「Try」 버튼을 직접 클릭하여 테스트할 수도 있습니다. -선택적 매개변수: +선택 매개변수: -- `dimensions`: 벡터 차원 자르기, 기본적으로 전체 차원을 출력합니다. -- `encoding_format`: 반환 형식, 선택 가능 `float` 또는 `base64`입니다. +- `dimensions`: 벡터 차원을 자르며, 기본적으로 전체 차원을 출력합니다. +- `encoding_format`: 반환 형식으로, `float` 또는 `base64`를 선택할 수 있습니다.

-Python 샘플 호출 코드: +Python 예시 호출 코드: ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -호출 후, 반환 결과는 다음과 같습니다: +호출 후 반환 결과는 다음과 같습니다: ```json { @@ -97,7 +97,7 @@ print(response.text) ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,23 +105,23 @@ print(response.text) } ``` -반환 결과는 여러 필드를 포함하며, 다음과 같이 설명됩니다: +반환 결과에는 여러 필드가 있으며, 다음과 같이 소개합니다: -- `model`, 이번 텍스트를 단어 벡터로 변환하는 데 사용된 모델입니다. -- `usage`, 이번 텍스트를 단어 벡터로 변환하는 데 사용된 토큰 정보입니다. -- `data`, 텍스트 변환 후의 단어 벡터 결과입니다. +- `model`: 이번 텍스트를 임베딩으로 변환할 때 사용한 모델입니다. +- `usage`: 이번 텍스트를 임베딩으로 변환할 때 사용한 token 정보입니다. +- `data`: 텍스트 변환 후의 임베딩 결과입니다. -그 중 `data`는 텍스트에 해당하는 단어 벡터의 구체적인 정보를 포함하고 있으며, 그 안의 `embedding`은 생성된 단어 벡터의 구체적인 결과입니다. +그중 `data`에는 텍스트에 해당하는 임베딩의 구체적인 정보가 포함되어 있으며, 그 안의 `embedding`은 생성된 임베딩의 구체적인 결과입니다. ## 오류 처리 -API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어: +API 호출 시 오류가 발생하면 API는 해당 오류 코드와 정보를 반환합니다. 예를 들면 다음과 같습니다: -- `400 token_mismatched`: 잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다. -- `400 api_not_implemented`: 잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다. -- `401 invalid_token`: 인증되지 않음, 잘못되었거나 누락된 인증 토큰입니다. -- `429 too_many_requests`: 너무 많은 요청, 비율 제한을 초과했습니다. -- `500 api_error`: 내부 서버 오류, 서버에서 문제가 발생했습니다. +- `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. +- `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. +- `401 invalid_token`: Unauthorized, invalid or missing authorization token. +- `429 too_many_requests`: Too many requests, you have exceeded the rate limit. +- `500 api_error`: Internal server error, something went wrong on the server. ### 오류 응답 예시 @@ -138,4 +138,4 @@ API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정 ## 결론 -이 문서를 통해 OpenAI Embeddings API를 사용하여 공식 OpenAI의 단어 벡터 생성 기능을 쉽게 사용할 수 있는 방법을 이해하게 되었습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주세요. +이 문서를 통해 공식 OpenAI의 임베딩 생성 기능을 사용하기 위해 OpenAI Embeddings API를 쉽게 사용하는 방법을 이미 알아보았습니다. 이 문서가 해당 API를 더 잘 연동하고 사용하는 데 도움이 되기를 바랍니다. 궁금한 점이 있으시면 언제든지 기술 지원팀에 문의해 주세요. diff --git a/ko/guides/platform/wework_bot.mdx b/ko/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..5996dcdec --- /dev/null +++ b/ko/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "기업 위챗 봇" +description: "Platform API guide - Ace Data Cloud" +--- + +자신만의 기업 위챗 계정 인스턴스를 배포하고, 휴대폰 기업 위챗으로 QR 코드를 스캔해 로그인하며, REST API 또는 MCP를 통해 계정, 연락처, 대화 및 로컬 동기화 메시지를 읽습니다. 인스턴스는 일반 기업 위챗 계정에 대응하며, 프라이빗 서버나 기업 이메일 도메인 설정이 필요하지 않습니다. + +현재 Alpha입니다. 계정 읽기는 실제 대화 검증을 완료했으며, 본인 텍스트 전송 및 이벤트 읽기 회수는 실제 검수를 완료했습니다. 기타 연락처, 그룹 작업 및 새 인스턴스 복구는 아직 배포 환경 검수를 완료해야 합니다. 미디어 전송, 인용 답장, 실제 @, 그룹 구성원 관리 및 전달 확인은 아직 공개되지 않았습니다. 인스턴스의 `/api/capabilities` 반환값을 기준으로 하십시오. + +## 배포 및 로그인 + +Deployment 분류에서 서비스를 활성화하고 인스턴스 기간 요금제를 선택합니다. 배포 후 관리 페이지를 열고 계정 본인의 기업 위챗으로 스캔합니다. 휴대폰 확인이나 기타 로그인 단계가 필요한 경우 원격 데스크톱을 열고 해당 인스턴스의 데스크톱 비밀번호를 입력하십시오. API 자격 증명과 데스크톱 비밀번호는 독립적입니다. 로그인 정보는 인스턴스 디스크에 저장되며, 컨테이너를 재구성해도 디스크는 유지됩니다. 디스크를 삭제하면 로컬 세션이 삭제됩니다. + +각 인스턴스는 독립적으로 과금되며, 구매한 기간에 따라 실행됩니다. REST / MCP 호출은 메시지별로 별도 과금되지 않으며, 실제 가격은 요금제 페이지를 기준으로 합니다. 현재는 기본적으로 위챗 봇의 기간 요금제를 참고하며, 최종 공개 전 실행 리소스와 결합하여 가격 확인을 완료해야 합니다. + +## API 및 MCP + +관리 페이지의 인스턴스 API 주소를 사용하고, 모든 계정 인터페이스에 `Authorization: Bearer <인스턴스 API token>`을 포함합니다. 이 경로들은 전용 인스턴스에 속하며, 공유 API 게이트웨이가 아닙니다. MCP 주소는 인스턴스 주소에 `/mcp/`를 더한 것이며, 동일한 Bearer token을 사용합니다. + +| 인터페이스 | 기능 | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | 계정 준비 여부 및 기능 목록 | +| `GET /api/auth/qr` | 현재 로그인 QR 코드 PNG Base64 | +| `GET /api/account` | 현재 계정 | +| `GET /api/contacts?kind=all` | 내부 동료 및 외부 연락처, internal / external 지정 가능 | +| `GET /api/conversations` | 로컬 대화, 원본 대화 ID 유지 | +| `GET /api/messages` | 로컬 동기화 메시지; conversation_id, after_rowid, limit 매개변수 | +| `POST /api/search` | 연락처, 대화 및 로컬 텍스트 검색 | +| `POST /api/messages` | 텍스트 전송 비동기 작업, 반드시 Idempotency-Key 제공 | +| `POST /api/messages/send` | 동일한 전송 엔트리, 단일 또는 다수 대상 지원 | +| `GET /api/groups/{conversation_id}` | 로컬 동기화된 그룹 정보 및 구성원 | +| `GET /api/tasks` | 최근 작업 및 각 대상의 결과 | +| `GET /api/tasks/{id}` | 전송 결과 조회 | +| `POST /api/tasks/{id}/cancel` | 아직 시작하지 않은 작업 취소 | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | 자동화 일시 중지; 본인 검증 후 재개 | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | 인스턴스 상태 및 현재 화면, 모두 인증 필요 | +| `GET /api/events?after=0` | 복구 가능한 커서의 메시지 이벤트 | +| `WS /ws` | 메시지 이벤트 스트림, Bearer 인증 | + +전송 본문에는 `target`, `type: "text"` 및 `text`가 포함됩니다. `target`은 대화 ID, 연락처 ID, 기업 사용자 ID 또는 고유한 전체 이름을 허용합니다. ID를 우선 사용하십시오. 표시 이름으로도 고유하게 위치를 특정할 수 없는 경우, 인스턴스는 작업을 거부하며 대상을 추측하지 않습니다. 로컬 대화가 없는 연락처는 먼저 클라이언트를 통해 대화를 열고 실제 대화 ID를 확인한 후 전송합니다. 요청 헤더 `Idempotency-Key`는 8–128자의 영문자, 숫자 또는 `_.:-`입니다. 동일한 작업을 반복 요청할 때는 동일한 키와 동일한 요청 본문을 재사용해야 합니다. + +`target`을 `targets` 배열로 바꾸면 명확하게 지정된 1–50개 대상에게 순차적으로 전송할 수 있습니다. 둘은 동시에 제공할 수 없습니다. 모든 대상은 먼저 신원 확인을 완료하며, 동일한 객체를 가리키는 서로 다른 별칭은 거부됩니다. 어느 한 대상이 실패하면 이후 전송을 중지하고, 작업 결과는 항목별로 `succeeded`, `failed`, `unknown` 또는 `not_attempted`를 기록합니다. 부분 성공을 전체 성공으로 간주하지 마십시오. 이 절차 역시 배포 환경에서 지정된 연락처에 대한 실제 검수를 완료해야 합니다. + +작업은 queued, running, submitting, succeeded, failed, unknown 또는 cancelled 상태일 수 있습니다. `succeeded`는 제출 후 해당 대화 기록에서 정확한 텍스트 및 서버 메시지 ID를 찾았음을 의미하며, `delivered`가 여전히 null인 것은 상대방이 이미 받았음을 의미하지 않습니다. unknown은 결과가 불명확함을 의미하므로, 기록을 확인하고 새 키로 반복 전송하지 마십시오. 인스턴스는 중단된 작업을 자동으로 재전송하지 않습니다. + +기록에는 클라이언트가 이미 동기화한 내용만 포함되며, 전체 기록을 보장할 수 없습니다. 텍스트가 아닌 메시지는 unknown 유형으로 반환될 수 있으며, 첨부 파일 다운로드는 아직 공개되지 않았습니다. 이벤트는 최근 10,000개를 보존하며, `gap`은 커서가 보존 창을 이미 초과했음을 의미합니다. 최초 연결은 이전 기록을 새 메시지로 다시 재생하지 않습니다. + +메시지 기록의 `server_accepted` 및 `server_id`는 서버가 로컬 메시지를 이미 수락했는지 확인하는 데 사용할 수 있습니다. 로컬 기록만 있고 서버 ID가 없는 경우 전송 성공으로 판단할 수 없습니다. 이 필드들은 수신자가 이미 받았거나 읽었음을 의미하지 않습니다. 이벤트 기록은 생성 시점의 상태를 보존하며, 현재 확인 상태를 조회하려면 메시지 기록 인터페이스를 사용해야 합니다. + +## 계정 및 자격 증명 + +본인이 작업 권한을 가진 계정에만 로그인하십시오. API token을 신뢰할 수 있는 애플리케이션에 구성하십시오. 이는 해당 인스턴스의 계정 데이터에 접근할 수 있습니다. 비밀번호, QR 코드 또는 채팅 스크린샷을 공개 위치에 게시하지 마십시오. 인스턴스를 일시 중지하면 실시간 이벤트가 중단됩니다. 계정 로그아웃 또는 휴대폰 측에서 장치를 제거한 후에는 다시 로그인해야 합니다. + +현재 텍스트 입력은 한 줄만 지원하며, 줄바꿈은 전송 전에 명시적으로 거부됩니다. 클라이언트가 보안 검증 또는 재로그인을 요구할 때는 계정 본인이 원격 데스크톱에서 완료해야 합니다. 인스턴스는 검증을 우회하지 않습니다. 검증 중단 후의 작업은 unknown을 반환할 수 있으므로, 먼저 메시지 기록을 조회하고 새 멱등 키로 재전송하지 마십시오. + +보안 검증 프롬프트, 계정 로그아웃 또는 변경이 감지되면 자동화 대기열은 영구적으로 일시 중지됩니다. 휴대폰 검증을 완료한 후 인스턴스 콘솔의 “검증 후 재개”를 통해 아직 실행되지 않은 작업을 계속할 수 있습니다. 이미 제출되었으나 결과가 불확실한 작업은 재전송되지 않습니다. 일반적인 원격 업무도 기업 위챗 보안 검증을 유발할 수 있습니다. 공식 안내의 검증 후 24시간 동안 다시 잠기지 않는 창은 탐지가 이미 제거되었음을 의미하지 않으며, 인스턴스가 장기간 무인 운영을 보장할 수 있음을 의미하지도 않습니다. diff --git a/openapi/openai.json b/openapi/openai.json index 474c6f724..b991884db 100644 --- a/openapi/openai.json +++ b/openapi/openai.json @@ -2352,8 +2352,7 @@ "type": "string", "enum": [ "text-embedding-3-small", - "text-embedding-3-large", - "text-embedding-ada-002" + "text-embedding-3-large" ], "description": "Openai Embeddings Model" }, diff --git a/pl/guides/claude/claude_messages.mdx b/pl/guides/claude/claude_messages.mdx index a4bf246b6..1ce466669 100644 --- a/pl/guides/claude/claude_messages.mdx +++ b/pl/guides/claude/claude_messages.mdx @@ -1,43 +1,44 @@ --- -title: "Wniosek i korzystanie z Claude Messages API" +title: "Wnioskowanie o Claude Messages API i jego użycie" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude to bardzo potężny system konwersacyjny AI, który po prostu po wprowadzeniu promptu potrafi w ciągu kilku sekund wygenerować płynną i naturalną odpowiedź. Claude Messages API to oficjalny, natywny format API Anthropic, różniący się od formatu kompatybilnego z OpenAI (Chat Completion). Wykorzystuje własną strukturę żądań i odpowiedzi Anthropic, co pozwala lepiej wykorzystać unikalne możliwości Claude, takie jak wielomodalne wprowadzanie treści, wywoływanie narzędzi, głębokie myślenie (Extended Thinking) i inne zaawansowane funkcje. +Anthropic Claude to bardzo potężny system konwersacyjny AI, który po wprowadzeniu promptu potrafi w zaledwie kilka sekund wygenerować płynną i naturalną odpowiedź. Claude Messages API jest oficjalnym natywnym formatem API Anthropic, różniącym się od formatu kompatybilnego z OpenAI (Chat Completion), wykorzystuje własną strukturę żądań i odpowiedzi Anthropic, co pozwala lepiej wykorzystać unikalne możliwości Claude, takie jak multimodalne wprowadzanie treści, wywoływanie narzędzi, głębokie myślenie (Extended Thinking) i inne zaawansowane funkcje. -Ten dokument przedstawia przede wszystkim proces korzystania z operacji Claude Messages API. Dzięki niemu możemy używać natywnego interfejsu zgodnego z oficjalnym Anthropic do wywoływania funkcji konwersacyjnych Claude. +Ten dokument przedstawia głównie proces używania operacji Claude Messages API, dzięki któremu możemy korzystać z natywnego interfejsu zgodnego z oficjalnym Anthropic, aby wywoływać funkcję konwersacji Claude. -## Proces składania wniosku +## Proces wnioskowania -Aby korzystać z Claude Messages API, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token i zachować go na później. +Aby używać Claude Messages API, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token i zachować go do użycia później. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi Cię do rejestracji i zalogowania się, a po zakończeniu automatycznie wrócisz na bieżącą stronę. +Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi Cię do rejestracji i zalogowania się, a po zakończeniu automatycznie powrócisz na bieżącą stronę. -**Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez potrzeby osobnego składania wniosku dla każdej usługi.** Przy pierwszym wniosku otrzymasz bezpłatny limit, który pozwala na darmowe wypróbowanie; gdy limit jest niewystarczający, możesz doładować wspólne saldo w [konsoli](https://platform.acedata.cloud/console/coin). +**Jeden API Token pozwala wywoływać wszystkie usługi platformy, nie ma potrzeby składania osobnego wniosku dla każdej usługi.** Przy pierwszym wnioskowaniu otrzymasz bezpłatny limit, z którego możesz korzystać bezpłatnie; gdy limit jest niewystarczający, możesz doładować ogólne saldo w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Podstawowe użycie -Ścieżka żądania Claude Messages API to `/v1/messages`, zgodnie z oficjalnym API Anthropic. Musimy podać co najmniej trzy wymagane parametry: +Ścieżka żądania Claude Messages API to `/v1/messages`, zgodna z oficjalnym API Anthropic. Musimy podać co najmniej trzy wymagane parametry: -- `model`: wybór używanego modelu Claude. `claude-opus-5-5` jest dostępny wyłącznie przez Messages API, obsługuje kontekst 1 miliona Tokenów, maksymalnie 128K Tokenów wyjściowych i zawsze włącza adaptacyjne myślenie. Najnowszym modelem flagowym jest `claude-fable-5-1` (kontekst 1 miliona Tokenów, maksymalnie 128K Tokenów wyjściowych); wcześniejszy `claude-fable-5` pozostaje zachowany dla kompatybilności. `claude-sonnet-5-5` dołączył do serii natywnych interfejsów Messages, obsługuje wejście obrazów i adaptacyjne myślenie; jego oficjalne ceny referencyjne za wejście, wyjście i odczyt z pamięci podręcznej wynoszą odpowiednio 2, 10 i 0,20 USD za milion Tokenów. -- `messages`: tablica wiadomości wejściowych, gdzie każda wiadomość zawiera `role` (rolę) i `content` (treść), a `role` obsługuje `user` i `assistant`. +- `model`: wybierz używany model Claude. `claude-opus-5-5` jest udostępniany wyłącznie przez Messages API, obsługuje kontekst 1 miliona Tokenów, maksymalne wyjście 128K Tokenów i zawsze włącza adaptacyjne myślenie. Najnowszym flagowym modelem jest `claude-fable-5-1` (kontekst 1 miliona Tokenów, maksymalne wyjście 128K Tokenów); wcześniejszy `claude-fable-5` nadal jest zachowany dla kompatybilności. `claude-sonnet-5-5` został dodany do natywnego interfejsu serii Messages, obsługuje wejście obrazów i adaptacyjne myślenie; jego oficjalne ceny referencyjne za wejście, wyjście i odczyt z pamięci podręcznej wynoszą odpowiednio 2, 10 i 0,20 USD za milion Tokenów. +- `messages`: tablica wiadomości wejściowych, każda wiadomość zawiera `role` (rolę) i `content` (treść), gdzie `role` obsługuje `user` i `assistant`. - `max_tokens`: maksymalna liczba tokenów wyjściowych, używana do ograniczenia długości pojedynczej odpowiedzi. Często używane parametry opcjonalne: -- `system`: systemowy prompt, używany do określania zachowania i roli modelu. -- `temperature`: losowość generowania, od 0 do 1; im większa wartość, tym bardziej rozproszone odpowiedzi. -- `stream`: czy używać odpowiedzi strumieniowej; ustawienie na `true` umożliwia efekt zwracania znak po znaku. -- `stop_sequences`: niestandardowe sekwencje zatrzymania; model przestanie generować po napotkaniu tych tekstów. -- `top_p`: parametr próbkowania jądrowego, który wraz z temperature kontroluje losowość generowania. -- `top_k`: próbkuje wyłącznie spośród K opcji o najwyższym prawdopodobieństwie. -- `tools`: definicje narzędzi, używane do umożliwienia modelowi wywoływania funkcji zewnętrznych. -- `tool_choice`: kontroluje sposób używania przez model dostarczonych narzędzi. -- `cache_control`: automatycznie tworzy punkt przerwania pamięci podręcznej przy ostatnim możliwym do buforowania bloku treści żądania; można go również zapisać przy konkretnym bloku treści. +- `system`: prompt systemowy, używany do określenia zachowania i roli modelu. +- `temperature`: losowość generowania, między 0 a 1, im większa wartość, tym bardziej rozproszone odpowiedzi. +- `stream`: czy używać odpowiedzi strumieniowej, ustawienie `true` pozwala uzyskać efekt zwracania znak po znaku. +- `stop_sequences`: niestandardowe sekwencje zatrzymania, model przestanie generować po napotkaniu tych tekstów. +- `top_p`: parametr próbkowania jądrowego, współpracuje z temperature w celu kontrolowania losowości generowania. +- `top_k`: próbkowanie wyłącznie spośród K opcji o najwyższym prawdopodobieństwie. +- `tools`: definicje narzędzi, używane do umożliwienia modelowi wywoływania zewnętrznych funkcji. +- `tool_choice`: kontroluje, jak model używa dostarczonych narzędzi. +- `cache_control`: automatycznie tworzy punkt przerwania pamięci podręcznej przy ostatnim zawartościowym bloku możliwym do zapisania w pamięci podręcznej żądania; można też zapisać go w konkretnym bloku treści. +- `metadata`: opcjonalny obiekt metadanych żądania. `metadata.user_id` jest ciągiem znaków i może przekazywać niestandardowy identyfikator użytkownika wywołującego, na przykład `{"user_id":"example-user-001"}`; zaleca się używanie stabilnego identyfikatora niezawierającego danych osobowych. Nie zastępuje on uwierzytelniania `Authorization` ani nie musi być zapisywany w treści konwersacji `messages`. ### Przykład cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Po wywołaniu zwracany wynik wygląda następująco: +Po wywołaniu wynik zwracany jest następujący: ```json { @@ -107,24 +110,24 @@ Po wywołaniu zwracany wynik wygląda następująco: ``` Opis pól wyniku zwracanego: +- `id`: Unikalny identyfikator tej wiadomości. +- `type`: Zawsze `message`. +- `role`: Zawsze `assistant`. +- `content`: Tablica treści odpowiedzi, każdy element zawiera `type` (np. `text`) oraz odpowiadającą mu treść. +- `model`: Nazwa modelu przetwarzającego żądanie. +- `stop_reason`: Powód zatrzymania. Stabilne wartości obejmują `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (można zwrócić bieżącą treść assistant bez zmian, aby kontynuować), `refusal` oraz `model_context_window_exceeded`. +- `stop_sequence`: Jeśli zatrzymanie nastąpiło z powodu niestandardowej sekwencji zatrzymania, wyświetla dopasowany tekst sekwencji zatrzymania. +- `stop_details`: Gdy `stop_reason` ma wartość `refusal`, może zawierać kategorię odmowy i opis. +- `usage`: Statystyki użycia tokenów. `input_tokens` to niebuforowane dane wejściowe; `cache_creation_input_tokens` i `cache_read_input_tokens` oznaczają odpowiednio zapis do pamięci podręcznej i odczyt z niej; `output_tokens` to całkowita liczba tokenów wyjściowych. Jeśli zwracane jest `output_tokens_details.thinking_tokens`, ta wartość jest podzbiorem `output_tokens`, więc nie należy jej ponownie dodawać podczas obliczania sumy lub kosztu. Ten szczegół może mieć wartość `null` lub być pominięty, gdy nie ma autorytatywnego licznika. +- `usage.cache_creation`: Opcjonalne szczegóły TTL zapisu do pamięci podręcznej, zawierające `ephemeral_5m_input_tokens` i `ephemeral_1h_input_tokens`. Gdy obiekt istnieje, suma tych dwóch wartości jest równa `cache_creation_input_tokens`; wartość `null` lub pominięcie pola oznacza, że bieżąca odpowiedź nie ma dostępnego podziału TTL i nie należy interpretować tego jako `0`. +- `usage.cost`: Odpowiedzi niestreamowane mogą zawierać obiekt zużycia limitu zarejestrowany przez Ace Data Cloud, gdzie `amount` to faktyczne zużycie w tym żądaniu, `currency` to jednostka rozliczeniowa, a `list_amount` to kwota przed rabatem (jeśli występuje). Oficjalna cena bazowa odczytu z pamięci podręcznej dla Fable 5.1 wynosi $0.25/milion tokenów, a ceny bazowe zapisu do pamięci podręcznej na 5 minut i 1 godzinę wynoszą odpowiednio $12.50 i $20/milion tokenów; rzeczywiste ceny platformy są przeliczane zgodnie ze zniżkami planu. -- `id`: unikalny identyfikator tej wiadomości. -- `type`: zawsze `message`. -- `role`: zawsze `assistant`. -- `content`: tablica treści odpowiedzi, gdzie każdy element zawiera `type` (np. `text`) oraz odpowiadającą mu treść. -- `model`: nazwa modelu przetwarzającego żądanie. -- `stop_reason`: powód zatrzymania. Stabilne wartości obejmują `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (można zwrócić bieżącą treść assistant w niezmienionej formie, aby kontynuować), `refusal` oraz `model_context_window_exceeded`. -- `stop_sequence`: jeśli zatrzymanie nastąpiło z powodu niestandardowej sekwencji zatrzymania, wyświetla dopasowany tekst sekwencji zatrzymania. -- `stop_details`: gdy `stop_reason` ma wartość `refusal`, może zawierać kategorię odmowy i wyjaśnienie. -- `usage`: statystyki użycia tokenów. `input_tokens` oznacza niebuforowane wejście; `cache_creation_input_tokens` i `cache_read_input_tokens` oznaczają odpowiednio zapis i odczyt pamięci podręcznej; `output_tokens` to całkowita liczba tokenów wyjściowych. Jeśli zwracane jest `output_tokens_details.thinking_tokens`, wartość ta jest podzbiorem `output_tokens` i nie należy jej ponownie dodawać podczas obliczania całości lub kosztów. Ten szczegół może mieć wartość `null` lub zostać pominięty, gdy nie ma autorytatywnego licznika. -- `usage.cache_creation`: opcjonalne szczegóły TTL zapisu pamięci podręcznej, zawierające `ephemeral_5m_input_tokens` i `ephemeral_1h_input_tokens`. Gdy obiekt istnieje, suma obu pozycji jest równa `cache_creation_input_tokens`; wartość pola `null` lub pominięcie oznacza, że bieżąca odpowiedź nie ma dostępnego podziału TTL i nie można interpretować tego jako `0`. -- `usage.cost`: odpowiedzi niestrumieniowe mogą zawierać obiekt zużycia limitu zarejestrowany przez Ace Data Cloud, gdzie `amount` to faktyczne zużycie w tym wywołaniu, `currency` to jednostka rozliczeniowa, a `list_amount` to kwota przed rabatem (jeśli występuje). Oficjalna bazowa cena odczytu pamięci podręcznej dla Fable 5.1 wynosi 0,25 USD/milion Tokenów, a bazowe ceny zapisu pamięci podręcznej na 5 minut i 1 godzinę wynoszą odpowiednio 12,50 i 20 USD/milion Tokenów; rzeczywista cena platformy jest przeliczana zgodnie z rabatem pakietu. +## Komunikat systemowy -## Systemowy prompt +Claude Messages API obsługuje ustawianie komunikatu systemowego za pomocą pola `system`, używanego do definiowania zachowania, roli i kontekstu modelu. -Claude Messages API obsługuje ustawianie systemowego promptu za pomocą pola `system`, używanego do definiowania zachowania, roli i kontekstu modelu. +### Przykład w Pythonie -### Przykład Python ```python import requests @@ -149,13 +152,13 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Ustawiając prompt `system`, można precyzyjnie kontrolować rolę i sposób zachowania Claude'a. +Poprzez ustawienie komunikatu `system` można precyzyjnie kontrolować rolę i sposób zachowania Claude'a. ## Odpowiedzi strumieniowe -Ten interfejs obsługuje również odpowiedzi strumieniowe. Ustawienie parametru `stream` na `true` umożliwia uzyskanie efektu stopniowego zwracania, co jest bardzo przydatne do implementacji wyświetlania znak po znaku na stronach internetowych. +Ten interfejs obsługuje również odpowiedzi strumieniowe; ustawienie parametru `stream` na `true` pozwala uzyskać efekt stopniowego zwracania, co doskonale nadaje się do implementacji wyświetlania znak po znaku na stronie internetowej. -### Przykład Python +### Przykład w Pythonie ```python import requests @@ -183,14 +186,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Odpowiedzi strumieniowe są zwracane w formacie Server-Sent Events (SSE), przy czym każda linia jest poprzedzona prefiksem `event:` i `data:`. Typy zdarzeń strumieniowych obejmują: +Odpowiedzi strumieniowe są zwracane w formacie Server-Sent Events (SSE), przy czym każda linia ma prefiks `event:` i `data:`. Typy zdarzeń strumieniowych obejmują: -- `message_start`: rozpoczęcie wiadomości, zawiera podstawowe informacje o wiadomości i nazwę modelu. -- `content_block_start`: rozpoczęcie bloku treści. -- `content_block_delta`: przyrostowa aktualizacja bloku treści, zawiera nowo wygenerowane fragmenty tekstu. -- `content_block_stop`: zakończenie bloku treści. -- `message_delta`: przyrostowa aktualizacja na poziomie wiadomości, zawiera `stop_reason` i końcowe informacje `usage`. Wiążącą wartość `output_tokens_details.thinking_tokens` należy odczytywać wyłącznie z ostatniego `message_delta.usage`; nie należy sumować jej między zdarzeniami. -- `message_stop`: zakończenie wiadomości. +- `message_start`: Rozpoczęcie wiadomości, zawiera podstawowe informacje o wiadomości i nazwę modelu. +- `content_block_start`: Rozpoczęcie bloku treści. +- `content_block_delta`: Przyrostowa aktualizacja bloku treści, zawiera nowo wygenerowany fragment tekstu. +- `content_block_stop`: Zakończenie bloku treści. +- `message_delta`: Przyrostowa aktualizacja na poziomie wiadomości, zawiera informacje `stop_reason` i końcowe `usage`. Autorytatywną wartość `output_tokens_details.thinking_tokens` należy odczytywać wyłącznie z ostatniego `message_delta.usage`, nie należy sumować jej między zdarzeniami. +- `message_stop`: Zakończenie wiadomości. Efekt wyjściowy jest następujący: @@ -220,9 +223,9 @@ event: message_stop data: {"type":"message_stop"} ``` -Można zauważyć, że w odpowiedzi strumieniowej zdarzenie `content_block_delta` zawiera stopniowo generowaną treść tekstową; połączenie wszystkich `text_delta` pozwala uzyskać pełną odpowiedź. +Jak można zauważyć, zdarzenia `content_block_delta` w odpowiedzi strumieniowej zawierają stopniowo generowaną treść tekstową, a połączenie wszystkich `text_delta` pozwala uzyskać pełną odpowiedź. -### Przykład JavaScript +### Przykład w JavaScript ```javascript const options = { @@ -253,9 +256,9 @@ while (true) { ## Rozmowy wieloturowe -Jeśli chcesz korzystać z funkcji rozmów wieloturowych, musisz naprzemiennie umieścić w tablicy `messages` wiadomości z rolami `user` i `assistant`, przekazując jednocześnie całą wcześniejszą historię rozmowy. +Jeśli chcesz korzystać z funkcji rozmów wieloturowych, musisz naprzemiennie umieszczać wiadomości ról `user` i `assistant` w tablicy `messages`, przekazując razem całą wcześniejszą historię rozmowy. -### Przykład Python +### Przykład w Pythonie ```python import requests @@ -282,8 +285,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Wynik zwracany jest następujący: - +Wynik zwracany jest następująco: ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,11 +309,11 @@ Wynik zwracany jest następujący: Przekazując pełną historię rozmowy w `messages`, Claude może udzielać dokładnych odpowiedzi z uwzględnieniem kontekstu. -## Model głębokiego rozumowania +## Modele głębokiego rozumowania -Thinking Claude'a i thinking summary to dwa różne pojęcia: model może przeprowadzać wewnętrzne rozumowanie, ale API nie zwraca oryginalnego łańcucha myślenia. Gdy konieczne jest wyświetlenie procesu rozumowania, API zwraca przetworzone podsumowanie. +Thinking Claude'a i thinking summary to dwa różne pojęcia: model może prowadzić wewnętrzne rozumowanie, ale API nie zwraca oryginalnego łańcucha myśli. Gdy konieczne jest pokazanie procesu rozumowania, API zwraca przetworzone podsumowanie. -Obecnie zaleca się dla modelu używanie adaptive thinking oraz kontrolowanie ogólnego nakładu rozumowania za pomocą `output_config.effort`: +W przypadku obecnych modeli zalecane jest używanie adaptive thinking oraz kontrolowanie ogólnego nakładu rozumowania za pomocą `output_config.effort`: ```python import requests @@ -341,7 +343,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Blok thinking w odpowiedzi ma postać: +Blok thinking w odpowiedzi wygląda następująco: ```json { @@ -350,26 +352,27 @@ Blok thinking w odpowiedzi ma postać: "signature": "opaque-signature" } ``` -- `display: "summarized"` zwraca czytelne podsumowanie rozumowania; nie jest to surowy łańcuch myślowy. + +- `display: "summarized"` zwraca czytelne podsumowanie rozumowania; nie jest to oryginalny łańcuch myśli. - `display: "omitted"` zwraca `thinking: ""`, ale nadal zachowuje opaque `signature`, aby wspierać kolejne rozmowy. -- `display: "updates"` to tryb beta Anthropic, który wymaga przekazania `anthropic-beta: thinking-display-updates-2026-08-18`. Oficjalna definicja mówi, że ukrywa treść rozumowania i wyświetla krótkie aktualizacje postępu między wywołaniami narzędzi. Platforma przekazuje ten parametr i nagłówek żądania beta w oryginalnej wartości, nie wymusza przepisania na `summarized`; rzeczywista zawartość wyjścia zależy od obsługi wybranego modelu. -- `thinking`, `output_config`, effort, parametry próbkowania oraz nowe pola rozszerzeń są przekazywane w oryginalnych wartościach. Platforma nie utrzymuje zakodowanych na stałe dla poszczególnych modeli enumeracji wartości ani ograniczeń kombinacji, ani nie przepisuje automatycznie trybu thinking; o tym, czy te parametry są akceptowane, decyduje wybrany model, a błędy parametrów zwrócone przez model są przekazywane klientowi. -- Domyślna wartość display dla Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 i Opus 4.7 to `omitted`; Opus 4.6, Sonnet 4.6 oraz wcześniejsze modele obsługujące thinking domyślnie używają `summarized`. +- `display: "updates"` to beta tryb Anthropic, który wymaga przekazania `anthropic-beta: thinking-display-updates-2026-08-18`. Oficjalna definicja mówi o ukrywaniu treści rozumowania i wyświetlaniu krótkich aktualizacji postępu między wywołaniami narzędzi. Platforma przekazuje ten parametr i nagłówek beta w oryginalnej postaci, nie wymuszając zmiany na `summarized`; rzeczywista zawartość wyjścia zależy od obsługi wybranego modelu. +- `thinking`, `output_config`, effort, parametry próbkowania oraz nowe rozszerzone pola są przekazywane w oryginalnej postaci. Platforma nie utrzymuje zakodowanych na stałe dla poszczególnych modeli wyliczeń wartości ani ograniczeń kombinacji, a także nie zmienia automatycznie trybu thinking; o przyjęciu tych parametrów decyduje wybrany model, a błędy parametrów zwrócone przez model są przekazywane klientowi. +- Domyślną wartością display dla Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 i Opus 4.7 jest `omitted`; Opus 4.6, Sonnet 4.6 oraz wcześniejsze modele obsługujące thinking domyślnie używają `summarized`. - Display wpływa tylko na zwracaną zawartość i opóźnienie strumieniowania, nie wyłącza rozumowania ani nie zmniejsza rozliczania tokenów thinking. -- To, czy thinking jest domyślnie włączone, i domyślna wartość display to dwa niezależne zagadnienia. Opus 5 i Sonnet 5 domyślnie włączają adaptive thinking; dla Opus 5 pominięcie `thinking` jest równoważne adaptive, a pominięcie `output_config.effort` jest równoważne `high`. Opus 4.8, 4.7 i 4.6 wymagają jawnego włączenia. -- Thinking i końcowa treść wspólnie wykorzystują budżet wyjściowy `max_tokens`. Gdy budżet jest zbyt mały, thinking może wykorzystać większość limitu, przez co treść może być pusta lub obcięta; zwiększ `max_tokens` albo użyj effort `low` / `medium`, aby kontrolować nakład na rozumowanie. -- Dla modeli, które pozwalają wyłączyć thinking, można przekazać `thinking: {"type":"disabled"}`. Nowe tryby, takie jak `between_tools`, oraz kombinacje effort zależą od wybranego modelu; platforma nie odrzuca ich z wyprzedzeniem na podstawie starych reguł modeli. -- Stały budżet rozumowania można przekazać przez `budget_tokens`; nowe modele zazwyczaj używają `thinking.type=adaptive` oraz `output_config.effort`. To, czy stały budżet lub wyłączenie rozumowania są obsługiwane, zależy od aktualnych możliwości wybranego modelu. -- W rozmowach wieloturowych i przy wywołaniach narzędzi należy przekazywać z powrotem pełny blok thinking oraz signature zwrócone przez assistant bez zmian; nie modyfikuj ani nie generuj samodzielnie signature. -- Przekazywanie parametrów nie oznacza, że każdy model obsługuje wszystkie funkcje. Wywołania między protokołami nadal wymagają konwersji, a zakres obsługi i błędy dotyczące treści takich jak `redacted_thinking` są określane przez usługę modelu faktycznie przetwarzającą żądanie. +- Domyślne włączenie thinking i domyślna wartość display to dwa niezależne zagadnienia. Opus 5 i Sonnet 5 domyślnie włączają adaptive thinking; dla Opus 5 pominięcie `thinking` jest równoważne adaptive, a pominięcie `output_config.effort` jest równoważne `high`. Opus 4.8, 4.7 i 4.6 wymagają jawnego włączenia. +- Thinking i końcowa treść wspólnie wykorzystują budżet wyjściowy `max_tokens`. Gdy budżet jest zbyt mały, thinking może wykorzystać większość limitu, przez co treść będzie pusta lub obcięta; zwiększ `max_tokens` albo użyj effort `low` / `medium`, aby kontrolować nakład rozumowania. +- W przypadku modeli, które pozwalają wyłączyć thinking, można przekazać `thinking: {"type":"disabled"}`. Nowe tryby, takie jak `between_tools`, oraz kombinacje effort zależą od wybranego modelu; platforma nie odrzuca ich z wyprzedzeniem na podstawie starych reguł modeli. +- Stały budżet rozumowania można przekazać za pomocą `budget_tokens`; nowe modele zazwyczaj używają `thinking.type=adaptive` i `output_config.effort`. To, czy stały budżet lub wyłączenie rozumowania są obsługiwane, zależy od bieżących możliwości wybranego modelu. +- W przypadku rozmów wieloturowych i wywołań narzędzi należy przekazać z powrotem w niezmienionej postaci pełny blok thinking oraz signature zwrócone przez assistant; nie modyfikuj ani nie generuj samodzielnie signature. +- Przekazywanie parametrów nie oznacza, że każdy model obsługuje wszystkie funkcje. Wywołania między protokołami nadal wymagają konwersji, a zakres obsługi i błędy dotyczące treści takich jak `redacted_thinking` zależą od usługi modelu, która faktycznie przetwarza żądanie. -W żądaniach strumieniowych `summarized` generuje `thinking_delta`; `omitted` nie generuje `thinking_delta`, zachowuje jedynie cykl życia bloku thinking i `signature_delta`. +W żądaniach strumieniowych `summarized` generuje `thinking_delta`; `omitted` nie generuje `thinking_delta`, zachowując jedynie cykl życia bloku thinking oraz `signature_delta`. ## Modele wizualne -Claude obsługuje dane wejściowe multimodalne i może jednocześnie przetwarzać tekst oraz obrazy. W Messages API możliwości wizualne można wykorzystać, ustawiając `content` w formacie tablicy i przekazując blok zawartości obrazu. +Claude obsługuje wejścia multimodalne i może jednocześnie przetwarzać tekst oraz obrazy. W Messages API możliwości wizualne można wykorzystać, ustawiając `content` jako tablicę i przekazując blok zawartości obrazu. -### Używanie obrazów zakodowanych Base64 +### Używanie obrazów zakodowanych w Base64 ```python import base64 @@ -456,7 +459,6 @@ print(response.json()) ``` ### Przykład cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -490,7 +492,7 @@ Obsługiwane formaty obrazów obejmują: `image/jpeg`, `image/png`, `image/gif`, ## Dokumenty i PDF -PDF używa bloku zawartości `document`, obsługując dwa stabilne źródła: Base64 i URL. Źródło Base64 musi używać `application/pdf`: +PDF używa bloku treści `document`, obsługując dwa stabilne źródła: Base64 i URL. Źródło Base64 musi używać `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -Źródło URL zapisuje się jako `{"type":"url","url":"https://example.com/report.pdf"}`. `document` obsługuje również `text/plain` oraz źródło `content` złożone z bloków text/image; pola opcjonalne obejmują `title`, `context` i `citations`. Źródło `file_id` z Files API należy do niezależnej funkcji beta i nie wchodzi w skład stabilnego kontraktu tego interfejsu. +Źródło URL zapisuje się jako `{"type":"url","url":"https://example.com/report.pdf"}`. `document` obsługuje również `text/plain` oraz źródło `content` składające się z bloków text/image; pola opcjonalne obejmują `title`, `context` i `citations`. Źródło `file_id` z Files API należy do niezależnej funkcji beta i nie jest objęte stabilnym kontraktem tego interfejsu. ## Buforowanie promptów -Najwyższego poziomu `cache_control` automatycznie umieszcza punkt przerwania pamięci podręcznej na ostatnim bloku, który można buforować: +Najwyższy poziom `cache_control` automatycznie umieszcza punkt przerwania pamięci podręcznej na ostatnim bloku możliwym do buforowania: ```python payload = { @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Gdy konieczna jest precyzyjna kontrola pozycji, można również zapisać ten sam `cache_control` w blokach zawartości text, image, document, tool_use, tool_result lub w definicji narzędzia. `ttl` obsługuje `5m` (domyślnie) oraz `1h`; proszę określać zapis do pamięci podręcznej i trafienia na podstawie `usage.cache_creation_input_tokens` oraz `usage.cache_read_input_tokens`. -Gdy odpowiedź zawiera `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Jeśli `cache_creation` ma wartość `null` lub jest pominięte, oznacza to, że dostępna jest tylko łączna liczba zapisów do pamięci podręcznej, bez wiarygodnego podziału TTL; w takim przypadku nie należy traktować żadnego bucketu jako znanego 0, a rozliczenia i sumy nadal opierają się na polu zbiorczym. +Gdy wymagana jest precyzyjna kontrola pozycji, ten sam `cache_control` można również zapisać w blokach treści text, image, document, tool_use, tool_result lub w definicjach narzędzi. `ttl` obsługuje `5m` (domyślnie) i `1h`; należy użyć `usage.cache_creation_input_tokens` oraz `usage.cache_read_input_tokens`, aby określić zapis do pamięci podręcznej i trafienia. + +Gdy odpowiedź udostępnia `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Jeśli `cache_creation` ma wartość `null` lub zostało pominięte, oznacza to, że istnieje tylko łączna wartość zapisu do pamięci podręcznej, bez wiarygodnego podziału TTL; w takim przypadku nie należy traktować żadnego bucketu jako znanego 0, a rozliczenia i sumy nadal opierają się na polu agregującym. -Przykład wyniku zwracanego: +Przykład zwracanego wyniku: ```json { @@ -563,9 +566,9 @@ Przykład wyniku zwracanego: ## Wywoływanie narzędzi (Tool Use) -Claude Messages API natywnie obsługuje funkcję wywoływania narzędzi, umożliwiając modelowi wywoływanie w razie potrzeby zdefiniowanych przez Państwa narzędzi/funkcji. +Claude Messages API natywnie obsługuje funkcję wywoływania narzędzi, umożliwiając modelowi wywoływanie w razie potrzeby zdefiniowanych przez Ciebie narzędzi/funkcji. -### Przykład Python +### Przykład w Pythonie ```python import requests @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Gdy model zdecyduje się wywołać narzędzie, `content` w wyniku zwracanym będzie zawierać blok zawartości typu `tool_use`: +Gdy model zdecyduje się wywołać narzędzie, `content` w zwracanym wyniku będzie zawierać blok treści typu `tool_use`: ```json { @@ -637,7 +640,7 @@ Gdy model zdecyduje się wywołać narzędzie, `content` w wyniku zwracanym będ } ``` -Należy zauważyć, że `stop_reason` ma wartość `tool_use`, co oznacza, że model musi wywołać narzędzie. Po otrzymaniu tego wyniku należy wykonać funkcję narzędzia i przekazać wynik z powrotem do modelu w formie `tool_result`: +Zauważ, że `stop_reason` ma wartość `tool_use`, co oznacza, że model musi wywołać narzędzie. Po otrzymaniu tego wyniku należy wykonać funkcję narzędzia i przekazać wynik z powrotem do modelu w formie `tool_result`: ```python payload = { @@ -689,33 +692,32 @@ Model wygeneruje końcową odpowiedź w języku naturalnym na podstawie wyniku z ## Różnice względem Chat Completion API -Ace Data Cloud udostępnia jednocześnie dwa formaty Claude API, a główne różnice między nimi są następujące: +Ace Data Cloud oferuje jednocześnie dwa formaty Claude API, a ich główne różnice są następujące: -`usage.input_tokens` w Messages API oznacza wyłącznie dane wejściowe niepochodzące z pamięci podręcznej, natomiast `cache_read_input_tokens` i `cache_creation_input_tokens` są niezależnymi bucketami rozliczeniowymi; wszystkie trzy są obliczane osobno według odpowiednich cen. - -| Cecha | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | +`usage.input_tokens` w Messages API oznacza wyłącznie niebuforowane dane wejściowe, a `cache_read_input_tokens` i `cache_creation_input_tokens` są niezależnymi bucketami rozliczeniowymi; wszystkie trzy są obliczane oddzielnie według odpowiednich cen. +| Cecha | API Messages (`/v1/messages`) | API Chat Completion (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Format | Natywny format Anthropic | Format kompatybilny z OpenAI | -| Komunikat systemowy | Niezależne pole `system` | Przekazywany przez `role: "system"` w `messages` | -| Struktura odpowiedzi | Tablica `content` (obsługuje wiele typów) | Tablica `choices` (zawiera `message`) | +| Prompt systemowy | Niezależne pole `system` | Przekazywany przez `role: "system"` w `messages` | +| Struktura odpowiedzi | Tablica `content` (obsługuje wiele typów) | Tablica `choices` (zawierająca `message`) | | Format strumieniowy | Zdarzenia SSE (wiele typów zdarzeń) | Linie SSE `data` | -| Głębokie rozumowanie | Natywne `thinking` oraz `output_config.effort` | Domyślna strategia modelu i kompatybilne parametry | -| Wywoływanie narzędzi | Natywne `tools` + `input_schema` | Format `tools` kompatybilny z OpenAI | +| Głębokie myślenie | Natywne `thinking` oraz `output_config.effort` | Domyślna strategia modelu i parametry kompatybilności | +| Wywołania narzędzi | Natywny format `tools` + `input_schema` | Format `tools` kompatybilny z OpenAI | | Statystyki tokenów | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Jeśli Państwa system jest już zintegrowany z API w formacie OpenAI, można użyć Chat Completion API do płynnego przejścia. Jeśli potrzebują Państwo wszystkich natywnych możliwości Claude, zaleca się użycie Messages API. +Jeśli Państwa system jest już zintegrowany z API w formacie OpenAI, można użyć Chat Completion API w celu płynnego przełączenia. Jeśli potrzebują Państwo korzystać ze wszystkich natywnych możliwości Claude, zalecane jest użycie Messages API. ## Obsługa błędów -Odpowiedzi błędów publicznego interfejsu używają envelope platformy Ace Data Cloud: `error.code` jest stabilnym kodem błędu, `error.message` jest opisem, a `trace_id` służy do diagnozowania żądania. Typowe statusy HTTP obejmują: +Odpowiedzi błędów publicznego interfejsu używają envelope platformy Ace Data Cloud: `error.code` jest stabilnym kodem błędu, `error.message` zawiera opis, a `trace_id` służy do analizy żądań. Typowe statusy HTTP obejmują: -- `400`: Parametry żądania lub zawartość protokołu są nieprawidłowe. -- `401`: Token autoryzacyjny jest nieprawidłowy, brakujący lub wygasł. -- `403`: Dostęp zabroniony, niewystarczające saldo lub ograniczony limit. -- `404`: API lub model nie istnieje. -- `413`: Treść żądania jest zbyt duża. -- `429`: Zbyt wiele żądań. -- `500` / `503` / `504`: Błąd usługi, tymczasowa niedostępność lub przekroczony limit czasu przetwarzania. +- `400`：Nieprawidłowe parametry żądania lub nieprawidłowa zawartość protokołu. +- `401`：Nieprawidłowy, brakujący lub wygasły token autoryzacji. +- `403`：Dostęp zabroniony, niewystarczające saldo lub ograniczony limit. +- `404`：API lub model nie istnieje. +- `413`：Treść żądania jest zbyt duża. +- `429`：Zbyt wiele żądań. +- `500` / `503` / `504`：Błąd usługi, tymczasowa niedostępność lub przekroczenie czasu przetwarzania. ### Przykład odpowiedzi błędu @@ -729,7 +731,8 @@ Odpowiedzi błędów publicznego interfejsu używają envelope platformy Ace Dat } ``` -Ta struktura błędu jest kontraktem wykonawczym Ace Data Cloud i nie jest równoznaczna z oficjalnym envelope błędów Anthropic; należy obsługiwać ją zgodnie ze statusem HTTP oraz `error.code`. +Ta struktura błędu jest kontraktem środowiska uruchomieniowego Ace Data Cloud i nie jest równoważna z oficjalnym envelope błędów Anthropic; należy obsługiwać ją zgodnie ze statusem HTTP oraz `error.code`. + +## Podsumowanie -## Wniosek -Dzięki temu dokumentowi wiesz już, jak używać Claude Messages API do wywoływania funkcji konwersacyjnych Claude w natywnym formacie Anthropic. Messages API obsługuje bogate funkcje, takie jak podstawowe rozmowy, systemowe podpowiedzi, odpowiedzi strumieniowe, rozmowy wieloturowe, pogłębione myślenie, rozumienie obrazu, pliki PDF, buforowanie podpowiedzi i wywoływanie narzędzi. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego. +Dzięki temu dokumentowi poznali Państwo sposób korzystania z Claude Messages API w celu wywoływania funkcji konwersacyjnych Claude w natywnym formacie Anthropic. Messages API obsługuje podstawowe rozmowy, prompty systemowe, odpowiedzi strumieniowe, rozmowy wieloetapowe, głębokie myślenie, rozumienie wizualne, pliki PDF, buforowanie promptów oraz wywołania narzędzi i inne bogate funkcje. W przypadku jakichkolwiek pytań prosimy o kontakt z zespołem wsparcia technicznego. diff --git a/pl/guides/openai/openai_embeddings.mdx b/pl/guides/openai/openai_embeddings.mdx index ade759357..0ce505a54 100644 --- a/pl/guides/openai/openai_embeddings.mdx +++ b/pl/guides/openai/openai_embeddings.mdx @@ -1,38 +1,38 @@ --- -title: "OpenAI Embeddings API 申请及使用" +title: "Wnioskowanie i korzystanie z OpenAI Embeddings API" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI usługa wektorów słów, służąca do generowania wektorów słów reprezentujących wprowadzone teksty. +Usługa wektorów słów OpenAI, używana do generowania wyników wektorów słów reprezentujących tekst wejściowy. -Dokument ten głównie opisuje proces korzystania z OpenAI Embeddings API, dzięki któremu możemy tworzyć wektory osadzenia reprezentujące wprowadzone teksty. +Ten dokument przedstawia głównie proces korzystania z OpenAI Embeddings API, dzięki któremu możemy tworzyć wektory osadzeń reprezentujące tekst wejściowy。。 -## 申请流程 +## Proces wnioskowania -Aby korzystać z OpenAI Embeddings API, najpierw przejdź do [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość. +Aby korzystać z OpenAI Embeddings API, najpierw przejdź do [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój API Token i zachować go na później. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. +Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zachęci Cię do rejestracji i zalogowania się, a po zakończeniu automatycznie powrócisz na bieżącą stronę. -**Jeden token API wystarczy do korzystania ze wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Przy pierwszym wniosku otrzymasz darmowy limit, aby móc go przetestować; gdy limit się wyczerpie, możesz doładować saldo ogólne w [kontrolerze](https://platform.acedata.cloud/console/coin). +**Jeden API Token umożliwia wywoływanie wszystkich usług platformy, nie ma potrzeby składania osobnego wniosku dla każdej usługi.** Przy pierwszym wniosku otrzymasz bezpłatny limit, który pozwala na darmowe wypróbowanie; gdy limit będzie niewystarczający, możesz doładować uniwersalne saldo w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## 基本使用 +## Podstawowe użycie -Następnie możesz wypełnić odpowiednie pola na interfejsie, jak pokazano na obrazku: +Następnie możesz wypełnić odpowiednią zawartość w interfejsie, jak pokazano na ilustracji:

-Podczas pierwszego korzystania z tego interfejsu musimy wypełnić co najmniej trzy pola: jedno to `authorization`, które można wybrać bezpośrednio z rozwijanej listy. Drugim parametrem jest `model`, `model` to kategoria modelu, którą wybieramy do użycia z oficjalnej strony OpenAI, mamy tutaj głównie 3 modele, szczegóły można znaleźć w dostarczonych modelach. Ostatnim parametrem jest `input`, `input` to tekst, który chcemy przekształcić w wektor słów. +Przy pierwszym użyciu tego interfejsu musimy wypełnić co najmniej trzy elementy, jednym z nich jest `authorization`, który można bezpośrednio wybrać z listy rozwijanej. Kolejnym parametrem jest `model`, `model` oznacza kategorię modelu z oficjalnej strony OpenAI, której używamy; obecnie dostępne modele to `text-embedding-3-small` i `text-embedding-3-large`. `text-embedding-ada-002` nie jest już oferowany; jeśli istniejący indeks wektorowy korzysta z tego starego modelu, nie można bezpośrednio mieszać wektorów nowego modelu i należy ponownie utworzyć indeks. Ostatnim parametrem jest `input`, `input` to tekst wektora słów, który musimy przekonwertować. -Możesz również zauważyć, że po prawej stronie znajduje się odpowiedni kod do wywołania, który możesz skopiować i uruchomić, lub po prostu kliknąć przycisk „Try”, aby przetestować. +Jednocześnie możesz zauważyć, że po prawej stronie generowany jest odpowiedni kod wywołania, możesz skopiować kod i uruchomić go bezpośrednio, możesz też bezpośrednio kliknąć przycisk „Try”, aby przeprowadzić test. -Opcjonalne parametry: +Parametry opcjonalne: -- `dimensions`: przycinanie wymiarów wektora, domyślnie zwraca pełne wymiary. -- `encoding_format`: format zwrotu, opcjonalnie `float` lub `base64`. +- `dimensions`: przycinanie wymiarów wektora, domyślnie zwracany jest pełny wymiar. +- `encoding_format`: format zwracany, do wyboru `float` lub `base64`.

@@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Po wywołaniu zauważamy, że zwrócony wynik wygląda następująco: +Po wywołaniu zauważamy, że zwracany wynik jest następujący: ```json { @@ -97,7 +97,7 @@ Po wywołaniu zauważamy, że zwrócony wynik wygląda następująco: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,25 +105,25 @@ Po wywołaniu zauważamy, że zwrócony wynik wygląda następująco: } ``` -Zwrócony wynik zawiera wiele pól, które są opisane poniżej: +Zwracany wynik zawiera wiele pól, które przedstawiono poniżej: -- `model`, model użyty do przekształcenia tekstu w wektor słów. -- `usage`, informacje o tokenach użytych do przekształcenia tekstu w wektor słów. -- `data`, wyniki wektora słów po przekształceniu tekstu. +- `model`, model użyty tym razem do konwersji tekstu na wektory słów. +- `usage`, informacje o tokenach użytych tym razem do konwersji tekstu na wektory słów. +- `data`, wynik wektorów słów po konwersji tekstu. -W tym przypadku `data` zawiera szczegółowe informacje o wektorze słów odpowiadającym tekstowi, a `embedding` to konkretne wyniki wygenerowanego wektora słów. +Wśród nich `data` zawiera szczegółowe informacje o wektorach słów odpowiadających tekstowi, a znajdujące się w nim `embedding` to konkretny wygenerowany wynik wektorów słów. -## 错误处理 +## Obsługa błędów -Podczas wywoływania API, jeśli napotkasz błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład: +Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład: -- `400 token_mismatched`: Zły wniosek, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. -- `400 api_not_implemented`: Zły wniosek, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. -- `401 invalid_token`: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacji. -- `429 too_many_requests`: Zbyt wiele żądań, przekroczono limit. -- `500 api_error`: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze. +- `400 token_mismatched`: Nieprawidłowe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. +- `400 api_not_implemented`: Nieprawidłowe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów. +- `401 invalid_token`: Brak autoryzacji, nieprawidłowy lub brakujący token autoryzacyjny. +- `429 too_many_requests`: Zbyt wiele żądań, przekroczono limit szybkości. +- `500 api_error`: Wewnętrzny błąd serwera, coś poszło nie tak na serwerze. -### 错误响应示例 +### Przykład odpowiedzi błędu ```json { @@ -136,6 +136,6 @@ Podczas wywoływania API, jeśli napotkasz błąd, API zwróci odpowiedni kod b } ``` -## 结论 +## Wnioski -Dzięki temu dokumentowi zrozumiałeś, jak łatwo korzystać z OpenAI Embeddings API, aby wykorzystać funkcję generowania wektorów słów od oficjalnego OpenAI. Mamy nadzieję, że ten dokument pomoże Ci lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, skontaktuj się z naszym zespołem wsparcia technicznego. +Dzięki temu dokumentowi dowiedziałeś się już, jak korzystać z OpenAI Embeddings API, aby łatwo używać oficjalnej funkcji OpenAI do generowania wektorów słów. Mamy nadzieję, że ten dokument pomoże Ci lepiej integrować i używać tego API. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego. diff --git a/pl/guides/platform/wework_bot.mdx b/pl/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..98cc5dcb8 --- /dev/null +++ b/pl/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "Robot WeCom" +description: "Platform API guide - Ace Data Cloud" +--- + +Wdróż własną instancję konta WeCom, użyj mobilnego WeCom do logowania przez zeskanowanie kodu i odczytuj konto, kontakty, konwersacje oraz lokalnie zsynchronizowane wiadomości przez REST API lub MCP. Instancja odpowiada zwykłemu kontu WeCom i nie wymaga prywatnego serwera ani konfiguracji domeny firmowej poczty e-mail. + +Obecnie jest to Alpha. Odczyt konta zakończył prawdziwą weryfikację konwersacji; wysyłanie własnych tekstów oraz odczyt zwrotny zdarzeń zakończyły prawdziwy odbiór; inne kontakty, operacje grupowe i odzyskiwanie nowych instancji nadal wymagają odbioru środowiska wdrożeniowego. Wysyłanie mediów, odpowiedzi z cytatem, prawdziwe @, zarządzanie członkami grupy i potwierdzenia doręczenia nie są jeszcze dostępne. Za wiążącą uznaje się wartość zwracaną przez `/api/capabilities` instancji. + +## Wdrożenie i logowanie + +Aktywuj usługę w kategorii Deployment i wybierz pakiet czasu trwania instancji. Po wdrożeniu otwórz stronę zarządzania i użyj WeCom właściciela konta do zeskanowania kodu; jeśli wymagane jest potwierdzenie na telefonie lub inne kroki logowania, otwórz pulpit zdalny i wprowadź hasło pulpitu tej instancji. Dane uwierzytelniające API i hasło pulpitu są niezależne. Dane logowania są przechowywane na dysku instancji, a ponowne utworzenie kontenera zachowuje dysk; usunięcie dysku usunie lokalną sesję. + +Każda instancja jest rozliczana niezależnie i działa przez zakupiony czas. Wywołania REST / MCP nie są dodatkowo rozliczane za wiadomość, a rzeczywista cena zależy od strony pakietu. Obecnie domyślnie odwołuje się do pakietu czasu trwania robota WeChat, a przed ostatecznym udostępnieniem należy potwierdzić wycenę w połączeniu z zasobami operacyjnymi. + +## API i MCP + +Użyj adresu API instancji na stronie zarządzania, wszystkie interfejsy konta przekazują `Authorization: Bearer `. Te ścieżki należą do dedykowanej instancji, a nie do współdzielonej bramy API. Adres MCP to adres instancji z dodanym `/mcp/`, używający tego samego tokenu Bearer. + +| Interfejs | Funkcja | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Czy konto jest gotowe i lista możliwości | +| `GET /api/auth/qr` | Aktualny kod QR logowania w Base64 PNG | +| `GET /api/account` | Aktualne konto | +| `GET /api/contacts?kind=all` | Wewnętrzni współpracownicy i kontakty zewnętrzne, można określić internal / external | +| `GET /api/conversations` | Lokalne konwersacje z zachowaniem oryginalnego ID konwersacji | +| `GET /api/messages` | Lokalnie zsynchronizowane wiadomości; parametry conversation_id, after_rowid, limit | +| `POST /api/search` | Wyszukiwanie kontaktów, konwersacji i lokalnego tekstu | +| `POST /api/messages` | Asynchroniczne zadanie wysyłania tekstu, należy podać Idempotency-Key | +| `POST /api/messages/send` | Ten sam punkt wejścia wysyłania, obsługuje jeden lub wiele celów | +| `GET /api/groups/{conversation_id}` | Lokalnie zsynchronizowane informacje o grupie i członkowie | +| `GET /api/tasks` | Ostatnie zadania i wyniki dla każdego celu | +| `GET /api/tasks/{id}` | Zapytanie o wynik wysyłania | +| `POST /api/tasks/{id}/cancel` | Anulowanie zadania, które jeszcze się nie rozpoczęło | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Wstrzymanie automatyzacji; wznowienie po weryfikacji właściciela | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Stan instancji i bieżący ekran, oba wymagają uwierzytelnienia | +| `GET /api/events?after=0` | Zdarzenia wiadomości z kursorem możliwym do wznowienia | +| `WS /ws` | Strumień zdarzeń wiadomości, uwierzytelnianie Bearer | + +Treść wysyłania zawiera `target`, `type: "text"` oraz `text`. `target` akceptuje ID konwersacji, ID kontaktu, ID użytkownika firmowego lub unikalną pełną nazwę; preferowane jest używanie ID; gdy wyświetlana nazwa nadal nie może jednoznacznie wskazać obiektu, instancja odrzuci operację i nie będzie zgadywać obiektu. Kontakt bez lokalnej konwersacji najpierw otworzy konwersację przez klienta, a następnie wyśle wiadomość po sprawdzeniu rzeczywistego ID konwersacji. Nagłówek żądania `Idempotency-Key` składa się z 8–128 liter, cyfr lub `_.:-`. Powtórzone żądania tej samej operacji muszą ponownie używać tego samego klucza i tej samej treści żądania. + +Zastąpienie `target` tablicą `targets` pozwala wysyłać seryjnie do 1–50 jednoznacznie określonych celów. Nie można podawać obu jednocześnie. Wszystkie cele najpierw kończą rozpoznanie tożsamości, a różne aliasy wskazujące ten sam obiekt zostaną odrzucone. Po niepowodzeniu jednego celu kolejne wysyłanie zostaje zatrzymane, a wynik zadania rejestruje dla każdego elementu `succeeded`, `failed`, `unknown` lub `not_attempted`; nie należy traktować częściowego sukcesu jako pełnego sukcesu. Ten proces nadal wymaga prawdziwego odbioru określonych kontaktów w środowisku wdrożeniowym. + +Zadania mogą znajdować się w stanie queued, running, submitting, succeeded, failed, unknown lub cancelled. `succeeded` oznacza, że po przesłaniu w rekordzie odpowiedniej konwersacji znaleziono dokładny tekst i ID wiadomości serwera, `delivered` nadal ma wartość null i nie oznacza, że druga strona ją otrzymała. unknown oznacza, że wynik jest niejednoznaczny, sprawdź historię i nie powtarzaj wysyłania z nowym kluczem. Instancja nie ponawia automatycznie przerwanych zadań. + +Historia zawiera tylko treści, które klient już zsynchronizował, i nie może gwarantować pełnej historii. Wiadomości nietekstowe mogą zwracać typ unknown, a pobieranie załączników nie jest jeszcze dostępne. Zdarzenia zachowują ostatnie 10 000 wpisów, `gap` oznacza, że kursor przekroczył okno retencji. Pierwsze połączenie nie odtworzy starej historii jako nowych wiadomości. + +`server_accepted` i `server_id` w historii wiadomości mogą służyć do sprawdzenia, czy serwer zaakceptował lokalną wiadomość; jeśli istnieje tylko lokalny rekord bez ID serwera, nie można uznać wysyłania za udane. Te pola nie oznaczają, że odbiorca otrzymał lub przeczytał wiadomość. Rekordy zdarzeń zachowują stan w chwili wygenerowania, aby sprawdzić bieżący stan potwierdzenia, należy użyć interfejsu historii wiadomości. + +## Konto i dane uwierzytelniające + +Loguj się tylko na konto, do obsługi którego właściciel ma uprawnienia. Skonfiguruj token API w zaufanych aplikacjach; może on uzyskać dostęp do danych konta tej instancji. Nie publikuj haseł, kodów QR ani zrzutów ekranu czatów w miejscach publicznych. Wstrzymanie instancji przerwie zdarzenia w czasie rzeczywistym. Po wylogowaniu konta lub usunięciu urządzenia po stronie telefonu wymagane jest ponowne logowanie. + +Obecne wprowadzanie tekstu obsługuje tylko jedną linię, a znaki nowej linii zostaną wyraźnie odrzucone przed wysłaniem. Gdy klient wymaga weryfikacji bezpieczeństwa lub ponownego logowania, właściciel konta powinien je ukończyć na pulpicie zdalnym; instancja nie ominie weryfikacji. Zadania po przerwaniu weryfikacji mogą zwrócić unknown, najpierw sprawdź rekordy wiadomości i nie wysyłaj ponownie z nowym kluczem idempotencji. + +Po wykryciu monitu o weryfikację bezpieczeństwa, wylogowania konta lub zmiany kolejka automatyzacji zostanie trwale wstrzymana. Po ukończeniu weryfikacji na telefonie można kontynuować niewykonane jeszcze zadania przez „Wznów po weryfikacji” w konsoli instancji; zadania, które zostały już przesłane, ale których wynik jest niepewny, nie zostaną ponowione. Zwykła praca zdalna również może wywołać weryfikację bezpieczeństwa WeCom. Opisane oficjalnie 24-godzinne okno braku ponownej blokady po weryfikacji nie oznacza wyeliminowania wykrywania ani nie oznacza, że instancja może zagwarantować długotrwałą pracę bez nadzoru. diff --git a/pt/guides/claude/claude_messages.mdx b/pt/guides/claude/claude_messages.mdx index c71cf6fd8..ac55a5166 100644 --- a/pt/guides/claude/claude_messages.mdx +++ b/pt/guides/claude/claude_messages.mdx @@ -3,9 +3,9 @@ title: "Solicitação e uso da API Claude Messages" description: "Claude AI API guide - Ace Data Cloud" --- -O Anthropic Claude é um sistema de diálogo de IA muito poderoso que, bastando inserir um prompt, pode gerar respostas fluidas e naturais em poucos segundos. A API Claude Messages é o formato de API nativo oficial da Anthropic. Diferentemente do formato compatível com OpenAI (Chat Completion), ela adota a própria estrutura de solicitação e resposta da Anthropic, permitindo aproveitar melhor os recursos exclusivos do Claude, como entrada de conteúdo multimodal, chamada de ferramentas, pensamento estendido (Extended Thinking) e outros recursos avançados. +O Anthropic Claude é um sistema de conversação de IA muito poderoso que, basta inserir um prompt, pode gerar respostas fluentes e naturais em poucos segundos. A API Claude Messages é o formato de API nativo oficial da Anthropic. Diferente do formato compatível com OpenAI (Chat Completion), ela adota a própria estrutura de solicitação e resposta da Anthropic, permitindo aproveitar melhor as capacidades exclusivas do Claude, como entrada de conteúdo multimodal, chamada de ferramentas, pensamento profundo (Extended Thinking) e outros recursos avançados. -Este documento apresenta principalmente o processo de uso das operações da API Claude Messages. Com ela, podemos usar uma interface nativa consistente com a oficial da Anthropic para chamar as funções de diálogo do Claude. +Este documento apresenta principalmente o processo de uso das operações da API Claude Messages. Com ela, podemos usar uma interface nativa consistente com a oficial da Anthropic para chamar os recursos de conversação do Claude. ## Processo de solicitação @@ -13,9 +13,9 @@ Para usar a API Claude Messages, primeiro acesse o [Console Ace Data Cloud](http ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Se você ainda não tiver feito login ou se registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login. Após a conclusão, você retornará automaticamente à página atual. +Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login para se registrar e fazer login, retornando automaticamente à página atual após a conclusão. -**Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar um separadamente para cada serviço.** A primeira solicitação concede créditos gratuitos para experimentar sem custo; quando os créditos forem insuficientes, você poderá recarregar o saldo comum no [console](https://platform.acedata.cloud/console/coin). +**Um único API Token pode chamar todos os serviços da plataforma, sem a necessidade de solicitar separadamente para cada serviço.** A primeira solicitação concede créditos gratuitos, permitindo uma experiência gratuita; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin). > 📘 Documentação completa: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) @@ -23,21 +23,22 @@ Se você ainda não tiver feito login ou se registrado, será redirecionado auto O caminho de solicitação da API Claude Messages é `/v1/messages`, mantendo-se consistente com a API oficial da Anthropic. Precisamos fornecer pelo menos três parâmetros obrigatórios: -- `model`: seleciona o modelo Claude a ser usado. `claude-opus-5-5` é fornecido apenas por meio da API Messages, oferece suporte a contexto de 1 milhão de Tokens, saída máxima de 128K Tokens e sempre ativa o pensamento adaptativo. O mais recente carro-chefe é `claude-fable-5-1` (contexto de 1 milhão de Tokens, saída máxima de 128K Tokens); o antigo `claude-fable-5` continua mantido por compatibilidade. `claude-sonnet-5-5` foi adicionado à série de interfaces nativas Messages, oferecendo suporte a entrada de imagens e pensamento adaptativo; seus preços oficiais de referência para entrada, saída e leitura de cache são, respectivamente, 2, 10 e 0,20 dólares por milhão de Tokens. -- `messages`: array das mensagens de entrada; cada mensagem contém `role` (função) e `content` (conteúdo), sendo que `role` oferece suporte a `user` e `assistant`. -- `max_tokens`: número máximo de tokens de saída, usado para limitar o comprimento de uma única resposta. +- `model`: Seleciona o modelo Claude a ser usado. `claude-opus-5-5` é fornecido apenas pela API Messages, suporta contexto de 1 milhão de Tokens, saída máxima de 128K Tokens e sempre ativa o pensamento adaptativo. O mais recente modelo principal é `claude-fable-5-1` (contexto de 1 milhão de Tokens, saída máxima de 128K Tokens); o antigo `claude-fable-5` permanece compatível. `claude-sonnet-5-5` foi adicionado à série de interfaces nativas Messages, suporta entrada de imagens e pensamento adaptativo; seus preços de referência oficiais para entrada, saída e leitura de cache são, respectivamente, 2, 10 e 0,20 dólares por milhão de Tokens. +- `messages`: Array de mensagens de entrada, em que cada mensagem contém `role` (função) e `content` (conteúdo), e `role` suporta `user` e `assistant`. +- `max_tokens`: Número máximo de tokens de saída, usado para limitar o comprimento de uma única resposta. Parâmetros opcionais comuns: -- `system`: prompt do sistema, usado para definir o comportamento e a função do modelo. -- `temperature`: aleatoriedade da geração, entre 0 e 1; quanto maior o valor, mais divergente será a resposta. -- `stream`: se deve usar resposta em streaming; defini-lo como `true` permite o efeito de retorno caractere por caractere. -- `stop_sequences`: sequências de parada personalizadas; o modelo interromperá a geração ao encontrar esses textos. -- `top_p`: parâmetro de amostragem de núcleo, que controla a aleatoriedade da geração em conjunto com temperature. -- `top_k`: realiza a amostragem apenas entre as K opções com maior probabilidade. -- `tools`: definição de ferramentas, usada para permitir que o modelo chame funções externas. -- `tool_choice`: controla como o modelo usa as ferramentas fornecidas. -- `cache_control`: cria automaticamente um ponto de interrupção de cache no último bloco de conteúdo armazenável em cache da solicitação; também pode ser escrito em blocos de conteúdo específicos. +- `system`: Prompt de sistema, usado para definir o comportamento e a função do modelo. +- `temperature`: Aleatoriedade de geração, entre 0 e 1; quanto maior o valor, mais divergente será a resposta. +- `stream`: Define se deve usar resposta em streaming; configurá-lo como `true` permite um efeito de retorno palavra por palavra. +- `stop_sequences`: Sequências de parada personalizadas; o modelo interromperá a geração ao encontrar esses textos. +- `top_p`: Parâmetro de amostragem de núcleo, usado em conjunto com temperature para controlar a aleatoriedade da geração. +- `top_k`: Amostra apenas entre as K opções com maior probabilidade. +- `tools`: Definições de ferramentas, usadas para permitir que o modelo chame funções externas. +- `tool_choice`: Controla como o modelo usa as ferramentas fornecidas. +- `cache_control`: Cria automaticamente um ponto de interrupção de cache no último bloco de conteúdo armazenável em cache da solicitação; também pode ser escrito em blocos de conteúdo específicos. +- `metadata`: Objeto opcional de metadados da solicitação. `metadata.user_id` é uma string e pode transmitir o identificador de usuário personalizado do chamador, por exemplo, `{"user_id":"example-user-001"}`; recomenda-se usar um identificador estável que não contenha informações pessoais. Ele não substitui a autenticação `Authorization`, nem precisa ser incluído no conteúdo da conversa em `messages`. ### Exemplo cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -107,24 +110,24 @@ Após a chamada, o resultado retornado é o seguinte: ``` Descrição dos campos do resultado retornado: +- `id`：o identificador único desta mensagem. +- `type`：sempre `message`. +- `role`：sempre `assistant`. +- `content`：a matriz de conteúdo da resposta, cada elemento contém `type` (como `text`) e o conteúdo correspondente. +- `model`：o nome do modelo que processa a solicitação. +- `stop_reason`：o motivo da interrupção. Os valores estáveis incluem `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (pode devolver o conteúdo atual do assistant sem alterações para continuar), `refusal` e `model_context_window_exceeded`. +- `stop_sequence`：se a interrupção ocorrer devido a uma sequência de parada personalizada, exibe o texto da sequência de parada correspondente. +- `stop_details`：quando `stop_reason` for `refusal`, pode conter a categoria e a descrição da recusa. +- `usage`：estatísticas de uso de tokens. `input_tokens` é a entrada não armazenada em cache; `cache_creation_input_tokens` e `cache_read_input_tokens` são, respectivamente, a gravação e a leitura do cache; `output_tokens` é o número total de tokens de saída. Se `output_tokens_details.thinking_tokens` for retornado, esse valor será um subconjunto de `output_tokens`; não o some novamente ao calcular o total ou o custo. Esse detalhamento pode ser `null` ou ser omitido quando não houver uma contagem autoritativa. +- `usage.cache_creation`：detalhes opcionais do TTL de gravação do cache, contendo `ephemeral_5m_input_tokens` e `ephemeral_1h_input_tokens`. Quando o objeto existir, a soma dos dois será igual a `cache_creation_input_tokens`; um campo `null` ou omitido indica que a resposta atual não possui uma divisão de TTL disponível e não deve ser interpretado como `0`. +- `usage.cost`：respostas não transmitidas por streaming podem conter o objeto de consumo de créditos registrado pela Ace Data Cloud, no qual `amount` é o consumo real desta vez, `currency` é a unidade de medição e `list_amount` é o valor antes do desconto (se houver). O preço-base oficial de leitura de cache do Fable 5.1 é de US$ 0,25/milhão de Tokens, e os preços-base de gravação de cache de 5 minutos e 1 hora são de US$ 12,50 e US$ 20/milhão de Tokens, respectivamente; os preços reais da plataforma são convertidos de acordo com o desconto do plano. + +## Prompt de sistema + +A Claude Messages API oferece suporte à definição de prompts de sistema por meio do campo `system`, usados para definir o comportamento, o papel e o contexto do modelo. -- `id`: identificador exclusivo desta mensagem. -- `type`: sempre é `message`. -- `role`: sempre é `assistant`. -- `content`: array do conteúdo da resposta; cada elemento contém `type` (como `text`) e o conteúdo correspondente. -- `model`: nome do modelo que processou a solicitação. -- `stop_reason`: motivo da interrupção. Os valores estáveis incluem `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (você pode reenviar o conteúdo atual do assistant sem alterações para continuar), `refusal` e `model_context_window_exceeded`. -- `stop_sequence`: se a interrupção ocorreu devido a uma sequência de parada personalizada, exibe o texto da sequência de parada correspondente. -- `stop_details`: quando `stop_reason` for `refusal`, pode conter a categoria e a explicação da recusa. -- `usage`: estatísticas de uso de tokens. `input_tokens` são entradas não armazenadas em cache; `cache_creation_input_tokens` e `cache_read_input_tokens` são, respectivamente, gravação e leitura de cache; `output_tokens` é o número de tokens de toda a saída. Se `output_tokens_details.thinking_tokens` for retornado, esse valor é um subconjunto de `output_tokens`; não o some novamente ao calcular o total ou o custo. Esse detalhamento pode ser `null` ou omitido quando não houver uma contagem oficial. -- `usage.cache_creation`: detalhamento opcional do TTL de gravação de cache, contendo `ephemeral_5m_input_tokens` e `ephemeral_1h_input_tokens`. Quando o objeto existir, a soma dos dois será igual a `cache_creation_input_tokens`; um campo `null` ou omitido indica que a resposta atual não tem uma divisão de TTL disponível e não pode ser interpretado como `0`. -- `usage.cost`: respostas sem streaming podem incluir um objeto de consumo de créditos registrado pela Ace Data Cloud, em que `amount` é o consumo real desta vez, `currency` é a unidade de medição e `list_amount` é o valor antes do desconto (se houver). O preço-base oficial de leitura de cache do Fable 5.1 é de $0,25/milhão de Tokens, e os preços-base de gravação de cache de 5 minutos e 1 hora são de $12,50 e $20/milhão de Tokens, respectivamente; o preço real da plataforma é convertido de acordo com o desconto do plano. - -## Prompt do sistema - -A API Claude Messages oferece suporte à definição de prompts do sistema por meio do campo `system`, usado para definir o comportamento, a função e o contexto do modelo. +### Exemplo em Python -### Exemplo Python ```python import requests @@ -149,11 +152,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Ao definir o prompt `system`, é possível controlar precisamente o papel e o comportamento do Claude. +Ao configurar o prompt `system`, é possível controlar precisamente o papel e o comportamento do Claude. ## Resposta em streaming -Esta interface também oferece suporte a respostas em streaming. Defina o parâmetro `stream` como `true` para obter um retorno progressivo, o que é muito adequado para implementar a exibição palavra por palavra em páginas web. +Esta interface também oferece suporte a respostas em streaming; basta definir o parâmetro `stream` como `true` para obter um efeito de retorno gradual, sendo muito adequada para implementar a exibição de texto caractere por caractere em páginas da web. ### Exemplo em Python @@ -183,16 +186,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -A resposta em streaming é retornada no formato Server-Sent Events (SSE), com cada linha prefixada por `event:` e `data:`. Os tipos de eventos de streaming incluem: +As respostas em streaming são retornadas no formato Server-Sent Events (SSE), e cada linha é prefixada por `event:` e `data:`. Os tipos de eventos de streaming incluem: -- `message_start`: início da mensagem, incluindo as informações básicas da mensagem e o nome do modelo. -- `content_block_start`: início do bloco de conteúdo. -- `content_block_delta`: atualização incremental do bloco de conteúdo, incluindo o fragmento de texto recém-gerado. -- `content_block_stop`: fim do bloco de conteúdo. -- `message_delta`: atualização incremental no nível da mensagem, incluindo as informações de `stop_reason` e `usage` final. O valor autoritativo de `output_tokens_details.thinking_tokens` deve ser lido apenas do último `message_delta.usage`, sem acumulá-lo entre eventos. -- `message_stop`: fim da mensagem. +- `message_start`：início da mensagem, contendo as informações básicas da mensagem e o nome do modelo. +- `content_block_start`：início do bloco de conteúdo. +- `content_block_delta`：atualização incremental do bloco de conteúdo, contendo o fragmento de texto recém-gerado. +- `content_block_stop`：fim do bloco de conteúdo. +- `message_delta`：atualização incremental no nível da mensagem, contendo `stop_reason` e as informações finais de `usage`. O valor autoritativo de `output_tokens_details.thinking_tokens` deve ser lido somente do último `message_delta.usage`; não o acumule entre eventos. +- `message_stop`：fim da mensagem. -O resultado da saída é o seguinte: +O efeito de saída é o seguinte: ``` event: message_start @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Como pode ser visto, o evento `content_block_delta` na resposta em streaming contém o conteúdo de texto gerado progressivamente. Ao concatenar todos os `text_delta`, é possível obter a resposta completa. +Pode-se observar que, na resposta em streaming, o evento `content_block_delta` contém o conteúdo de texto gerado gradualmente; ao concatenar todos os `text_delta`, é possível obter a resposta completa. ### Exemplo em JavaScript @@ -251,9 +254,9 @@ while (true) { } ``` -## Conversa com múltiplas rodadas +## Conversas de múltiplos turnos -Se desejar integrar a funcionalidade de conversa com múltiplas rodadas, é necessário alternar as mensagens com os papéis `user` e `assistant` no array `messages`, transmitindo também todo o histórico anterior da conversa. +Se você quiser integrar a funcionalidade de conversas de múltiplos turnos, será necessário alternar as mensagens com os papéis `user` e `assistant` na matriz `messages` e enviar junto o histórico anterior da conversa. ### Exemplo em Python @@ -283,7 +286,6 @@ print(response.json()) ``` O resultado retornado é o seguinte: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,11 +309,11 @@ O resultado retornado é o seguinte: Ao transmitir o histórico completo da conversa em `messages`, o Claude pode fornecer respostas precisas com base no contexto. -## Modelo de raciocínio profundo +## Modelos de raciocínio profundo -O thinking e o thinking summary do Claude são dois conceitos diferentes: o modelo pode realizar raciocínio interno, mas a API não retorna a cadeia de pensamento original. Quando for necessário exibir o processo de raciocínio, a API retorna um resumo processado. +O thinking e o thinking summary do Claude são dois conceitos diferentes: o modelo pode realizar raciocínio interno, mas a API não retorna a cadeia de pensamento original. Quando é necessário exibir o processo de raciocínio, a API retorna um resumo processado. -O modelo atual recomenda usar adaptive thinking e controlar o esforço total de raciocínio por meio de `output_config.effort`: +Atualmente, recomenda-se que os modelos usem adaptive thinking e controlem o investimento geral de raciocínio por meio de `output_config.effort`: ```python import requests @@ -350,26 +352,27 @@ O bloco thinking na resposta tem a seguinte forma: "signature": "opaque-signature" } ``` -- `display: "summarized"` retorna um resumo de pensamento legível; não é a cadeia de raciocínio original. -- `display: "omitted"` retorna `thinking: ""`, mas ainda preserva a `signature` opaca para dar suporte a conversas subsequentes. -- `display: "updates"` é o modo beta da Anthropic, exigindo `anthropic-beta: thinking-display-updates-2026-08-18`. A definição oficial é ocultar o corpo do raciocínio e exibir breves atualizações de progresso entre chamadas de ferramentas. A plataforma transmite esse parâmetro e o cabeçalho beta pelos valores originais, e não força a reescrita para `summarized`; o conteúdo de saída real depende do suporte do modelo selecionado. -- `thinking`, `output_config`, effort, parâmetros de amostragem e campos de extensão recém-adicionados são transmitidos pelos valores originais. A plataforma não mantém enumerações de valores ou restrições de combinação codificadas por modelo, nem reescreve automaticamente o modo thinking; cabe ao modelo selecionado decidir se aceita esses parâmetros, e os erros de parâmetros retornados pelo modelo serão repassados ao cliente. -- Os valores padrão de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 são `omitted`; Opus 4.6, Sonnet 4.6 e modelos anteriores que oferecem suporte a thinking usam `summarized` por padrão. + +- `display: "summarized"` retorna um resumo de pensamento legível; ele não é a cadeia de pensamento original. +- `display: "omitted"` retorna `thinking: ""`, mas ainda mantém a `signature` opaque para dar suporte a conversas subsequentes. +- `display: "updates"` é o modo beta da Anthropic, que requer `anthropic-beta: thinking-display-updates-2026-08-18`. A definição oficial é ocultar o texto do raciocínio e exibir breves atualizações de progresso entre chamadas de ferramentas. A plataforma transmite esse parâmetro e o cabeçalho de solicitação beta conforme os valores originais, sem forçar a reescrita para `summarized`; o conteúdo real da saída depende do suporte do modelo selecionado. +- `thinking`, `output_config`, effort, parâmetros de amostragem e novos campos de extensão são transmitidos conforme os valores originais. A plataforma não mantém enumerações de valores ou restrições de combinação codificadas por modelo, nem reescreve automaticamente o modo thinking; cabe ao modelo selecionado decidir se aceita esses parâmetros, e os erros de parâmetros retornados pelo modelo são repassados ao cliente. +- O valor padrão de display para Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 e Opus 4.7 é `omitted`; Opus 4.6, Sonnet 4.6 e modelos anteriores com suporte a thinking usam `summarized` por padrão. - Display afeta apenas o conteúdo retornado e a latência de streaming, não desativa o raciocínio nem reduz a cobrança de tokens de thinking. -- Se thinking é ativado por padrão e o valor padrão de display são duas questões independentes. Opus 5 e Sonnet 5 ativam adaptive thinking por padrão; para Opus 5, omitir `thinking` equivale a adaptive, e omitir `output_config.effort` equivale a `high`. Opus 4.8, 4.7 e 4.6 exigem ativação explícita. -- Thinking e o corpo final compartilham o orçamento de saída de `max_tokens`. Quando o orçamento é muito baixo, thinking pode ocupar a maior parte da cota, deixando o corpo vazio ou truncado; aumente `max_tokens` ou use effort `low` / `medium` para controlar o investimento em raciocínio. -- Para modelos que permitem desativar thinking, pode-se passar `thinking: {"type":"disabled"}`. Novos modos, como `between_tools`, e combinações de effort dependem do modelo selecionado; a plataforma não rejeita antecipadamente com base em regras antigas de modelo. -- Um orçamento de pensamento fixo pode ser transmitido por meio de `budget_tokens`; modelos novos geralmente usam `thinking.type=adaptive` e `output_config.effort`. O suporte a orçamento fixo ou à desativação do pensamento depende das capacidades atuais do modelo selecionado. -- Em conversas de múltiplas rodadas e chamadas de ferramentas, os blocos completos de thinking e a signature retornados pelo assistant devem ser retransmitidos como estão; não modifique nem gere uma signature por conta própria. -- A transmissão de parâmetros não significa que todos os modelos suportam todos os recursos. Chamadas entre protocolos ainda exigem conversão, e o escopo de suporte e os erros para conteúdos como `redacted_thinking` são determinados pelo serviço de modelo que realmente processa a solicitação. +- A ativação padrão de thinking e o valor padrão de display são duas questões independentes. Opus 5 e Sonnet 5 ativam adaptive thinking por padrão; para o Opus 5, omitir `thinking` equivale a adaptive, e omitir `output_config.effort` equivale a `high`. Opus 4.8, 4.7 e 4.6 exigem ativação explícita. +- Thinking e o texto final compartilham o orçamento de saída de `max_tokens`. Quando o orçamento é muito pequeno, thinking pode consumir grande parte da cota, deixando o texto vazio ou truncado; aumente `max_tokens` ou use effort `low` / `medium` para controlar o investimento de raciocínio. +- Para modelos que permitem desativar thinking, pode-se transmitir `thinking: {"type":"disabled"}`. Novos modos como `between_tools` e combinações de effort dependem do modelo selecionado; a plataforma não os rejeita antecipadamente com base em regras antigas de modelos. +- Um orçamento fixo de pensamento pode ser transmitido por meio de `budget_tokens`; os novos modelos normalmente usam `thinking.type=adaptive` e `output_config.effort`. O suporte a orçamento fixo ou à desativação do pensamento depende dos recursos atuais do modelo selecionado. +- Em conversas de múltiplos turnos e chamadas de ferramentas, o bloco thinking completo e a signature retornados pelo assistant devem ser retransmitidos sem alterações; não modifique nem gere a signature por conta própria. +- A transmissão de parâmetros não significa que todos os modelos suportam todos os recursos. Chamadas entre protocolos ainda exigem conversão, e o escopo de suporte e os erros para conteúdos como `redacted_thinking` são determinados pelo serviço do modelo que realmente processa a solicitação. -Em solicitações de streaming, `summarized` produz `thinking_delta`; `omitted` não produz `thinking_delta`, preservando apenas o ciclo de vida do bloco thinking e `signature_delta`. +Em solicitações de streaming, `summarized` produz `thinking_delta`; `omitted` não produz `thinking_delta`, mantendo apenas o ciclo de vida do bloco thinking e `signature_delta`. ## Modelos visuais -Claude oferece suporte a entrada multimodal e pode processar texto e imagens simultaneamente. Na Messages API, os recursos visuais podem ser usados definindo `content` no formato de array e passando blocos de conteúdo de imagem. +O Claude oferece suporte a entradas multimodais e pode processar texto e imagens simultaneamente. Na Messages API, os recursos visuais podem ser usados definindo `content` no formato de array e transmitindo blocos de conteúdo de imagem. -### Usar imagens codificadas em Base64 +### Usando imagens codificadas em Base64 ```python import base64 @@ -415,7 +418,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### Usar imagens por URL +### Usando imagens por URL ```python import requests @@ -456,7 +459,6 @@ print(response.json()) ``` ### Exemplo de cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -490,7 +492,7 @@ Os formatos de imagem compatíveis incluem: `image/jpeg`, `image/png`, `image/gi ## Documentos e PDF -PDF usa o bloco de conteúdo `document`, com suporte a duas fontes estáveis: Base64 e URL. A fonte Base64 deve usar `application/pdf`: +PDF usa o bloco de conteúdo `document`, oferecendo suporte a duas fontes estáveis: Base64 e URL. A fonte Base64 deve usar `application/pdf`: ```python import base64 @@ -521,9 +523,9 @@ payload = { A fonte URL é escrita como `{"type":"url","url":"https://example.com/report.pdf"}`. `document` também oferece suporte a `text/plain` e à fonte `content` composta por blocos text/image; os campos opcionais incluem `title`, `context` e `citations`. A fonte `file_id` da Files API pertence a uma funcionalidade beta independente e não faz parte do contrato estável desta interface. -## Cache de prompts +## Cache de prompt -O `cache_control` de nível superior posicionará automaticamente o ponto de interrupção de cache no último bloco armazenável em cache: +O `cache_control` de nível superior coloca automaticamente o ponto de interrupção do cache no último bloco armazenável em cache: ```python payload = { @@ -534,9 +536,10 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Quando for necessário controlar precisamente a posição, também é possível escrever o mesmo `cache_control` em blocos de conteúdo text, image, document, tool_use, tool_result ou em definições de ferramentas. `ttl` oferece suporte a `5m` (padrão) e `1h`; determine a gravação e o acerto do cache por meio de `usage.cache_creation_input_tokens` e `usage.cache_read_input_tokens`. -Quando a resposta fornecer `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Se `cache_creation` for `null` ou for omitido, isso indica que há apenas o total de gravações em cache, sem uma divisão de TTL autoritativa; nesse caso, não trate nenhum bucket como 0 conhecido, e a cobrança e o total ainda devem se basear no campo aggregate. +Quando for necessário controlar precisamente a posição, também é possível escrever o mesmo `cache_control` nos blocos de conteúdo text, image, document, tool_use, tool_result ou na definição da ferramenta. `ttl` oferece suporte a `5m` (padrão) e `1h`; use `usage.cache_creation_input_tokens` e `usage.cache_read_input_tokens` para determinar a gravação e o acerto do cache. + +Quando a resposta fornece `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Se `cache_creation` for `null` ou for omitido, isso indica que há apenas o total de gravações em cache, sem uma divisão de TTL autoritativa; nesse caso, não trate nenhum bucket como um 0 conhecido, e a cobrança e o total ainda devem se basear no campo agregado. Exemplo de resultado retornado: @@ -561,9 +564,9 @@ Exemplo de resultado retornado: } ``` -## Chamada de Ferramentas (Tool Use) +## Chamada de ferramentas (Tool Use) -A API Claude Messages oferece suporte nativo à funcionalidade de chamada de ferramentas, permitindo que o modelo chame as ferramentas/funções que você predefiniu quando necessário. +A Claude Messages API oferece suporte nativo à funcionalidade de chamada de ferramentas, permitindo que o modelo chame suas ferramentas/funções predefinidas quando necessário. ### Exemplo em Python @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Quando o modelo decide chamar uma ferramenta, o `content` no resultado retornado incluirá um bloco de conteúdo do tipo `tool_use`: +Quando o modelo decide chamar uma ferramenta, o resultado retornado conterá um bloco de conteúdo do tipo `tool_use` em `content`: ```json { @@ -685,38 +688,38 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -O modelo gerará a resposta final em linguagem natural com base no resultado retornado pela ferramenta. +O modelo gerará uma resposta final em linguagem natural com base no resultado retornado pela ferramenta. ## Diferenças em relação à Chat Completion API -A Ace Data Cloud fornece simultaneamente dois formatos de API Claude, cujas principais diferenças são as seguintes: - -O `usage.input_tokens` da Messages API representa apenas a entrada não armazenada em cache, enquanto `cache_read_input_tokens` e `cache_creation_input_tokens` são buckets de cobrança independentes; os três são calculados separadamente de acordo com os preços correspondentes. +A Ace Data Cloud fornece simultaneamente dois formatos de Claude API, e as principais diferenças entre eles são as seguintes: +O `usage.input_tokens` da Messages API representa apenas entradas não armazenadas em cache; `cache_read_input_tokens` e `cache_creation_input_tokens` são buckets de cobrança independentes; os três serão calculados separadamente de acordo com os preços correspondentes. | Recurso | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Formato | Formato nativo da Anthropic | Formato compatível com OpenAI | | Prompt do sistema | Campo `system` independente | Transmitido por meio de `role: "system"` em `messages` | -| Estrutura de resposta | Array `content` (suporta vários tipos) | Array `choices` (inclui `message`) | -| Raciocínio profundo | `thinking` nativo e `output_config.effort` | Estratégia padrão do modelo e parâmetros compatíveis | +| Estrutura da resposta | Array `content` (suporta vários tipos) | Array `choices` (contém `message`) | +| Formato de streaming | Eventos SSE (vários tipos de eventos) | Linhas SSE `data` | +| Pensamento profundo | `thinking` nativo e `output_config.effort` | Estratégia padrão do modelo e parâmetros compatíveis | | Chamada de ferramentas | `tools` nativo + `input_schema` | Formato `tools` compatível com OpenAI | | Estatísticas de Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Se o seu sistema já estiver integrado com uma API no formato OpenAI, você pode usar a Chat Completion API para fazer a mudança de forma integrada. Se precisar usar todos os recursos nativos do Claude, recomenda-se usar a Messages API. +Se o seu sistema já está integrado à API no formato OpenAI, você pode usar a Chat Completion API para alternar perfeitamente. Se você precisar usar todos os recursos nativos do Claude, recomenda-se usar a Messages API. -## Tratamento de Erros +## Tratamento de erros -As respostas de erro da interface pública usam o envelope da plataforma Ace Data Cloud: `error.code` é o código de erro estável, `error.message` é a descrição, e `trace_id` é usado para investigar solicitações. Os status HTTP comuns incluem: +As respostas de erro da interface pública usam o envelope da plataforma Ace Data Cloud: `error.code` é um código de erro estável, `error.message` é a descrição, e `trace_id` é usado para rastrear solicitações. Os status HTTP comuns incluem: -- `400`: os parâmetros da solicitação ou o conteúdo do protocolo são inválidos. -- `401`: o token de autorização é inválido, está ausente ou expirou. -- `403`: acesso proibido, saldo insuficiente ou cota restrita. -- `404`: a API ou o modelo não existe. -- `413`: o corpo da solicitação é muito grande. -- `429`: há solicitações em excesso. -- `500` / `503` / `504`: erro de serviço, indisponibilidade temporária ou tempo limite de processamento excedido. +- `400`: Os parâmetros da solicitação ou o conteúdo do protocolo são inválidos. +- `401`: O token de autorização é inválido, está ausente ou expirou. +- `403`: Acesso proibido, saldo insuficiente ou cota limitada. +- `404`: A API ou o modelo não existe. +- `413`: O corpo da solicitação é muito grande. +- `429`: Solicitações em excesso. +- `500` / `503` / `504`: Erro de serviço, temporariamente indisponível ou tempo limite de processamento excedido. -### Exemplo de Resposta de Erro +### Exemplo de resposta de erro ```json { @@ -728,7 +731,8 @@ As respostas de erro da interface pública usam o envelope da plataforma Ace Dat } ``` -Essa estrutura de erro é o contrato de tempo de execução da Ace Data Cloud e não equivale ao envelope de erro oficial da Anthropic; processe-a de acordo com o status HTTP e `error.code`. +Essa estrutura de erro é o contrato de tempo de execução do Ace Data Cloud e não equivale ao envelope de erro oficial da Anthropic; trate-o de acordo com o status HTTP e `error.code`. ## Conclusão -Por meio deste documento, você já aprendeu como usar a Claude Messages API para chamar a funcionalidade de conversa do Claude no formato nativo da Anthropic. A Messages API oferece suporte a recursos avançados como conversas básicas, prompts de sistema, respostas em streaming, conversas de múltiplas rodadas, raciocínio profundo, compreensão visual, PDFs, cache de prompts e chamadas de ferramentas. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento. + +Por meio deste documento, você já entendeu como usar a Claude Messages API para chamar as funcionalidades de conversa do Claude no formato nativo da Anthropic. A Messages API oferece suporte a recursos avançados como conversas básicas, prompts de sistema, respostas em streaming, conversas de múltiplas rodadas, pensamento profundo, compreensão visual, PDF, cache de prompts e chamadas de ferramentas. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento. diff --git a/pt/guides/openai/openai_embeddings.mdx b/pt/guides/openai/openai_embeddings.mdx index eae628877..1faf3776b 100644 --- a/pt/guides/openai/openai_embeddings.mdx +++ b/pt/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API Solicitação e Uso" +title: "Solicitação e uso da API de Embeddings da OpenAI" description: "OpenAI generation API guide - Ace Data Cloud" --- -Serviço de vetores de palavras da OpenAI, utilizado para gerar resultados de vetores de palavras que representam o texto de entrada. +Serviço de vetores de palavras da OpenAI, usado para gerar resultados de vetores de palavras que representam o texto de entrada. -Este documento apresenta principalmente o fluxo de operação do uso da OpenAI Embeddings API, com a qual podemos criar vetores de incorporação que representam o texto de entrada. +Este documento apresenta principalmente o processo de uso das operações da API de Embeddings da OpenAI. Com ela, podemos criar vetores de embedding que representam o texto de entrada. -## Processo de Solicitação +## Processo de solicitação -Para usar a OpenAI Embeddings API, primeiro acesse o [Painel de Controle da Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro. +Para usar a API de Embeddings da OpenAI, primeiro obtenha seu API Token no [Console do Ace Data Cloud](https://platform.acedata.cloud/console/applications) e guarde-o para uso posterior. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será retornado automaticamente à página atual. +Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login, onde será convidado a se registrar e fazer login. Após a conclusão, você retornará automaticamente à página atual. -**Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar individualmente para cada serviço.** A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no [painel de controle](https://platform.acedata.cloud/console/coin). +**Um único API Token permite chamar todos os serviços da plataforma, sem necessidade de solicitar separadamente para cada serviço.** A primeira solicitação inclui créditos gratuitos para uma experiência sem custo; quando os créditos forem insuficientes, você poderá recarregar o saldo universal no [console](https://platform.acedata.cloud/console/coin). -> 📘 Documentação Completa: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) +> 📘 Documentação completa: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## Uso Básico +## Uso básico -Em seguida, você pode preencher os conteúdos correspondentes na interface, conforme mostrado na imagem: +Em seguida, você pode preencher o conteúdo correspondente na interface, conforme mostrado na imagem:

-Na primeira vez que usar esta interface, precisamos preencher pelo menos três conteúdos: um é `authorization`, que pode ser selecionado diretamente na lista suspensa. O outro parâmetro é `model`, que é a categoria do modelo que escolhemos usar do site da OpenAI; aqui temos principalmente 3 tipos de modelos, e mais detalhes podem ser encontrados nos modelos que fornecemos. O último parâmetro é `input`, que é o texto que precisamos converter em vetor de palavras. +Ao usar esta interface pela primeira vez, precisamos preencher pelo menos três conteúdos. Um deles é `authorization`, que pode ser selecionado diretamente na lista suspensa. Outro parâmetro é `model`; `model` é a categoria de modelo oficial da OpenAI que escolhemos usar. Os modelos atualmente disponíveis são `text-embedding-3-small` e `text-embedding-3-large`. O `text-embedding-ada-002` deixou de ser fornecido; se índices vetoriais existentes usam esse modelo antigo, os vetores dos novos modelos não podem ser misturados diretamente e é necessário recriar o índice. O último parâmetro é `input`; `input` é o texto que precisamos converter em vetores de palavras. -Você também pode notar que à direita há um código de chamada correspondente gerado, que você pode copiar e executar diretamente, ou pode clicar no botão "Try" para testar. +Ao mesmo tempo, você pode observar que há uma geração de código de chamada correspondente no lado direito. Você pode copiar o código e executá-lo diretamente, ou clicar diretamente no botão «Try» para testar. Parâmetros opcionais: -- `dimensions`: recorta a dimensão do vetor, a saída padrão é a dimensão completa. -- `encoding_format`: formato de retorno, pode ser `float` ou `base64`. +- `dimensions`: reduz a dimensão do vetor; por padrão, retorna a dimensão completa. +- `encoding_format`: formato de retorno, podendo ser `float` ou `base64`.

-Código de exemplo de chamada em Python: +Código de chamada de exemplo em Python: ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Após a chamada, encontramos o resultado retornado como segue: +Após a chamada, constatamos que o resultado retornado é o seguinte: ```json { @@ -97,7 +97,7 @@ Após a chamada, encontramos o resultado retornado como segue: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,25 +105,25 @@ Após a chamada, encontramos o resultado retornado como segue: } ``` -O resultado retornado contém vários campos, descritos a seguir: +O resultado retornado possui vários campos, apresentados a seguir: -- `model`, o modelo utilizado para a conversão do texto em vetor de palavras. -- `usage`, informações sobre os tokens utilizados na conversão do texto em vetor de palavras. +- `model`, o modelo usado nesta conversão de texto em vetor de palavras. +- `usage`, as informações de token usadas nesta conversão de texto em vetor de palavras. - `data`, o resultado do vetor de palavras após a conversão do texto. -O campo `data` contém informações específicas sobre o vetor de palavras correspondente ao texto, onde `embedding` é o resultado específico do vetor de palavras gerado. +Entre eles, `data` contém as informações específicas dos vetores de palavras correspondentes ao texto, e seu `embedding` é o resultado específico do vetor de palavras gerado. -## Tratamento de Erros +## Tratamento de erros -Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo: +Ao chamar a API, se ocorrer um erro, a API retornará o código e as informações de erro correspondentes. Por exemplo: -- `400 token_mismatched`: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos. -- `400 api_not_implemented`: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos. +- `400 token_mismatched`: Solicitação incorreta, possivelmente devido a parâmetros ausentes ou inválidos. +- `400 api_not_implemented`: Solicitação incorreta, possivelmente devido a parâmetros ausentes ou inválidos. - `401 invalid_token`: Não autorizado, token de autorização inválido ou ausente. - `429 too_many_requests`: Muitas solicitações, você excedeu o limite de taxa. - `500 api_error`: Erro interno do servidor, algo deu errado no servidor. -### Exemplo de Resposta de Erro +### Exemplo de resposta de erro ```json { @@ -138,4 +138,4 @@ Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de ## Conclusão -Através deste documento, você já entendeu como usar a OpenAI Embeddings API para utilizar facilmente a funcionalidade de geração de vetores de palavras da OpenAI. Esperamos que este documento ajude você a integrar e usar melhor esta API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico. +Por meio deste documento, você já aprendeu como usar a API de Embeddings da OpenAI para utilizar facilmente a funcionalidade oficial de geração de vetores de palavras da OpenAI. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento. diff --git a/pt/guides/platform/wework_bot.mdx b/pt/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..1fadee49e --- /dev/null +++ b/pt/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "Robô do WeCom" +description: "Platform API guide - Ace Data Cloud" +--- + +Implante sua própria instância de conta do WeCom, use o WeCom no celular para fazer login por código QR e leia contas, contatos, conversas e mensagens sincronizadas localmente por REST API ou MCP. A instância corresponde a uma conta comum do WeCom, sem necessidade de servidor privatizado ou configuração de domínio de e-mail corporativo. + +Atualmente está em Alpha. A leitura da conta concluiu a validação em conversas reais; o envio de texto pelo próprio usuário e a leitura de retorno de eventos concluíram a aceitação real; as operações com outros contatos, grupos e a recuperação de novas instâncias ainda precisam concluir a aceitação no ambiente de implantação. Envio de mídia, resposta com citação, @ real, gerenciamento de membros de grupo e confirmação de entrega ainda não estão disponíveis. Consulte o valor retornado por `/api/capabilities` da instância. + +## Implantação e login + +Ative o serviço na categoria Deployment e selecione um plano de duração da instância. Após a implantação, abra a página de gerenciamento e use o WeCom da própria conta para escanear o código; se for necessária confirmação no celular ou outras etapas de login, abra a área de trabalho remota e insira a senha de desktop dessa instância. As credenciais da API e a senha de desktop são independentes. As informações de login são salvas no disco da instância; recriar o contêiner preserva o disco; excluir o disco excluirá a sessão local. + +Cada instância é cobrada separadamente e opera pela duração adquirida. Chamadas REST / MCP não são cobradas separadamente por mensagem; o preço real está sujeito à página do plano. Atualmente, o padrão de referência é o plano de duração do robô do WeChat; antes da disponibilidade final, é necessário confirmar a precificação com base nos recursos de operação. + +## API e MCP + +Use o endereço da API da instância na página de gerenciamento; todas as interfaces da conta devem incluir `Authorization: Bearer `. Esses caminhos pertencem à instância exclusiva e não são um gateway de API compartilhado. O endereço MCP é o endereço da instância acrescido de `/mcp/`, usando o mesmo token Bearer. + +| Interface | Função | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Se a conta está pronta e a lista de capacidades | +| `GET /api/auth/qr` | PNG Base64 do código QR de login atual | +| `GET /api/account` | Conta atual | +| `GET /api/contacts?kind=all` | Colegas internos e contatos externos; é possível especificar internal / external | +| `GET /api/conversations` | Conversas locais, preservando o ID original da conversa | +| `GET /api/messages` | Mensagens sincronizadas localmente; parâmetros conversation_id, after_rowid e limit | +| `POST /api/search` | Pesquisa de contatos, conversas e texto local | +| `POST /api/messages` | Tarefa assíncrona de envio de texto; é obrigatório fornecer Idempotency-Key | +| `POST /api/messages/send` | A mesma entrada de envio, com suporte para um ou vários destinos | +| `GET /api/groups/{conversation_id}` | Informações e membros de grupos sincronizados localmente | +| `GET /api/tasks` | Tarefas recentes e resultados de cada destino | +| `GET /api/tasks/{id}` | Consultar o resultado do envio | +| `POST /api/tasks/{id}/cancel` | Cancelar tarefas que ainda não foram iniciadas | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Pausar a automação; retomar após validação pelo próprio usuário | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Estado da instância e tela atual; ambos exigem autenticação | +| `GET /api/events?after=0` | Eventos de mensagem com cursor recuperável | +| `WS /ws` | Fluxo de eventos de mensagem, autenticação Bearer | + +O corpo do envio contém `target`, `type: "text"` e `text`. `target` aceita ID de conversa, ID de contato, ID de usuário corporativo ou nome completo único; priorize IDs; quando o nome exibido ainda não puder identificar de forma única, a instância recusará a operação e não tentará adivinhar o objeto. Para contatos sem conversa local, a conversa será primeiro aberta pelo cliente, e o envio será realizado após verificar o ID real da conversa. O cabeçalho `Idempotency-Key` possui de 8 a 128 caracteres de letras, números ou `_.:-`. Solicitações repetidas para a mesma operação devem reutilizar a mesma chave e o mesmo corpo de solicitação. + +Substitua `target` por um array `targets` para enviar em série a 1–50 destinos explicitamente especificados. Os dois não podem ser fornecidos ao mesmo tempo. Todos os destinos concluem primeiro a resolução de identidade; aliases diferentes que apontem para o mesmo objeto serão rejeitados. Após a falha de um destino, os envios subsequentes serão interrompidos, e o resultado da tarefa registrará para cada item `succeeded`, `failed`, `unknown` ou `not_attempted`; não trate sucesso parcial como sucesso total. Esse processo ainda precisa concluir a aceitação real dos contatos especificados no ambiente de implantação. + +As tarefas podem estar em queued, running, submitting, succeeded, failed, unknown ou cancelled. `succeeded` indica que, após o envio, foram encontrados o texto exato e o ID de mensagem do servidor no registro da conversa correspondente; `delivered` continua sendo null, o que não significa que a outra parte recebeu. unknown indica que o resultado não está claro; verifique o histórico e não envie novamente com uma nova chave. A instância não reenviará automaticamente tarefas interrompidas. + +O histórico contém apenas o conteúdo já sincronizado pelo cliente e não pode garantir todo o histórico. Mensagens não textuais podem retornar o tipo unknown, e o download de anexos ainda não está disponível. Os eventos retêm as 10.000 entradas mais recentes; `gap` indica que o cursor ultrapassou a janela de retenção. A primeira conexão não reproduzirá o histórico antigo como novas mensagens. + +`server_accepted` e `server_id` no histórico de mensagens podem ser usados para verificar se o servidor aceitou a mensagem local; quando houver apenas um registro local sem ID do servidor, o envio não pode ser considerado bem-sucedido. Esses campos não indicam que o destinatário recebeu ou leu. Os registros de eventos preservam o estado no momento da geração; para consultar o estado de confirmação atual, use a interface de histórico de mensagens. + +## Conta e credenciais + +Faça login apenas em contas que você tenha autorização para operar. Configure o token da API em aplicações confiáveis; ele pode acessar os dados da conta dessa instância. Não publique senhas, códigos QR ou capturas de tela de conversas em locais públicos. Pausar a instância interromperá os eventos em tempo real. Após sair da conta ou remover o dispositivo no celular, será necessário fazer login novamente. + +A entrada de texto atual suporta apenas uma única linha; quebras de linha serão explicitamente recusadas antes do envio. Quando o cliente exigir verificação de segurança ou novo login, o próprio titular da conta deverá concluí-los na área de trabalho remota; a instância não contornará a verificação. Tarefas após uma interrupção de verificação podem retornar unknown; consulte primeiro os registros de mensagens e não reenvie com uma nova chave de idempotência. + +Ao detectar um aviso de verificação de segurança, saída ou alteração da conta, a fila de automação será pausada de forma persistente. Após concluir a verificação no celular, é possível continuar as tarefas ainda não executadas por meio de “Retomar após verificação” no console da instância; tarefas já enviadas, mas com resultado incerto, não serão reenviadas. O trabalho remoto normal também pode acionar a verificação de segurança do WeCom. A janela de 24 horas sem novo bloqueio após a verificação, informada oficialmente, não significa que a detecção foi eliminada, nem significa que a instância pode garantir operação não supervisionada de longo prazo. diff --git a/ru/guides/claude/claude_messages.mdx b/ru/guides/claude/claude_messages.mdx index 6a9e8fd89..bed8f2e8a 100644 --- a/ru/guides/claude/claude_messages.mdx +++ b/ru/guides/claude/claude_messages.mdx @@ -1,43 +1,44 @@ --- -title: "Получение доступа и использование Claude Messages API" +title: "Получение и использование Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude — это очень мощная система ИИ-диалогов: достаточно ввести промпт, и она сможет за считанные секунды сгенерировать плавный и естественный ответ. Claude Messages API — это официальный нативный формат API от Anthropic. В отличие от формата, совместимого с OpenAI (Chat Completion), он использует собственную структуру запросов и ответов Anthropic, что позволяет лучше использовать уникальные возможности Claude, такие как мультимодальный ввод контента, вызов инструментов, глубокое мышление (Extended Thinking) и другие расширенные функции. +Anthropic Claude — это очень мощная система диалогов с ИИ: достаточно ввести промпт, и она сможет за несколько секунд сгенерировать плавный и естественный ответ. Claude Messages API — это официальный нативный формат API Anthropic, который отличается от формата, совместимого с OpenAI (Chat Completion). Он использует собственные структуры запросов и ответов Anthropic, что позволяет лучше использовать уникальные возможности Claude, такие как мультимодальный ввод контента, вызов инструментов, глубокое мышление (Extended Thinking) и другие расширенные функции. -Этот документ главным образом описывает процесс использования операций Claude Messages API. С его помощью мы можем использовать нативный интерфейс, соответствующий официальному Anthropic, для вызова диалоговых возможностей Claude. +В этом документе в основном описывается процесс использования операций Claude Messages API. С его помощью мы можем использовать нативный интерфейс, соответствующий официальному Anthropic, для вызова диалоговых функций Claude. -## Процесс получения доступа +## Процесс получения -Чтобы использовать Claude Messages API, сначала перейдите в [консоль Ace Data Cloud](https://platform.acedata.cloud/console/applications), чтобы получить ваш API Token и сохранить его для дальнейшего использования. +Чтобы использовать Claude Messages API, сначала получите ваш API Token в [консоли Ace Data Cloud](https://platform.acedata.cloud/console/applications) и сохраните его для дальнейшего использования. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти в систему; после завершения вы автоматически вернётесь на текущую страницу. +Если вы ещё не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти; после завершения вы автоматически вернётесь на текущую страницу. -**Один API Token позволяет вызывать все сервисы платформы, нет необходимости подавать отдельную заявку для каждого сервиса.** При первом получении предоставляется бесплатный лимит, позволяющий бесплатно ознакомиться с сервисом; если лимита недостаточно, вы можете пополнить универсальный баланс в [консоли](https://platform.acedata.cloud/console/coin). +**Один API Token позволяет вызывать все сервисы платформы, не требуется подавать отдельную заявку для каждого сервиса.** При первом получении предоставляется бесплатный лимит, позволяющий бесплатно попробовать сервис; при недостатке лимита можно пополнить универсальный баланс в [консоли](https://platform.acedata.cloud/console/coin). > 📘 Полная документация: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Базовое использование -Путь запроса Claude Messages API — `/v1/messages`, он соответствует официальному API Anthropic. Нам необходимо предоставить как минимум три обязательных параметра: +Путь запроса Claude Messages API — `/v1/messages`, что соответствует официальному API Anthropic. Необходимо предоставить как минимум три обязательных параметра: -- `model`: выбор используемой модели Claude. `claude-opus-5-5` предоставляется только через Messages API, поддерживает контекст в 1 миллион Token, максимальный вывод в 128K Token и всегда включает адаптивное мышление. Новейшая флагманская модель — `claude-fable-5-1` (контекст в 1 миллион Token, максимальный вывод в 128K Token); прежняя `claude-fable-5` по-прежнему сохранена для совместимости. `claude-sonnet-5-5` добавлена в серию нативных интерфейсов Messages, поддерживает ввод изображений и адаптивное мышление; её официальные справочные цены на ввод, вывод и чтение из кэша составляют соответственно 2, 10 и 0,20 доллара США за миллион Token. +- `model`: выбор используемой модели Claude. `claude-opus-5-5` предоставляется только через Messages API, поддерживает контекст в 1 миллион Token, максимальный вывод 128K Token и всегда включает адаптивное мышление. Новейшей флагманской моделью является `claude-fable-5-1` (контекст в 1 миллион Token, максимальный вывод 128K Token); прежняя `claude-fable-5` всё ещё сохранена для совместимости. `claude-sonnet-5-5` добавлена в серию нативных интерфейсов Messages, поддерживает ввод изображений и адаптивное мышление; её официальные справочные цены на ввод, вывод и чтение из кэша составляют соответственно 2, 10 и 0,20 доллара США за миллион Token. - `messages`: массив входных сообщений, каждое сообщение содержит `role` (роль) и `content` (содержимое), при этом `role` поддерживает `user` и `assistant`. - `max_tokens`: максимальное количество выходных token, используемое для ограничения длины одного ответа. -Распространённые необязательные параметры: +Часто используемые необязательные параметры: -- `system`: системный промпт, используемый для настройки поведения и роли модели. -- `temperature`: случайность генерации, от 0 до 1; чем больше значение, тем более вариативным будет ответ. -- `stream`: использовать ли потоковый ответ; установите `true`, чтобы реализовать эффект посимвольного возврата. -- `stop_sequences`: пользовательские последовательности остановки; модель прекращает генерацию при встрече с этим текстом. -- `top_p`: параметр ядерной выборки, совместно с temperature контролирует случайность генерации. +- `system`: системный промпт, используемый для задания поведения и роли модели. +- `temperature`: случайность генерации, от 0 до 1; чем больше значение, тем более разнообразным будет ответ. +- `stream`: использовать ли потоковый ответ; установка значения `true` позволяет реализовать эффект посимвольного возврата. +- `stop_sequences`: пользовательские последовательности остановки; модель прекратит генерацию при встрече с этим текстом. +- `top_p`: параметр ядерной выборки, совместно с temperature управляющий случайностью генерации. - `top_k`: выборка только из K вариантов с наивысшей вероятностью. -- `tools`: определения инструментов, используемые для вызова моделью внешних функций. +- `tools`: определения инструментов, используемые для того, чтобы модель вызывала внешние функции. - `tool_choice`: управление тем, как модель использует предоставленные инструменты. -- `cache_control`: автоматически создаёт контрольную точку кэша на последнем кэшируемом блоке содержимого запроса; также может быть указан в конкретном блоке содержимого. +- `cache_control`: автоматически создаёт точку остановки кэша на последнем кэшируемом блоке содержимого запроса; также может быть записан на конкретном блоке содержимого. +- `metadata`: необязательный объект метаданных запроса. `metadata.user_id` является строкой и может передавать пользовательский идентификатор пользователя, определённый вызывающей стороной, например `{"user_id":"example-user-001"}`; рекомендуется использовать стабильный идентификатор, не содержащий персональной информации. Он не заменяет аутентификацию `Authorization` и не требует записи в содержимое диалога `messages`. ### Пример cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -После вызова результат будет следующим: +После вызова результат возврата выглядит следующим образом: ```json { @@ -106,25 +109,25 @@ print(response.json()) } ``` -Описание полей результата: - -- `id`: уникальный идентификатор данного сообщения. -- `type`: всегда `message`. -- `role`: всегда `assistant`. -- `content`: массив содержимого ответа, каждый элемент содержит `type` (например, `text`) и соответствующее содержимое. -- `model`: название модели, обработавшей запрос. -- `stop_reason`: причина остановки. Стабильные значения включают `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (можно передать текущее содержимое assistant без изменений, чтобы продолжить), `refusal` и `model_context_window_exceeded`. -- `stop_sequence`: если остановка произошла из-за пользовательской последовательности остановки, отображается текст совпавшей последовательности остановки. -- `stop_details`: когда `stop_reason` имеет значение `refusal`, может содержать категорию отказа и пояснение. -- `usage`: статистика использования token. `input_tokens` — это некэшированный ввод; `cache_creation_input_tokens` и `cache_read_input_tokens` — соответственно запись в кэш и чтение из кэша; `output_tokens` — общее количество выходных token. Если возвращается `output_tokens_details.thinking_tokens`, это значение является подмножеством `output_tokens`; при расчёте общего количества или стоимости не добавляйте его повторно. При отсутствии достоверного подсчёта эта детализация может быть `null` или отсутствовать. -- `usage.cache_creation`: необязательная детализация TTL записи в кэш, содержащая `ephemeral_5m_input_tokens` и `ephemeral_1h_input_tokens`. Когда объект существует, сумма этих двух значений равна `cache_creation_input_tokens`; значение поля `null` или отсутствие означает, что в текущем ответе нет доступной разбивки по TTL, и это нельзя интерпретировать как `0`. -- `usage.cost`: непотоковый ответ может содержать объект расхода лимита, записанный Ace Data Cloud, где `amount` — фактический расход в этом вызове, `currency` — единица измерения, а `list_amount` — сумма до скидки (при наличии). Официальная базовая цена чтения из кэша для Fable 5.1 составляет $0.25/миллион Token, а базовые цены записи в кэш на 5 минут и 1 час составляют $12.50 и $20/миллион Token соответственно; фактическая цена платформы рассчитывается согласно скидке тарифа. +Описание полей результата возврата: +- `id`：Уникальный идентификатор текущего сообщения. +- `type`：Всегда `message`. +- `role`：Всегда `assistant`. +- `content`：Массив содержимого ответа, каждый элемент содержит `type` (например, `text`) и соответствующее содержимое. +- `model`：Название модели, обрабатывающей запрос. +- `stop_reason`：Причина остановки. Стабильные значения включают `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (можно вернуть текущее содержимое assistant без изменений для продолжения), `refusal` и `model_context_window_exceeded`. +- `stop_sequence`：Если остановка произошла из-за пользовательской последовательности остановки, отображается текст совпавшей последовательности остановки. +- `stop_details`：Когда `stop_reason` имеет значение `refusal`, может содержать категорию отказа и описание. +- `usage`：Статистика использования token. `input_tokens` — некэшированный ввод; `cache_creation_input_tokens` и `cache_read_input_tokens` соответственно означают запись в кэш и чтение из него; `output_tokens` — общее число выходных token. Если возвращается `output_tokens_details.thinking_tokens`, это значение является подмножеством `output_tokens`; не добавляйте его повторно при подсчёте общего количества или стоимости. При отсутствии авторитетного подсчёта эта детализация может иметь значение `null` или быть опущена. +- `usage.cache_creation`：Необязательная детализация TTL записи в кэш, содержащая `ephemeral_5m_input_tokens` и `ephemeral_1h_input_tokens`. Если объект присутствует, сумма двух значений равна `cache_creation_input_tokens`; если поле имеет значение `null` или опущено, это означает, что для текущего ответа недоступно разбиение по TTL, и его нельзя интерпретировать как `0`. +- `usage.cost`：Непотоковые ответы могут содержать объект потребления квоты, записанный Ace Data Cloud, где `amount` — фактическое потребление за текущий раз, `currency` — единица измерения, а `list_amount` — сумма до скидки (если есть). Официальная базовая цена чтения из кэша для Fable 5.1 составляет $0.25/миллион Token, а базовые цены записи в кэш на 5 минут и 1 час составляют $12.50 и $20/миллион Token соответственно; фактическая цена платформы рассчитывается с учётом скидки тарифа. ## Системный промпт Claude Messages API поддерживает настройку системного промпта через поле `system`, используемое для определения поведения, роли и контекста модели. ### Пример Python + ```python import requests @@ -149,11 +152,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Установив системный промпт `system`, можно точно контролировать роль и поведение Claude. +Настроив промпт `system`, можно точно контролировать роль Claude и способ его поведения. ## Потоковые ответы -Этот интерфейс также поддерживает потоковые ответы: установите параметр `stream` в значение `true`, чтобы получать результат поэтапно, что особенно подходит для реализации посимвольного отображения на веб-страницах. +Этот интерфейс также поддерживает потоковые ответы: установите параметр `stream` в `true`, чтобы получить эффект постепенного возврата, что особенно подходит для реализации посимвольного отображения на веб-страницах. ### Пример Python @@ -183,16 +186,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Потоковые ответы возвращаются в формате Server-Sent Events (SSE), каждая строка имеет префикс `event:` и `data:`. Типы потоковых событий включают: +Потоковые ответы возвращаются в формате Server-Sent Events (SSE), каждая строка начинается с префиксов `event:` и `data:`. Типы потоковых событий включают: -- `message_start`: начало сообщения, содержит основную информацию о сообщении и название модели. -- `content_block_start`: начало блока содержимого. -- `content_block_delta`: инкрементальное обновление блока содержимого, содержит вновь сгенерированный фрагмент текста. -- `content_block_stop`: конец блока содержимого. -- `message_delta`: инкрементальное обновление на уровне сообщения, содержит `stop_reason` и итоговую информацию `usage`. Авторитетное значение `output_tokens_details.thinking_tokens` следует считывать только из последнего `message_delta.usage`, не суммируйте его по событиям. -- `message_stop`: конец сообщения. +- `message_start`：Начало сообщения, содержит основную информацию о сообщении и название модели. +- `content_block_start`：Начало блока содержимого. +- `content_block_delta`：Инкрементальное обновление блока содержимого, содержит вновь сгенерированный фрагмент текста. +- `content_block_stop`：Конец блока содержимого. +- `message_delta`：Инкрементальное обновление на уровне сообщения, содержит `stop_reason` и окончательную информацию `usage`. Авторитетное значение `output_tokens_details.thinking_tokens` следует считывать только из последнего `message_delta.usage`; не суммируйте его между событиями. +- `message_stop`：Конец сообщения. -Результат вывода выглядит следующим образом: +Эффект вывода выглядит следующим образом: ``` event: message_start @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Как видно, событие `content_block_delta` в потоковом ответе содержит постепенно генерируемый текст, и, объединив все `text_delta`, можно получить полный ответ. +Как видно, в потоковом ответе событие `content_block_delta` содержит постепенно генерируемое текстовое содержимое; полный ответ можно получить, объединив все `text_delta`. ### Пример JavaScript @@ -253,7 +256,7 @@ while (true) { ## Многораундовый диалог -Если вы хотите подключить функцию многораундового диалога, необходимо поочерёдно разместить сообщения с ролями `user` и `assistant` в массиве `messages`, передав вместе с ними предыдущую историю диалога. +Если вы хотите подключить функцию многораундового диалога, необходимо поочерёдно размещать сообщения с ролями `user` и `assistant` в массиве `messages`, одновременно передавая всю предыдущую историю диалога. ### Пример Python @@ -283,7 +286,6 @@ print(response.json()) ``` Результат возврата выглядит следующим образом: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -309,9 +311,9 @@ print(response.json()) ## Модели глубокого мышления -Thinking и thinking summary Claude — это два разных понятия: модель может выполнять внутренние рассуждения, но API не возвращает исходную цепочку мыслей. Когда необходимо показать процесс рассуждения, API возвращает обработанное резюме. +thinking и thinking summary в Claude — это два разных понятия: модель может выполнять внутренние рассуждения, но API не возвращает исходную цепочку мыслей. Когда необходимо показать процесс рассуждения, API возвращает обработанное резюме. -Для текущих моделей рекомендуется использовать adaptive thinking и управлять общими затратами на рассуждения через `output_config.effort`: +Для текущих моделей рекомендуется использовать adaptive thinking и управлять общими затратами на рассуждение через `output_config.effort`: ```python import requests @@ -350,24 +352,25 @@ print(response.json()) "signature": "opaque-signature" } ``` -- `display: "summarized"` возвращает читаемое резюме размышлений; это не исходная цепочка рассуждений. -- `display: "omitted"` возвращает `thinking: ""`, но по-прежнему сохраняет opaque `signature` для поддержки последующих диалогов. -- `display: "updates"` — это beta-режим Anthropic, требующий передачи `anthropic-beta: thinking-display-updates-2026-08-18`. Официальное определение — скрывать основной текст рассуждений и показывать краткие обновления о ходе выполнения между вызовами инструментов. Платформа передаёт этот параметр и beta-заголовок запроса в исходном виде и не принудительно переписывает его в `summarized`; фактическое содержимое вывода зависит от поддержки выбранной модели. -- `thinking`, `output_config`, effort, параметры сэмплирования и новые расширенные поля передаются в исходном виде. Платформа не поддерживает жёстко закодированные по моделям перечисления значений и ограничения сочетаний, а также не переписывает автоматически режим thinking; принимать ли эти параметры, определяет выбранная модель, а возвращаемые моделью ошибки параметров передаются обратно клиенту. -- Значение display по умолчанию для Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 и Opus 4.7 — `omitted`; Opus 4.6, Sonnet 4.6 и более ранние модели с поддержкой thinking по умолчанию используют `summarized`. -- Display влияет только на возвращаемое содержимое и задержку потоковой передачи, не отключает рассуждения и не уменьшает тарификацию thinking token. -- Вопросы о том, включён ли thinking по умолчанию, и о значении display по умолчанию — это два независимых вопроса. Opus 5 и Sonnet 5 по умолчанию включают adaptive thinking; для Opus 5 пропуск `thinking` эквивалентен adaptive, а пропуск `output_config.effort` эквивалентен `high`. Opus 4.8, 4.7 и 4.6 требуют явного включения. -- Thinking и итоговый основной текст совместно занимают выходной бюджет `max_tokens`. При слишком малом бюджете thinking может занять большую часть лимита, из-за чего основной текст будет пустым или обрезанным; увеличьте `max_tokens` или используйте effort `low` / `medium` для контроля затрат на рассуждения. -- Для моделей, допускающих отключение thinking, можно передать `thinking: {"type":"disabled"}`. Новые режимы, такие как `between_tools`, а также сочетания effort зависят от выбранной модели; платформа не отклоняет их заранее на основании старых правил по моделям. -- Фиксированный бюджет размышлений может передаваться через `budget_tokens`; новые модели обычно используют `thinking.type=adaptive` и `output_config.effort`. Поддерживаются ли фиксированный бюджет или отключение размышлений, зависит от текущих возможностей выбранной модели. -- При многоходовых диалогах и вызовах инструментов следует передавать обратно в исходном виде полный блок thinking и signature, возвращённые assistant; не изменяйте и не создавайте signature самостоятельно. -- Сквозная передача параметров не означает, что каждая модель поддерживает все функции. Вызовы между протоколами по-прежнему требуют преобразования, а область поддержки и ошибки для содержимого вроде `redacted_thinking` определяются сервисом модели, фактически обрабатывающим запрос. + +- `display: "summarized"` возвращает читаемое резюме размышлений; это не исходная цепочка мыслей. +- `display: "omitted"` возвращает `thinking: ""`, но при этом сохраняет непрозрачную `signature` для поддержки последующих диалогов. +- `display: "updates"` — это beta-режим Anthropic, для которого необходимо передать `anthropic-beta: thinking-display-updates-2026-08-18`. Официальное определение: скрывает текст рассуждений и показывает краткие обновления прогресса между вызовами инструментов. Платформа передаёт этот параметр и beta-заголовок запроса без изменений и не принудительно преобразует его в `summarized`; фактическое содержимое вывода зависит от поддержки выбранной модели. +- `thinking`, `output_config`, effort, параметры семплирования и новые расширенные поля передаются без изменений. Платформа не поддерживает жёстко закодированные по моделям перечисления допустимых значений или ограничения комбинаций и не изменяет автоматически режим thinking; решение о принятии этих параметров принимает выбранная модель, а ошибки параметров, возвращаемые моделью, передаются клиенту. +- Значение display по умолчанию для Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 и Opus 4.7 — `omitted`; для Opus 4.6, Sonnet 4.6 и более ранних моделей с поддержкой thinking по умолчанию используется `summarized`. +- Display влияет только на возвращаемое содержимое и задержку потоковой передачи, но не отключает рассуждения и не уменьшает тарификацию thinking token. +- Вопрос о том, включён ли thinking по умолчанию, и вопрос о значении display по умолчанию — это два независимых вопроса. Opus 5 и Sonnet 5 по умолчанию включают adaptive thinking; для Opus 5 отсутствие `thinking` эквивалентно adaptive, а отсутствие `output_config.effort` эквивалентно `high`. Для Opus 4.8, 4.7 и 4.6 требуется явное включение. +- Thinking и итоговый текст совместно используют выходной бюджет `max_tokens`. При слишком малом бюджете thinking может занять большую часть лимита, из-за чего основной текст будет пустым или обрезанным; увеличьте `max_tokens` или используйте effort `low` / `medium` для управления затратами на рассуждение. +- Для моделей, допускающих отключение thinking, можно передать `thinking: {"type":"disabled"}`. Новые режимы, такие как `between_tools`, а также комбинации effort зависят от выбранной модели; платформа не отклоняет их заранее на основании старых правил для моделей. +- Фиксированный бюджет рассуждений можно передать через `budget_tokens`; новые модели обычно используют `thinking.type=adaptive` и `output_config.effort`. Поддержка фиксированного бюджета или отключения thinking определяется текущими возможностями выбранной модели. +- В многоходовых диалогах и при вызовах инструментов необходимо передавать обратно полный блок thinking и signature, возвращённые assistant, без изменений; не изменяйте и не создавайте signature самостоятельно. +- Прозрачная передача параметров не означает, что каждая модель поддерживает все функции. При межпротокольных вызовах всё равно требуется преобразование, а область поддержки и ошибки для такого содержимого, как `redacted_thinking`, определяются сервисом модели, фактически обрабатывающим запрос. В потоковых запросах `summarized` создаёт `thinking_delta`; `omitted` не создаёт `thinking_delta`, сохраняя только жизненный цикл блока thinking и `signature_delta`. ## Визуальные модели -Claude поддерживает мультимодальный ввод и может одновременно обрабатывать текст и изображения. В Messages API визуальные возможности можно использовать, задав `content` в формате массива и передав блок содержимого изображения. +Claude поддерживает мультимодальный ввод и может одновременно обрабатывать текст и изображения. В Messages API визуальные возможности можно использовать, установив `content` в формат массива и передав блок содержимого изображения. ### Использование изображений в кодировке Base64 @@ -415,7 +418,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### Использование изображения по URL +### Использование URL-изображений ```python import requests @@ -456,7 +459,6 @@ print(response.json()) ``` ### Пример cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -490,7 +492,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ ## Документы и PDF -PDF использует блок содержимого `document`, поддерживающий два стабильных источника: Base64 и URL. Источник Base64 обязательно должен использовать `application/pdf`: +PDF использует блок содержимого `document` и поддерживает два стабильных источника: Base64 и URL. Источник Base64 должен использовать `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -Источник URL записывается как `{"type":"url","url":"https://example.com/report.pdf"}`. `document` также поддерживает `text/plain` и источник `content`, состоящий из блоков text/image; необязательные поля включают `title`, `context` и `citations`. Источник `file_id` в Files API является отдельной beta-функцией и не входит в стабильный контракт этого интерфейса. +Источник URL записывается как `{"type":"url","url":"https://example.com/report.pdf"}`. `document` также поддерживает `text/plain` и источник `content`, состоящий из блоков text/image; необязательные поля включают `title`, `context` и `citations`. Источник `file_id` Files API относится к отдельной beta-функции и не входит в стабильный контракт этого интерфейса. -## Кэширование подсказок +## Кэширование промптов -Верхнеуровневый `cache_control` автоматически размещает точку разрыва кэша на последнем кэшируемом блоке: +`cache_control` верхнего уровня автоматически размещает точку остановки кэша на последнем кэшируемом блоке: ```python payload = { @@ -534,9 +536,10 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Когда требуется точно контролировать позицию, тот же `cache_control` также можно записывать на блоках содержимого text, image, document, tool_use, tool_result или определениях инструментов. `ttl` поддерживает `5m` (по умолчанию) и `1h`; определяйте запись в кэш и попадание в кэш через `usage.cache_creation_input_tokens` и `usage.cache_read_input_tokens`. -Когда ответ предоставляет `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Если `cache_creation` имеет значение `null` или отсутствует, это означает, что есть только общий объём записи в кэш и нет авторитетного разделения по TTL; в таком случае не считайте ни один bucket известным как 0, а для тарификации и общего объёма по-прежнему используйте aggregate-поля. +Когда требуется точно контролировать расположение, такой же `cache_control` также можно записать в блоки содержимого text, image, document, tool_use, tool_result или в определение инструмента. `ttl` поддерживает `5m` (по умолчанию) и `1h`; используйте `usage.cache_creation_input_tokens` и `usage.cache_read_input_tokens` для определения записи в кэш и попадания в кэш. + +Когда ответ предоставляет `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Если `cache_creation` имеет значение `null` или опущен, это означает, что есть только общий объём записи в кэш без авторитетного разделения по TTL; в этом случае не считайте ни один bucket известным как 0, а для расчёта стоимости и общего объёма по-прежнему используйте aggregate-поля. Пример возвращаемого результата: @@ -563,7 +566,7 @@ payload = { ## Вызов инструментов (Tool Use) -Claude Messages API нативно поддерживает функцию вызова инструментов, позволяя модели при необходимости вызывать заранее определённые вами инструменты/функции. +Claude Messages API нативно поддерживает функцию вызова инструментов, позволяя модели при необходимости вызывать предварительно определённые вами инструменты/функции. ### Пример Python @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Когда модель решает вызвать инструмент, в возвращаемом результате `content` будет содержать блок содержимого типа `tool_use`: +Когда модель решает вызвать инструмент, `content` в возвращаемом результате будет содержать блок содержимого типа `tool_use`: ```json { @@ -637,7 +640,7 @@ print(response.json()) } ``` -Обратите внимание, что `stop_reason` имеет значение `tool_use`, что означает необходимость вызова инструмента моделью. Получив этот результат, вам нужно выполнить функцию инструмента и вернуть результат модели в форме `tool_result`: +Обратите внимание, что `stop_reason` равен `tool_use`, что означает необходимость вызова инструмента моделью. После получения этого результата вам нужно выполнить функцию инструмента и вернуть результат модели в форме `tool_result`: ```python payload = { @@ -685,39 +688,38 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Модель на основе результата, возвращённого инструментом, сгенерирует итоговый ответ на естественном языке. +Модель на основе результата, возвращённого инструментом, сгенерирует окончательный ответ на естественном языке. ## Отличия от Chat Completion API Ace Data Cloud одновременно предоставляет два формата Claude API, основные различия между ними следующие: -`usage.input_tokens` в Messages API означает только некэшированный ввод, а `cache_read_input_tokens` и `cache_creation_input_tokens` являются независимыми тарифицируемыми bucket; все три рассчитываются отдельно по соответствующим ценам. - +`usage.input_tokens` Messages API обозначает только некэшированный ввод, а `cache_read_input_tokens` и `cache_creation_input_tokens` являются отдельными тарифицируемыми bucket; все три рассчитываются отдельно по соответствующим ценам. | Характеристика | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Формат | Нативный формат Anthropic | Совместимый с OpenAI формат | | Системный промпт | Отдельное поле `system` | Передаётся через `role: "system"` в `messages` | | Структура ответа | Массив `content` (поддерживает несколько типов) | Массив `choices` (содержит `message`) | -| Потоковый формат | SSE-события (несколько типов событий) | SSE-строки `data` | +| Формат потоковой передачи | SSE-события (несколько типов событий) | SSE-строки `data` | | Глубокое мышление | Нативные `thinking` и `output_config.effort` | Стратегия модели по умолчанию и совместимые параметры | | Вызов инструментов | Нативные `tools` + `input_schema` | Совместимый с OpenAI формат `tools` | | Статистика Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Если ваша система уже интегрирована с API формата OpenAI, можно использовать Chat Completion API для бесшовного переключения. Если вам необходимо использовать все нативные возможности Claude, рекомендуется использовать Messages API. +Если ваша система уже интегрирована с API формата OpenAI, вы можете использовать Chat Completion API для бесшовного переключения. Если вам необходимо использовать все нативные возможности Claude, рекомендуется использовать Messages API. ## Обработка ошибок -Ответы об ошибках публичного интерфейса используют envelope платформы Ace Data Cloud: `error.code` — стабильный код ошибки, `error.message` — описание, а `trace_id` используется для диагностики запроса. Распространённые HTTP-статусы включают: +Ответы с ошибками публичного интерфейса используют envelope платформы Ace Data Cloud: `error.code` — стабильный код ошибки, `error.message` — описание, а `trace_id` используется для диагностики запроса. Распространённые HTTP-статусы включают: -- `400`: недопустимы параметры запроса или содержимое протокола. +- `400`: параметры запроса или содержимое протокола недействительны. - `401`: токен авторизации недействителен, отсутствует или истёк. -- `403`: доступ запрещён, недостаточный баланс или ограниченная квота. +- `403`: доступ запрещён, недостаточно средств или ограничена квота. - `404`: API или модель не существуют. - `413`: тело запроса слишком велико. - `429`: слишком много запросов. - `500` / `503` / `504`: ошибка сервиса, временная недоступность или тайм-аут обработки. -### Пример ответа об ошибке +### Пример ответа с ошибкой ```json { @@ -729,7 +731,8 @@ Ace Data Cloud одновременно предоставляет два фор } ``` -Эта структура ошибок является контрактом времени выполнения Ace Data Cloud и не эквивалентна официальному error envelope Anthropic; обрабатывайте её согласно HTTP-статусу и `error.code`. +Эта структура ошибки является контрактом времени выполнения Ace Data Cloud и не равнозначна официальному envelope ошибок Anthropic; обрабатывайте её по HTTP-статусу и `error.code`. ## Заключение -Благодаря этому документу вы уже узнали, как использовать Claude Messages API для вызова диалоговых функций Claude в нативном формате Anthropic. Messages API поддерживает богатые функции, такие как базовый диалог, системные промпты, потоковые ответы, многораундовые диалоги, глубокое мышление, визуальное понимание, PDF, кэширование промптов и вызов инструментов. Если у вас возникнут какие-либо вопросы, пожалуйста, в любое время свяжитесь с нашей командой технической поддержки. + +С помощью этого документа вы уже узнали, как использовать Claude Messages API для вызова диалоговых функций Claude в нативном формате Anthropic. Messages API поддерживает богатые функции, такие как базовый диалог, системные промпты, потоковые ответы, многораундовые диалоги, глубокое мышление, визуальное понимание, PDF, кэширование промптов и вызов инструментов. Если у вас возникнут какие-либо вопросы, пожалуйста, в любое время свяжитесь с нашей командой технической поддержки. diff --git a/ru/guides/openai/openai_embeddings.mdx b/ru/guides/openai/openai_embeddings.mdx index 5c7ef1bf9..35a7140e7 100644 --- a/ru/guides/openai/openai_embeddings.mdx +++ b/ru/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API Заявка и использование" +title: "Подключение и использование OpenAI Embeddings API" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI сервис векторных слов, предназначенный для генерации векторных результатов, представляющих входной текст. +Сервис векторных представлений OpenAI, используемый для генерации результатов векторных представлений входного текста. -Этот документ в основном описывает процесс использования OpenAI Embeddings API, с помощью которого мы можем создать векторные вложения, представляющие входной текст. +В этом документе в основном описывается процесс использования OpenAI Embeddings API, с помощью которого мы можем создавать векторы вложений, представляющие входной текст。。 -## Процесс заявки +## Процесс подключения -Чтобы использовать OpenAI Embeddings API, сначала перейдите в [консоль Ace Data Cloud](https://platform.acedata.cloud/console/applications) и получите ваш API Token для резервного копирования. +Чтобы использовать OpenAI Embeddings API, сначала перейдите в [консоль Ace Data Cloud](https://platform.acedata.cloud/console/applications), чтобы получить ваш API Token и сохранить его для дальнейшего использования. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти. После завершения вы будете автоматически возвращены на текущую страницу. +Если вы еще не вошли в систему или не зарегистрировались, вы будете автоматически перенаправлены на страницу входа, где вам будет предложено зарегистрироваться и войти в систему, после чего вы автоматически вернетесь на текущую страницу. -**Один API Token позволяет вызывать все сервисы платформы, не нужно отдельно запрашивать для каждого сервиса.** При первой заявке предоставляется бесплатный лимит, чтобы вы могли попробовать; если лимит исчерпан, вы можете пополнить общий баланс в [консоли](https://platform.acedata.cloud/console/coin). +**Одного API Token достаточно для вызова всех сервисов платформы, не требуется подавать отдельную заявку для каждого сервиса.** При первой заявке предоставляется бесплатная квота, позволяющая бесплатно ознакомиться с сервисом; при недостатке квоты вы можете пополнить универсальный баланс в [консоли](https://platform.acedata.cloud/console/coin). > 📘 Полная документация: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## Основное использование +## Базовое использование -Теперь вы можете заполнить соответствующие поля на интерфейсе, как показано на изображении: +Далее вы можете заполнить соответствующее содержимое в интерфейсе, как показано на рисунке:

-При первом использовании этого интерфейса нам необходимо заполнить как минимум три поля: одно из них — `authorization`, которое можно выбрать прямо из выпадающего списка. Другой параметр — `model`, `model` — это категория модели, которую мы выбираем для использования с сайта OpenAI, здесь у нас в основном есть 3 модели, подробности можно посмотреть в предоставленных моделях. Последний параметр — `input`, `input` — это текст, который мы хотим преобразовать в вектор слов. +При первом использовании данного интерфейса нам необходимо заполнить как минимум три поля: одно из них — `authorization`, его достаточно выбрать непосредственно в выпадающем списке. Другой параметр — `model`, `model` — это категория модели с официального сайта OpenAI, которую мы выбираем для использования; доступные в настоящее время модели: `text-embedding-3-small` и `text-embedding-3-large`. `text-embedding-ada-002` больше не предоставляется; если существующий векторный индекс использует эту старую модель, нельзя напрямую смешивать векторы новой модели, необходимо заново создать индекс. Последний параметр — `input`, `input` — это текст, который нам необходимо преобразовать в векторное представление. -Также вы можете заметить, что справа есть соответствующий код вызова, который вы можете скопировать и запустить, или просто нажать кнопку «Try» для тестирования. +В то же время вы можете заметить, что справа генерируется соответствующий код вызова; вы можете скопировать код и запустить его напрямую, а также можете непосредственно нажать кнопку «Try» для тестирования. -Дополнительные параметры: +Необязательные параметры: -- `dimensions`: обрезка размерности вектора, по умолчанию выводится полная размерность. -- `encoding_format`: формат возврата, можно выбрать `float` или `base64`. +- `dimensions`：обрезка размерности вектора, по умолчанию выводится полная размерность. +- `encoding_format`：формат возврата, доступны `float` или `base64`.

-Пример кода вызова на Python: +Пример кода вызова Python: ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -После вызова мы обнаруживаем, что возвращаемый результат выглядит следующим образом: +После вызова мы видим, что возвращаемый результат выглядит следующим образом: ```json { @@ -97,7 +97,7 @@ print(response.text) ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -107,23 +107,23 @@ print(response.text) Возвращаемый результат содержит несколько полей, описание которых приведено ниже: -- `model`, модель, использованная для преобразования текста в вектор слов. -- `usage`, информация о токенах, использованных для преобразования текста в вектор слов. -- `data`, результат преобразования текста в вектор слов. +- `model` — модель, использованная для преобразования данного текста в векторное представление. +- `usage` — информация о token, использованных для преобразования данного текста в векторное представление. +- `data` — результат векторного представления после преобразования текста. -Где `data` содержит конкретную информацию о векторе слов, соответствующем тексту, а `embedding` — это конкретный результат сгенерированного вектора слов. +Среди них `data` содержит конкретную информацию о векторном представлении, соответствующем тексту, а его `embedding` — конкретный сгенерированный результат векторного представления. ## Обработка ошибок При вызове API, если возникает ошибка, API возвращает соответствующий код ошибки и информацию. Например: -- `400 token_mismatched`: Неверный запрос, возможно, из-за отсутствующих или недействительных параметров. -- `400 api_not_implemented`: Неверный запрос, возможно, из-за отсутствующих или недействительных параметров. -- `401 invalid_token`: Неавторизован, недействительный или отсутствующий токен авторизации. -- `429 too_many_requests`: Слишком много запросов, вы превысили лимит частоты. -- `500 api_error`: Внутренняя ошибка сервера, что-то пошло не так на сервере. +- `400 token_mismatched`：Неверный запрос, возможно, из-за отсутствующих или недопустимых параметров. +- `400 api_not_implemented`：Неверный запрос, возможно, из-за отсутствующих или недопустимых параметров. +- `401 invalid_token`：Не авторизован, недопустимый или отсутствующий токен авторизации. +- `429 too_many_requests`：Слишком много запросов, вы превысили ограничение частоты запросов. +- `500 api_error`：Внутренняя ошибка сервера, на сервере что-то пошло не так. -### Пример ответа об ошибке +### Пример ответа с ошибкой ```json { @@ -138,4 +138,4 @@ print(response.text) ## Заключение -С помощью этого документа вы узнали, как легко использовать OpenAI Embeddings API для генерации векторов слов от официального OpenAI. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку. +С помощью этого документа вы уже узнали, как легко использовать функцию генерации векторных представлений официального OpenAI через OpenAI Embeddings API. Надеемся, что этот документ поможет вам лучше интегрировать и использовать данный API. Если у вас возникнут какие-либо вопросы, пожалуйста, свяжитесь с нашей командой технической поддержки в любое время. diff --git a/ru/guides/platform/wework_bot.mdx b/ru/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..10a6e65a5 --- /dev/null +++ b/ru/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "Корпоративный бот WeChat" +description: "Platform API guide - Ace Data Cloud" +--- + +Разверните собственный экземпляр аккаунта корпоративного WeChat, войдите в систему, отсканировав QR-код корпоративного WeChat на телефоне, и используйте REST API или MCP для чтения аккаунта, контактов, бесед и локально синхронизированных сообщений. Экземпляр соответствует обычному аккаунту корпоративного WeChat и не требует частного сервера или настройки домена корпоративной электронной почты. + +Сейчас Alpha. Чтение аккаунта прошло проверку в реальных беседах; отправка текстов от собственного имени и обратное чтение событий прошли реальную приёмку; операции с другими контактами, группами и восстановление новых экземпляров ещё требуют приёмки в среде развертывания. Отправка медиа, ответы с цитированием, реальные @, управление участниками групп и подтверждения доставки пока не открыты. Ориентируйтесь на возвращаемое экземпляром значение `/api/capabilities`. + +## Развертывание и вход + +В категории Deployment подключите сервис и выберите пакет длительности экземпляра. После развертывания откройте страницу управления и отсканируйте QR-код корпоративного WeChat с аккаунта владельца; если требуется подтверждение на телефоне или другие шаги входа, откройте удалённый рабочий стол и введите пароль рабочего стола этого экземпляра. Учётные данные API и пароль рабочего стола независимы. Данные входа сохраняются на диске экземпляра, при пересоздании контейнера диск сохраняется; удаление диска удалит локальную сессию. + +Каждый экземпляр оплачивается отдельно и работает в течение приобретённого срока. Вызовы REST / MCP не тарифицируются отдельно за сообщения, фактическая цена определяется страницей пакета. В настоящее время по умолчанию используется тариф по длительности для бота WeChat в качестве ориентира; перед окончательным открытием необходимо подтвердить ценообразование с учётом используемых ресурсов. + +## API и MCP + +Используйте адрес API экземпляра на странице управления, все интерфейсы аккаунта передают `Authorization: Bearer `. Эти пути относятся к выделенному экземпляру, а не к общему шлюзу API. Адрес MCP — это адрес экземпляра с добавлением `/mcp/`, используется тот же Bearer token. + +| Интерфейс | Назначение | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Готовность аккаунта и список возможностей | +| `GET /api/auth/qr` | PNG Base64 текущего QR-кода входа | +| `GET /api/account` | Текущий аккаунт | +| `GET /api/contacts?kind=all` | Внутренние коллеги и внешние контакты, можно указать internal / external | +| `GET /api/conversations` | Локальные беседы, исходные ID бесед сохраняются | +| `GET /api/messages` | Локально синхронизированные сообщения; параметры conversation_id、after_rowid、limit | +| `POST /api/search` | Поиск контактов, бесед и локальных текстов | +| `POST /api/messages` | Асинхронная задача отправки текста, необходимо указать Idempotency-Key | +| `POST /api/messages/send` | Тот же вход отправки, поддерживает одну или несколько целей | +| `GET /api/groups/{conversation_id}` | Локально синхронизированная информация о группе и участниках | +| `GET /api/tasks` | Последние задачи и результаты по каждой цели | +| `GET /api/tasks/{id}` | Запрос результата отправки | +| `POST /api/tasks/{id}/cancel` | Отмена ещё не начатой задачи | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Приостановить автоматизацию; возобновить после проверки владельца | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Состояние экземпляра и текущий экран, для обоих требуется авторизация | +| `GET /api/events?after=0` | События сообщений с восстанавливаемым курсором | +| `WS /ws` | Поток событий сообщений, Bearer-аутентификация | + +Тело отправки содержит `target`, `type: "text"` и `text`. `target` принимает ID беседы, ID контакта, ID корпоративного пользователя или уникальное полное имя; предпочтительно использовать ID; если отображаемое имя всё ещё не позволяет однозначно определить объект, экземпляр отклонит операцию и не будет угадывать объект. Для контакта без локальной беседы клиент сначала откроет беседу, а затем отправит сообщение после сверки фактического ID беседы. Заголовок запроса `Idempotency-Key` состоит из 8–128 букв, цифр или символов `_.:-`. Повторные запросы одной и той же операции должны использовать один и тот же ключ и одинаковое тело запроса. + +Замена `target` на массив `targets` позволяет последовательно отправлять сообщения 1–50 явно указанным целям. Оба параметра нельзя передавать одновременно. Для всех целей сначала выполняется разрешение идентичности, различные псевдонимы, указывающие на один и тот же объект, будут отклонены. После сбоя одной цели последующие отправки прекращаются, результат задачи по каждому элементу записывается как `succeeded`, `failed`, `unknown` или `not_attempted`; не считайте частичный успех полным успехом. Этот процесс также должен пройти реальную приёмку указанных контактов в среде развертывания. + +Задачи могут находиться в состояниях queued、running、submitting、succeeded、failed、unknown или cancelled. `succeeded` означает, что после отправки в записи соответствующей беседы был найден точный текст и серверный ID сообщения, `delivered` всё ещё равен null и не означает, что другая сторона получила сообщение. unknown означает, что результат неясен, проверьте историю и не повторяйте отправку с новым ключом. Экземпляр не будет автоматически повторно отправлять прерванные задачи. + +История содержит только то, что уже синхронизировано клиентом, и не может гарантировать всю историю. Нетекстовые сообщения могут возвращаться с типом unknown, загрузка вложений пока не открыта. События хранятся в количестве последних 10,000, `gap` означает, что курсор уже вышел за окно хранения. При первом подключении старая история не будет повторно воспроизводиться как новые сообщения. + +`server_accepted` и `server_id` в истории сообщений можно использовать для проверки того, принял ли сервер локальное сообщение; если присутствует только локальная запись без серверного ID, отправку нельзя считать успешной. Эти поля не означают, что получатель получил или прочитал сообщение. Записи событий сохраняют состояние на момент создания, для запроса текущего состояния подтверждения следует использовать интерфейс истории сообщений. + +## Аккаунт и учётные данные + +Входите только в аккаунты, которыми вы уполномочены управлять. Настройте API token в доверенных приложениях; он может получать доступ к данным аккаунта этого экземпляра. Не публикуйте пароли, QR-коды или скриншоты чатов в общедоступных местах. Приостановка экземпляра прервёт события в реальном времени. После выхода из аккаунта или удаления устройства на телефоне необходимо войти повторно. + +Текущий ввод текста поддерживает только одну строку, переносы строк будут явно отклонены перед отправкой. Если клиент требует проверку безопасности или повторный вход, владелец аккаунта должен завершить это на удалённом рабочем столе; экземпляр не будет обходить проверку. Задачи после прерывания проверки могут вернуть unknown, сначала запросите записи сообщений, не отправляйте повторно с новым ключом идемпотентности. + +После обнаружения подсказки о проверке безопасности, выхода из аккаунта или изменений очередь автоматизации будет приостановлена с сохранением состояния. После завершения проверки на телефоне можно через консоль экземпляра «Возобновить после проверки» продолжить ещё не выполненные задачи; уже отправленные, но с неопределённым результатом задачи не будут повторно отправлены. Обычная удалённая работа также может вызвать проверку безопасности корпоративного WeChat. Указанное в официальном описании окно в 24 часа без повторной блокировки после проверки не означает, что обнаружение уже устранено, и не означает, что экземпляр может гарантировать длительную работу без присмотра. diff --git a/sr/guides/claude/claude_messages.mdx b/sr/guides/claude/claude_messages.mdx index b088b65d0..0f9820a17 100644 --- a/sr/guides/claude/claude_messages.mdx +++ b/sr/guides/claude/claude_messages.mdx @@ -3,41 +3,42 @@ title: "Prijava i korišćenje Claude Messages API-ja" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude je veoma moćan AI sistem za razgovor, koji može da generiše tečne i prirodne odgovore za samo nekoliko sekundi nakon unosa prompta. Claude Messages API je zvanični izvorni API format kompanije Anthropic i razlikuje se od formata kompatibilnog sa OpenAI-jem (Chat Completion). Koristi sopstvenu Anthropic strukturu zahteva i odgovora, što omogućava bolje korišćenje jedinstvenih Claude mogućnosti, kao što su multimodalni unos sadržaja, pozivanje alata, duboko razmišljanje (Extended Thinking) i druge napredne funkcije. +Anthropic Claude je veoma moćan AI sistem za razgovor koji može da generiše tečne i prirodne odgovore za samo nekoliko sekundi nakon unosa prompta. Claude Messages API je zvanični izvorni API format kompanije Anthropic. Za razliku od formata kompatibilnog sa OpenAI-jem (Chat Completion), koristi sopstvenu strukturu zahteva i odgovora kompanije Anthropic, što omogućava bolje korišćenje jedinstvenih mogućnosti Claude-a, kao što su multimodalni unos sadržaja, pozivanje alata, dubinsko razmišljanje (Extended Thinking) i druge napredne funkcije. -Ovaj dokument uglavnom predstavlja proces korišćenja Claude Messages API operacija. Pomoću njega možemo da koristimo izvorni interfejs usklađen sa zvaničnim Anthropic-om za pozivanje Claude funkcije razgovora. +Ovaj dokument uglavnom predstavlja proces korišćenja Claude Messages API operacija. Pomoću njega možemo da koristimo izvorni interfejs usklađen sa zvaničnim Anthropic interfejsom za pozivanje Claude-ovih funkcija razgovora. ## Proces prijave -Da biste koristili Claude Messages API, najpre preuzmite svoj API Token u [Ace Data Cloud konzoli](https://platform.acedata.cloud/console/applications) i sačuvajte ga za kasnije. +Da biste koristili Claude Messages API, prvo preuzmite svoj API Token sa [Ace Data Cloud konzole](https://platform.acedata.cloud/console/applications) i sačuvajte ga za kasniju upotrebu. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Ako se još niste prijavili ili registrovali, automatski ćete biti preusmereni na stranicu za prijavu, koja će vas pozvati da se registrujete i prijavite; po završetku ćete se automatski vratiti na trenutnu stranicu. +Ako još niste prijavljeni ili registrovani, bićete automatski preusmereni na stranicu za prijavu, gde ćete biti pozvani da se registrujete i prijavite; nakon završetka automatski ćete se vratiti na trenutnu stranicu. -**Jedan API Token može da poziva sve usluge platforme, bez potrebe za posebnom prijavom za svaku uslugu.** Prva prijava donosi besplatan kredit za besplatno isprobavanje; kada kredit nije dovoljan, možete dopuniti opšte stanje u [konzoli](https://platform.acedata.cloud/console/coin). +**Jedan API Token može da poziva sve usluge platforme, bez potrebe da se posebno prijavljujete za svaku uslugu.** Prva prijava donosi besplatni kredit za besplatno isprobavanje; kada kredit nije dovoljan, možete dopuniti univerzalni saldo u [konzoli](https://platform.acedata.cloud/console/coin). > 📘 Kompletna dokumentacija: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) -## Osnovna upotreba +## Osnovno korišćenje -Putanja zahteva za Claude Messages API je `/v1/messages`, što je usklađeno sa zvaničnim Anthropic API-jem. Potrebno je da navedemo najmanje tri obavezna parametra: +Putanja zahteva za Claude Messages API je `/v1/messages`, što je u skladu sa zvaničnim Anthropic API-jem. Potrebno je da navedemo najmanje tri obavezna parametra: -- `model`: Odaberite Claude model koji će se koristiti. `claude-opus-5-5` je dostupan samo putem Messages API-ja, podržava kontekst od 1 milion Tokena, maksimalni izlaz od 128K Tokena i uvek uključuje adaptivno razmišljanje. Najnoviji vodeći model je `claude-fable-5-1` (kontekst od 1 milion Tokena, maksimalni izlaz od 128K Tokena); prethodni `claude-fable-5` je i dalje kompatibilan i zadržan. `claude-sonnet-5-5` je dodat u izvorni Messages serijski interfejs, podržava unos slika i adaptivno razmišljanje; njegove zvanične referentne cene za unos, izlaz i čitanje keša iznose 2, 10 i 0,20 USD po milionu Tokena. -- `messages`: Niz ulaznih poruka, gde svaka poruka sadrži `role` (ulogu) i `content` (sadržaj), pri čemu `role` podržava `user` i `assistant`. +- `model`: Izaberite Claude model koji želite da koristite. `claude-opus-5-5` je dostupan samo putem Messages API-ja, podržava kontekst od 1 milion Token-a, maksimalni izlaz od 128K Token-a i uvek ima uključeno adaptivno razmišljanje. Najnoviji vodeći model je `claude-fable-5-1` (kontekst od 1 milion Token-a, maksimalni izlaz od 128K Token-a); prethodni `claude-fable-5` je i dalje kompatibilno zadržan. `claude-sonnet-5-5` je dodat seriji izvornih Messages interfejsa, podržava unos slika i adaptivno razmišljanje; njegove zvanične referentne cene za ulaz, izlaz i čitanje keša iznose 2, 10 i 0,20 američkih dolara po milionu Token-a. +- `messages`: Niz ulaznih poruka, pri čemu svaka poruka sadrži `role` (ulogu) i `content` (sadržaj), a `role` podržava `user` i `assistant`. - `max_tokens`: Maksimalan broj izlaznih tokena, koji se koristi za ograničavanje dužine jednog odgovora. Često korišćeni opcioni parametri: -- `system`: Sistemski prompt, koji se koristi za postavljanje ponašanja i uloge modela. +- `system`: Sistemski prompt, koji se koristi za definisanje ponašanja i uloge modela. - `temperature`: Nasumičnost generisanja, između 0 i 1; što je vrednost veća, odgovor je divergentniji. -- `stream`: Da li se koristi striming odgovor; postavljanje na `true` može postići efekat vraćanja reč po reč. +- `stream`: Da li se koristi strimovani odgovor; podešavanje na `true` može da ostvari efekat vraćanja reč po reč. - `stop_sequences`: Prilagođene sekvence za zaustavljanje; model će prestati sa generisanjem kada naiđe na ove tekstove. -- `top_p`: Parametar uzorkovanja jezgra, koji zajedno sa temperature kontroliše nasumičnost generisanja. -- `top_k`: Uzorkovanje samo iz K opcija sa najvećom verovatnoćom. -- `tools`: Definicije alata, koje se koriste da bi model pozivao spoljne funkcije. -- `tool_choice`: Kontroliše način na koji model koristi ponuđene alate. -- `cache_control`: Automatski kreira tačku prekida keša na poslednjem kešabilnom bloku sadržaja u zahtevu; može se napisati i na konkretnom bloku sadržaja. +- `top_p`: Parametar nuklearnog uzorkovanja, koji zajedno sa temperature kontroliše nasumičnost generisanja. +- `top_k`: Uzorkuje samo iz K opcija sa najvećom verovatnoćom. +- `tools`: Definicije alata, koje se koriste kako bi model pozivao spoljne funkcije. +- `tool_choice`: Kontroliše kako model koristi ponuđene alate. +- `cache_control`: Automatski kreira tačku prekida keša na poslednjem bloku sadržaja koji se može keširati u zahtevu; može se zapisati i na konkretnom bloku sadržaja. +- `metadata`: Opcioni objekat metapodataka zahteva. `metadata.user_id` je string i može proslediti korisnički identifikator koji prilagođava pozivalac, na primer `{"user_id":"example-user-001"}`; preporučuje se korišćenje stabilnog identifikatora koji ne sadrži lične podatke. Ne zamenjuje `Authorization` autentifikaciju i ne mora se upisivati u sadržaj razgovora u `messages`. ### cURL primer @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Nakon poziva, rezultat odgovora je sledeći: +Nakon poziva, rezultat vraćanja je sledeći: ```json { @@ -106,25 +109,25 @@ Nakon poziva, rezultat odgovora je sledeći: } ``` -Objašnjenje polja rezultata odgovora: - +Objašnjenje polja rezultata vraćanja: - `id`: Jedinstveni identifikator ove poruke. - `type`: Uvek je `message`. - `role`: Uvek je `assistant`. -- `content`: Niz sadržaja odgovora, gde svaki element sadrži `type` (kao što je `text`) i odgovarajući sadržaj. +- `content`: Niz sadržaja odgovora, svaki element sadrži `type` (kao što je `text`) i odgovarajući sadržaj. - `model`: Naziv modela koji obrađuje zahtev. -- `stop_reason`: Razlog zaustavljanja. Stabilne vrednosti uključuju `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (možete vratiti trenutni assistant sadržaj neizmenjen da biste nastavili), `refusal` i `model_context_window_exceeded`. -- `stop_sequence`: Ako je zaustavljanje nastupilo zbog prilagođene sekvence za zaustavljanje, prikazuje se tekst odgovarajuće sekvence za zaustavljanje. -- `stop_details`: Kada je `stop_reason` `refusal`, može sadržati kategoriju odbijanja i objašnjenje. -- `usage`: Statistika korišćenja tokena. `input_tokens` je ulaz koji nije keširan; `cache_creation_input_tokens` i `cache_read_input_tokens` su redom upisivanje u keš i čitanje iz keša; `output_tokens` je ukupan broj izlaznih tokena. Ako se vrati `output_tokens_details.thinking_tokens`, ova vrednost je podskup `output_tokens`; nemojte je ponovo sabirati pri izračunavanju ukupne količine ili troškova. Ovaj detalj može biti `null` ili izostavljen kada nema autoritativnog brojanja. -- `usage.cache_creation`: Opcioni detalji TTL-a za upis u keš, koji uključuju `ephemeral_5m_input_tokens` i `ephemeral_1h_input_tokens`. Kada objekat postoji, zbir ove dve stavke jednak je `cache_creation_input_tokens`; polje koje je `null` ili izostavljeno znači da trenutni odgovor nema dostupnu TTL podelu i ne može se tumačiti kao `0`. -- `usage.cost`: Nestriming odgovor može sadržati objekat potrošnje kredita koji beleži Ace Data Cloud, gde je `amount` stvarna potrošnja ovog puta, `currency` je merna jedinica, a `list_amount` je iznos pre popusta (ako postoji). Zvanična osnovna cena čitanja Fable 5.1 keša je $0.25/milion Tokena, dok osnovne cene upisivanja u keš za 5 minuta i 1 sat iznose $12.50 i $20/milion Tokena; stvarne cene platforme se preračunavaju prema popustu paketa. +- `stop_reason`: Razlog zaustavljanja. Stabilne vrednosti uključuju `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (trenutni sadržaj assistant-a može se vratiti neizmenjen radi nastavka), `refusal` i `model_context_window_exceeded`. +- `stop_sequence`: Ako je zaustavljeno zbog prilagođene sekvence zaustavljanja, prikazuje tekst odgovarajuće sekvence zaustavljanja. +- `stop_details`: Kada je `stop_reason` `refusal`, može sadržati kategoriju i objašnjenje odbijanja. +- `usage`: Statistika korišćenja tokena. `input_tokens` su ulazni podaci koji nisu keširani; `cache_creation_input_tokens` i `cache_read_input_tokens` predstavljaju upis i čitanje keša; `output_tokens` je ukupan broj izlaznih tokena. Ako se vrati `output_tokens_details.thinking_tokens`, ta vrednost je podskup `output_tokens`; nemojte je ponovo sabirati prilikom izračunavanja ukupne količine ili troškova. Kada nema autoritativnog brojanja, ovaj detalj može biti `null` ili izostavljen. +- `usage.cache_creation`: Opcioni detalji TTL-a za upis u keš, koji sadrže `ephemeral_5m_input_tokens` i `ephemeral_1h_input_tokens`. Kada objekat postoji, zbir ove dve stavke jednak je `cache_creation_input_tokens`; ako su polja `null` ili izostavljena, to znači da trenutni odgovor nema dostupnu TTL podelu i ne može se tumačiti kao `0`. +- `usage.cost`: Neprotočni odgovori mogu sadržati objekat potrošnje kredita koji beleži Ace Data Cloud, gde je `amount` stvarno potrošen iznos za ovaj put, `currency` je merna jedinica, a `list_amount` je iznos pre popusta (ako postoji). Zvanična osnovna cena za čitanje keša za Fable 5.1 je $0.25/milion tokena, a osnovne cene upisa u keš od 5 minuta i 1 sata su $12.50 odnosno $20/milion tokena; stvarne cene platforme obračunavaju se prema popustu paketa. ## Sistemski prompt Claude Messages API podržava postavljanje sistemskog prompta putem polja `system`, koje se koristi za definisanje ponašanja, uloge i konteksta modela. ### Python primer + ```python import requests @@ -149,11 +152,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Podešavanjem `system` prompta možete precizno kontrolisati Claudeovu ulogu i način ponašanja. +Postavljanjem `system` prompta možete precizno kontrolisati Claude-ovu ulogu i način ponašanja. -## Strimovani odgovor +## Protočni odgovor -Ovaj interfejs takođe podržava strimovane odgovore; postavite parametar `stream` na `true` da biste dobili efekat postepenog vraćanja, što je veoma pogodno za implementaciju prikaza znak po znak na veb-stranici. +Ovaj interfejs takođe podržava protočne odgovore; postavite parametar `stream` na `true` da biste dobili efekat postepenog vraćanja, što je veoma pogodno za implementaciju prikaza reč po reč na veb-stranici. ### Python primer @@ -183,14 +186,14 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Strimovani odgovor se vraća u formatu Server-Sent Events (SSE), pri čemu svaki red ima prefiks `event:` i `data:`. Tipovi strimovanih događaja uključuju: +Protočni odgovor vraća se u formatu Server-Sent Events (SSE), pri čemu svaki red počinje prefiksima `event:` i `data:`. Tipovi protočnih događaja uključuju: -- `message_start`: početak poruke, sadrži osnovne informacije o poruci i naziv modela. -- `content_block_start`: početak bloka sadržaja. -- `content_block_delta`: inkrementalno ažuriranje bloka sadržaja, sadrži novogenerisani fragment teksta. -- `content_block_stop`: kraj bloka sadržaja. -- `message_delta`: inkrementalno ažuriranje na nivou poruke, sadrži informacije `stop_reason` i konačne `usage`. Merodavna vrednost `output_tokens_details.thinking_tokens` treba da se čita samo iz poslednjeg `message_delta.usage`; nemojte je sabirati kroz događaje. -- `message_stop`: kraj poruke. +- `message_start`: Početak poruke, sadrži osnovne informacije o poruci i naziv modela. +- `content_block_start`: Početak bloka sadržaja. +- `content_block_delta`: Inkrementalno ažuriranje bloka sadržaja, sadrži novogenerisani fragment teksta. +- `content_block_stop`: Kraj bloka sadržaja. +- `message_delta`: Inkrementalno ažuriranje na nivou poruke, sadrži informacije `stop_reason` i konačne `usage`. Autoritativna vrednost `output_tokens_details.thinking_tokens` treba da se čita samo iz poslednjeg `message_delta.usage`, nemojte je sabirati kroz događaje. +- `message_stop`: Kraj poruke. Efekat izlaza je sledeći: @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Može se videti da događaj `content_block_delta` u strimovanom odgovoru sadrži postepeno generisan tekstualni sadržaj; spajanjem svih `text_delta` možete dobiti kompletan odgovor. +Može se videti da događaj `content_block_delta` u protočnom odgovoru sadrži postepeno generisani tekstualni sadržaj, a kompletan odgovor može se dobiti spajanjem svih `text_delta` vrednosti. ### JavaScript primer @@ -253,7 +256,7 @@ while (true) { ## Višekružni razgovor -Ako želite da povežete funkcionalnost višekružnog razgovora, potrebno je da naizmenično poređate poruke sa ulogama `user` i `assistant` u nizu `messages` i zajedno prosledite prethodnu istoriju razgovora. +Ako želite da povežete funkciju višekružnog razgovora, potrebno je da u nizu `messages` naizmenično poređate poruke sa ulogama `user` i `assistant`, i zajedno prosledite prethodnu istoriju razgovora. ### Python primer @@ -283,7 +286,6 @@ print(response.json()) ``` Rezultat vraćanja je sledeći: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ Rezultat vraćanja je sledeći: } ``` -Prosleđivanjem kompletne istorije razgovora u `messages`, Claude može da daje precizne odgovore u skladu sa kontekstom. +Prosleđivanjem kompletne istorije razgovora u `messages`, Claude može da kombinuje kontekst kako bi davao tačne odgovore. ## Model dubokog razmišljanja -Claudeovi thinking i thinking summary su dva različita koncepta: model može da vrši interno zaključivanje, ali API ne vraća originalni lanac razmišljanja. Kada je potrebno prikazati proces zaključivanja, API vraća obrađeni sažetak. +Claude-ovi thinking i thinking summary su dva različita koncepta: model može da obavlja interno zaključivanje, ali API ne vraća originalni lanac misli. Kada je potrebno prikazati proces zaključivanja, API vraća obrađeni sažetak. -Za trenutni model preporučuje se korišćenje adaptive thinking-a i kontrolisanje ukupnog ulaganja u zaključivanje putem `output_config.effort`: +Za trenutne modele preporučuje se korišćenje adaptive thinking-a i kontrolisanje ukupnog ulaganja u zaključivanje putem `output_config.effort`: ```python import requests @@ -350,26 +352,27 @@ Thinking blok u odgovoru izgleda ovako: "signature": "opaque-signature" } ``` -- `display: "summarized"` vraća čitljiv sažetak razmišljanja; to nije izvorni lanac misli. -- `display: "omitted"` vraća `thinking: ""`, ali i dalje zadržava opaque `signature` radi podrške narednim razgovorima. -- `display: "updates"` je Anthropic-ov beta režim, koji zahteva `anthropic-beta: thinking-display-updates-2026-08-18`. Zvanična definicija je da se skriva glavni tekst rezonovanja, a prikazuju kratka ažuriranja napretka između poziva alata. Platforma prosleđuje ovaj parametar i beta zaglavlje zahteva u izvornom obliku, neće ga prisilno prepisati kao `summarized`; stvarni izlazni sadržaj zavisi od podrške izabranog modela. -- `thinking`, `output_config`, effort, parametri uzorkovanja i nova proširena polja prosleđuju se u izvornom obliku. Platforma ne održava tvrdo kodirane enumeracije vrednosti niti ograničenja kombinacija po modelu, niti automatski prepisuje thinking režim; da li se ovi parametri prihvataju određuje izabrani model, a greške parametara koje vrati model prosleđuju se klijentu. + +- `display: "summarized"` vraća čitljiv sažetak razmišljanja; to nije originalni lanac misli. +- `display: "omitted"` vraća `thinking: ""`, ali i dalje zadržava opaque `signature` za podršku narednim razgovorima. +- `display: "updates"` je Anthropic-ov beta režim, koji zahteva `anthropic-beta: thinking-display-updates-2026-08-18`. Zvanična definicija je skrivanje teksta zaključivanja i prikazivanje kratkih ažuriranja napretka između poziva alata. Platforma prosleđuje ovaj parametar i beta zaglavlje zahteva u izvornoj vrednosti, i neće ga prinudno prepisati u `summarized`; stvarni sadržaj izlaza zavisi od podrške izabranog modela. +- `thinking`, `output_config`, effort, parametri uzorkovanja i nova proširena polja prosleđuju se u izvornim vrednostima. Platforma ne održava tvrdo kodirane enumeracije vrednosti ili ograničenja kombinacija po modelu, niti automatski prepisuje thinking režime; o prihvatanju ovih parametara odlučuje izabrani model, a greške parametara koje vrati model biće prosleđene klijentu. - Podrazumevana vrednost display-a za Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 i Opus 4.7 je `omitted`; Opus 4.6, Sonnet 4.6 i raniji modeli koji podržavaju thinking podrazumevano koriste `summarized`. -- Display utiče samo na vraćeni sadržaj i kašnjenje strimovanja, ne isključuje rezonovanje niti smanjuje naplatu thinking tokena. -- Da li je thinking podrazumevano omogućen i podrazumevana vrednost display-a su dva nezavisna pitanja. Opus 5 i Sonnet 5 podrazumevano omogućavaju adaptive thinking; za Opus 5, izostavljanje `thinking` je ekvivalentno adaptive, a izostavljanje `output_config.effort` je ekvivalentno `high`. Opus 4.8, 4.7 i 4.6 zahtevaju eksplicitno omogućavanje. -- Thinking i završni tekst zajedno zauzimaju izlazni budžet `max_tokens`. Kada je budžet premali, thinking može zauzeti najveći deo kvote, zbog čega tekst može biti prazan ili odsečen; povećajte `max_tokens` ili koristite `low` / `medium` effort za kontrolu ulaganja u rezonovanje. -- Za modele koji dozvoljavaju isključivanje thinking-a, može se proslediti `thinking: {"type":"disabled"}`. Novi režimi kao što je `between_tools` i effort kombinacije zavise od izabranog modela; platforma ih ne odbija unapred na osnovu starih pravila za modele. -- Fiksni budžet za razmišljanje može se proslediti putem `budget_tokens`; novi modeli obično koriste `thinking.type=adaptive` i `output_config.effort`. Da li su fiksni budžet ili isključivanje razmišljanja podržani zavisi od trenutnih mogućnosti izabranog modela. -- U višekružnim razgovorima i pri pozivima alata, kompletan thinking blok i signature koje vrati assistant treba proslediti nazad neizmenjene; nemojte menjati niti samostalno generisati signature. -- Prosleđivanje parametara ne znači da svaki model podržava sve funkcije. Pozivi između protokola i dalje zahtevaju konverziju, a opseg podrške i greške za sadržaje kao što je `redacted_thinking` određuje servis modela koji stvarno obrađuje zahtev. +- Display utiče samo na vraćeni sadržaj i kašnjenje pri strimovanju, ne isključuje zaključivanje niti smanjuje naplatu thinking tokena. +- Podrazumevano omogućavanje thinking-a i podrazumevana vrednost display-a su dva nezavisna pitanja. Opus 5 i Sonnet 5 podrazumevano omogućavaju adaptive thinking; za Opus 5, izostavljanje `thinking` je ekvivalentno adaptive, a izostavljanje `output_config.effort` je ekvivalentno `high`. +- Thinking i konačni tekst zajedno zauzimaju izlazni budžet `max_tokens`. Kada je budžet premali, thinking može zauzeti većinu kvote, ostavljajući tekst praznim ili odsečenim; povećajte `max_tokens`, ili koristite `low` / `medium` effort za kontrolu ulaganja u zaključivanje. +- Za modele kojima je dozvoljeno isključivanje thinking-a, može se proslediti `thinking: {"type":"disabled"}`. Novi režimi poput `between_tools`, kao i effort kombinacije, zavise od izabranog modela; platforma ih ne odbija unapred na osnovu starih pravila za modele. +- Fiksni budžet za razmišljanje može se proslediti putem `budget_tokens`; novi modeli obično koriste `thinking.type=adaptive` i `output_config.effort`. Da li su podržani fiksni budžet ili isključivanje razmišljanja zavisi od trenutnih mogućnosti izabranog modela. +- Tokom višekružnih razgovora i poziva alata, kompletan thinking blok i signature koje vrati assistant treba vratiti neizmenjene; ne menjajte niti sami generišite signature. +- Prosleđivanje parametara ne znači da svaki model podržava sve funkcije. Pozivi preko različitih protokola i dalje zahtevaju konverziju, a opseg podrške za sadržaje poput `redacted_thinking` i greške određuje servis modela koji stvarno obrađuje zahtev. -U strimovanim zahtevima, `summarized` proizvodi `thinking_delta`; `omitted` ne proizvodi `thinking_delta`, već zadržava samo životni ciklus thinking bloka i `signature_delta`. +U strimovanim zahtevima, `summarized` će proizvesti `thinking_delta`; `omitted` neće proizvesti `thinking_delta`, već samo zadržava životni ciklus thinking bloka i `signature_delta`. ## Vizuelni modeli -Claude podržava multimodalni unos i može istovremeno obrađivati tekst i slike. U Messages API-ju, vizuelne mogućnosti se mogu koristiti postavljanjem `content` na format niza i prosleđivanjem bloka sadržaja slike. +Claude podržava multimodalni unos i može istovremeno da obrađuje tekst i slike. U Messages API-ju, vizuelne mogućnosti se mogu koristiti postavljanjem `content` u format niza i prosleđivanjem bloka sadržaja slike. -### Korišćenje Base64 kodiranih slika +### Korišćenje slika kodiranih u Base64 formatu ```python import base64 @@ -456,7 +459,6 @@ print(response.json()) ``` ### cURL primer - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -486,11 +488,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Podržani formati slika uključuju: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Podržani formati slika uključuju: `image/jpeg`, `image/png`, `image/gif` i `image/webp`. ## Dokumenti i PDF -PDF koristi `document` blok sadržaja i podržava dva stabilna izvora, Base64 i URL. Base64 izvor mora koristiti `application/pdf`: +PDF koristi sadržajni blok `document` i podržava dva stabilna izvora: Base64 i URL. Base64 izvor mora koristiti `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -URL izvor se piše kao `{"type":"url","url":"https://example.com/report.pdf"}`. `document` takođe podržava `text/plain` i `content` izvor sastavljen od text/image blokova; opciona polja uključuju `title`, `context` i `citations`. `file_id` izvor iz Files API-ja pripada zasebnoj beta funkciji i nije deo stabilnog ugovora ovog interfejsa. +URL izvor se piše kao `{"type":"url","url":"https://example.com/report.pdf"}`. `document` takođe podržava `text/plain` i `content` izvore sastavljene od text/image blokova; opciona polja uključuju `title`, `context` i `citations`. Izvor `file_id` iz Files API-ja pripada zasebnoj beta funkciji i nije deo stabilnog ugovora ovog interfejsa. -## Keširanje promptova +## Keširanje upita -`cache_control` najvišeg nivoa automatski postavlja tačku prekida keša na poslednji blok koji se može keširati: +`cache_control` na najvišem nivou automatski postavlja tačku prekida keširanja na poslednji blok koji se može keširati: ```python payload = { @@ -534,9 +536,10 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Kada je potrebna precizna kontrola pozicije, isti `cache_control` se takođe može napisati na sadržajnim blokovima text, image, document, tool_use, tool_result ili na definicijama alata. `ttl` podržava `5m` (podrazumevano) i `1h`; proverite upisivanje i pogodak keša putem `usage.cache_creation_input_tokens` i `usage.cache_read_input_tokens`. -Kada odgovor pruža `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Ako je `cache_creation` `null` ili je izostavljen, to označava da postoji samo ukupan iznos upisivanja u keš, bez autoritativne TTL podele; u tom slučaju nemojte nijedan bucket smatrati poznatim kao 0, obračun i ukupna količina i dalje se zasnivaju na aggregate polju. +Kada je potrebna precizna kontrola pozicije, isti `cache_control` se takođe može zapisati na sadržajne blokove text, image, document, tool_use, tool_result ili na definicije alata. `ttl` podržava `5m` (podrazumevano) i `1h`; koristite `usage.cache_creation_input_tokens` i `usage.cache_read_input_tokens` da biste utvrdili upisivanje u keš i pogodak u kešu. + +Kada odgovor pruža `usage.cache_creation`, važi `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Ako je `cache_creation` `null` ili je izostavljen, to znači da postoji samo ukupna količina upisivanja u keš, bez pouzdane TTL podele; u tom slučaju nijedan bucket ne treba smatrati poznatim kao 0, a naplata i ukupna količina i dalje se zasnivaju na agregatnom polju. Primer vraćenog rezultata: @@ -563,7 +566,7 @@ Primer vraćenog rezultata: ## Pozivanje alata (Tool Use) -Claude Messages API izvorno podržava funkcionalnost pozivanja alata, omogućavajući modelu da po potrebi pozove vaše unapred definisane alate/funkcije. +Claude Messages API izvorno podržava funkciju pozivanja alata, omogućavajući modelu da po potrebi pozove vaše unapred definisane alate/funkcije. ### Python primer @@ -637,7 +640,7 @@ Kada model odluči da pozove alat, `content` u vraćenom rezultatu će sadržati } ``` -Imajte na umu da je `stop_reason` `tool_use`, što označava da model treba da pozove alat. Nakon prijema ovog rezultata, potrebno je da izvršite funkciju alata i vratite rezultat modelu u obliku `tool_result`: +Imajte na umu da je `stop_reason` `tool_use`, što ukazuje da model treba da pozove alat. Nakon prijema ovog rezultata, potrebno je da izvršite funkciju alata i vratite rezultat modelu u obliku `tool_result`: ```python payload = { @@ -685,39 +688,38 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Model će na osnovu rezultata vraćenog od alata generisati konačni odgovor na prirodnom jeziku. +Model će na osnovu rezultata koje je alat vratio generisati konačni odgovor na prirodnom jeziku. ## Razlike u odnosu na Chat Completion API Ace Data Cloud istovremeno pruža dva Claude API formata, a njihove glavne razlike su sledeće: -`usage.input_tokens` u Messages API-ju predstavlja samo ulaz bez keša, dok su `cache_read_input_tokens` i `cache_creation_input_tokens` nezavisni obračunski bucket-i; sva tri se zasebno obračunavaju po odgovarajućim cenama. - +`usage.input_tokens` u Messages API-ju predstavlja samo ulaz koji nije keširan, dok su `cache_read_input_tokens` i `cache_creation_input_tokens` nezavisni obračunski bucket-i; sva tri se zasebno obračunavaju prema odgovarajućim cenama. | Karakteristika | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Format | Anthropic izvorni format | OpenAI kompatibilan format | -| Sistemski prompt | Zasebno polje `system` | Prenosi se kroz `role: "system"` u `messages` | +| Sistemska prompt poruka | Nezavisno polje `system` | Prosleđuje se kroz `role: "system"` u `messages` | | Struktura odgovora | Niz `content` (podržava više tipova) | Niz `choices` (sadrži `message`) | -| Striming format | SSE događaji (više tipova događaja) | SSE `data` redovi | +| Format strimovanja | SSE događaji (više tipova događaja) | SSE `data` redovi | | Duboko razmišljanje | Izvorni `thinking` i `output_config.effort` | Podrazumevana strategija modela i kompatibilni parametri | | Pozivanje alata | Izvorni `tools` + `input_schema` | OpenAI kompatibilan format `tools` | | Token statistika | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Ako je vaš sistem već integrisan sa API-jem u OpenAI formatu, možete koristiti Chat Completion API za neprimetan prelazak. Ako treba da koristite sve izvorne mogućnosti Claude-a, preporučuje se korišćenje Messages API-ja. +Ako je vaš sistem već integrisan sa API-jem u OpenAI formatu, možete koristiti Chat Completion API za neometano prebacivanje. Ako vam je potrebno da koristite sve Claude-ove izvorne mogućnosti, preporučuje se korišćenje Messages API-ja. -## Obrada grešaka +## Rukovanje greškama -Odgovori sa greškom javnog interfejsa koriste Ace Data Cloud platform envelope: `error.code` je stabilan kod greške, `error.message` je objašnjenje, a `trace_id` se koristi za dijagnostiku zahteva. Uobičajeni HTTP statusi uključuju: +Odgovori na greške javnog interfejsa koriste Ace Data Cloud platform envelope: `error.code` je stabilan kod greške, `error.message` je objašnjenje, a `trace_id` se koristi za istraživanje zahteva. Uobičajeni HTTP statusi uključuju: - `400`: Parametri zahteva ili sadržaj protokola su nevažeći. -- `401`: Autorizacioni token je nevažeći, nedostaje ili je istekao. +- `401`: Token za autorizaciju je nevažeći, nedostaje ili je istekao. - `403`: Pristup je zabranjen, stanje je nedovoljno ili je kvota ograničena. - `404`: API ili model ne postoji. - `413`: Telo zahteva je preveliko. - `429`: Previše zahteva. -- `500` / `503` / `504`: Greška usluge, privremena nedostupnost ili istek vremena obrade. +- `500` / `503` / `504`: Greška usluge, privremeno nedostupno ili je obrada istekla. -### Primer odgovora sa greškom +### Primer odgovora na grešku ```json { @@ -729,7 +731,8 @@ Odgovori sa greškom javnog interfejsa koriste Ace Data Cloud platform envelope: } ``` -Ova struktura greške je ugovor tokom izvršavanja Ace Data Cloud-a i nije ekvivalentna zvaničnom Anthropic error envelope-u; obradite je prema HTTP statusu i `error.code`. +Ova struktura greške je ugovor u toku izvršavanja za Ace Data Cloud i nije ekvivalentna zvaničnom Anthropic error envelope-u; postupajte prema HTTP statusu i `error.code`. ## Zaključak -Kroz ovaj dokument, već ste saznali kako da koristite Claude Messages API za pozivanje Claude-ove funkcije razgovora u Anthropic izvornom formatu. Messages API podržava bogate funkcije kao što su osnovni razgovor, sistemski promptovi, strimovani odgovori, višekružni razgovori, duboko razmišljanje, vizuelno razumevanje, PDF-ovi, keširanje promptova i pozivanje alata. Ako imate bilo kakvih pitanja, slobodno kontaktirajte naš tim za tehničku podršku. + +Putem ovog dokumenta, već ste saznali kako da koristite Claude Messages API za pozivanje Claude-ovih funkcija za razgovor u Anthropic izvornom formatu. Messages API podržava bogate funkcije kao što su osnovni razgovori, sistemske prompt poruke, strimovani odgovori, razgovori u više rundi, duboko razmišljanje, vizuelno razumevanje, PDF, keširanje promptova i pozivanje alata. Ako imate bilo kakvih pitanja, slobodno kontaktirajte naš tim tehničke podrške. diff --git a/sr/guides/openai/openai_embeddings.mdx b/sr/guides/openai/openai_embeddings.mdx index b860de19f..726bfe6aa 100644 --- a/sr/guides/openai/openai_embeddings.mdx +++ b/sr/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API申请及使用" +title: "Prijava i korišćenje OpenAI Embeddings API-ja" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI reč vektori usluga, koja se koristi za generisanje reč vektora rezultata koji predstavljaju ulazni tekst. +OpenAI usluga vektora reči, koristi se za generisanje rezultata vektora reči koji predstavljaju ulazni tekst. -Ovaj dokument uglavnom opisuje proces korišćenja OpenAI Embeddings API, koristeći ga možemo kreirati vektore ugrađene koji predstavljaju ulazni tekst. +Ovaj dokument uglavnom predstavlja tok korišćenja OpenAI Embeddings API operacija, pomoću kojih možemo kreirati ugrađene vektore koji predstavljaju ulazni tekst。。 ## Proces prijave -Da biste koristili OpenAI Embeddings API, prvo idite na [Ace Data Cloud kontrolnu tablu](https://platform.acedata.cloud/console/applications) da dobijete svoj API Token, čuvajući ga za kasnije. +Da biste koristili OpenAI Embeddings API, prvo idite na [Ace Data Cloud konzolu](https://platform.acedata.cloud/console/applications) da biste dobili svoj API Token i sačuvali ga za kasniju upotrebu. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Ako još niste prijavljeni ili registrovani, automatski ćete biti preusmereni na stranicu za prijavu koja vas poziva da se registrujete i prijavite, a nakon toga ćete se automatski vratiti na trenutnu stranicu. +Ako se još niste prijavili ili registrovali, bićete automatski preusmereni na stranicu za prijavu gde ćete biti pozvani da se registrujete i prijavite, a po završetku ćete automatski biti vraćeni na trenutnu stranicu. -**Jedan API Token je dovoljan za korišćenje svih usluga platforme, nije potrebno da se za svaku uslugu posebno prijavljujete.** Prvi put kada se prijavite dobićete besplatnu kvotu, možete besplatno isprobati; kada kvota postane nedovoljna, možete dopuniti opšti saldo na [kontrolnoj tabli](https://platform.acedata.cloud/console/coin). +**Jedan API Token može da poziva sve usluge platforme, bez potrebe za posebnom prijavom za svaku uslugu.** Prilikom prve prijave dobijate besplatan kredit koji možete koristiti za besplatno isprobavanje; kada kredit nije dovoljan, možete dopuniti opšti saldo na [konzoli](https://platform.acedata.cloud/console/coin). -> 📘 Potpuna dokumentacija: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) +> 📘 Kompletna dokumentacija: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) ## Osnovna upotreba -Sledeće možete popuniti odgovarajući sadržaj na interfejsu, kao što je prikazano na slici: +Zatim možete popuniti odgovarajući sadržaj u interfejsu, kao što je prikazano na slici:

-Prilikom prvog korišćenja ovog interfejsa, potrebno je da popunite najmanje tri sadržaja, jedan je `authorization`, koji možete direktno izabrati iz padajuće liste. Drugi parametar je `model`, `model` je kategorija modela koju biramo da koristimo sa OpenAI zvanične stranice, ovde imamo 3 glavna modela, detalje možete videti u modelima koje pružamo. Poslednji parametar je `input`, `input` je tekst reč vektora koji treba da konvertujemo. +Prilikom prvog korišćenja ovog interfejsa, potrebno je da popunimo najmanje tri stavke, jedna je `authorization`, koju možete direktno izabrati sa padajuće liste. Drugi parametar je `model`, `model` predstavlja kategoriju modela sa zvaničnog OpenAI sajta koju biramo da koristimo, trenutno dostupni modeli su `text-embedding-3-small` i `text-embedding-3-large`. `text-embedding-ada-002` se više ne pruža; ako postojeći vektorski indeks koristi ovaj stari model, vektori novog modela se ne mogu direktno kombinovati sa njim i indeks je potrebno ponovo izgraditi. Poslednji parametar je `input`, `input` je tekst vektora reči koji treba da konvertujemo. -Takođe možete primetiti da se sa desne strane generiše odgovarajući kod za pozivanje, možete kopirati kod i direktno ga pokrenuti, ili jednostavno kliknuti na dugme „Try“ za testiranje. +Istovremeno možete primetiti da se na desnoj strani generiše odgovarajući kod za pozivanje, možete kopirati kod i direktno ga pokrenuti, ili možete direktno kliknuti na dugme „Try“ radi testiranja. Opcioni parametri: -- `dimensions`: skraćivanje dimenzija vektora, podrazumevano izlaz je u punim dimenzijama. -- `encoding_format`: format povratka, opcionalno `float` ili `base64`. +- `dimensions`: skraćivanje dimenzija vektora, podrazumevano se vraćaju pune dimenzije. +- `encoding_format`: format povratne vrednosti, opcije su `float` ili `base64`.

-Python primer pozivnog koda: +Primer Python koda za pozivanje: ```python import requests @@ -50,8 +50,8 @@ headers = { } payload = { - "input": "Hrana je bila ukusna i konobar...", - "model": "text-embedding-ada-002", + "input": "The food was delicious and the waiter...", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Nakon poziva, otkrili smo da je rezultat povratka sledeći: +Nakon pozivanja, vidimo da je povratni rezultat sledeći: ```json { @@ -97,7 +97,7 @@ Nakon poziva, otkrili smo da je rezultat povratka sledeći: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,25 +105,25 @@ Nakon poziva, otkrili smo da je rezultat povratka sledeći: } ``` -Povratni rezultat ima više polja, opisana su kako sledi: +Povratni rezultat ima više polja, koja su opisana u nastavku: -- `model`, model koji je korišćen za konverziju teksta u reč vektor. -- `usage`, informacije o tokenima korišćenim za konverziju teksta u reč vektor. -- `data`, rezultati reč vektora nakon konverzije teksta. +- `model`, model korišćen za konvertovanje ovog teksta u vektore reči. +- `usage`, informacije o tokenima korišćenim za konvertovanje ovog teksta u vektore reči. +- `data`, rezultat vektora reči nakon konvertovanja teksta. -Gde `data` sadrži konkretne informacije o reč vektoru koji odgovara tekstu, a `embedding` su konkretni rezultati generisanog reč vektora. +Među njima, `data` sadrži konkretne informacije o vektorima reči koji odgovaraju tekstu, a `embedding` unutar njega predstavlja konkretan generisani rezultat vektora reči. ## Obrada grešaka -Kada pozivate API, ako naiđete na grešku, API će vratiti odgovarajući kod greške i informacije. Na primer: +Prilikom pozivanja API-ja, ako dođe do greške, API će vratiti odgovarajući kod greške i informacije. Na primer: -- `400 token_mismatched`: Neispravna zahtev, moguće zbog nedostajućih ili nevalidnih parametara. -- `400 api_not_implemented`: Neispravna zahtev, moguće zbog nedostajućih ili nevalidnih parametara. -- `401 invalid_token`: Neautorizovano, nevalidan ili nedostajući autorizacioni token. -- `429 too_many_requests`: Previše zahteva, premašili ste limit brzine. -- `500 api_error`: Interna greška servera, nešto nije u redu sa serverom. +- `400 token_mismatched`: Neispravan zahtev, moguće zbog nedostajućih ili nevažećih parametara. +- `400 api_not_implemented`: Neispravan zahtev, moguće zbog nedostajućih ili nevažećih parametara. +- `401 invalid_token`: Neovlašćeno, nevažeći ili nedostajući token za autorizaciju. +- `429 too_many_requests`: Previše zahteva, prekoračili ste ograničenje broja zahteva. +- `500 api_error`: Interna greška servera, nešto je pošlo po zlu na serveru. -### Primer greške u odgovoru +### Primer odgovora greške ```json { @@ -138,4 +138,4 @@ Kada pozivate API, ako naiđete na grešku, API će vratiti odgovarajući kod gr ## Zaključak -Kroz ovaj dokument, već ste saznali kako lako koristiti OpenAI Embeddings API za korišćenje funkcionalnosti generisanja reč vektora zvaničnog OpenAI. Nadamo se da će vam ovaj dokument pomoći da bolje povežete i koristite ovaj API. Ako imate bilo kakvih pitanja, slobodno se obratite našem timu tehničke podrške. +Kroz ovaj dokument, već ste saznali kako da koristite OpenAI Embeddings API za jednostavno korišćenje funkcije generisanja vektora reči zvaničnog OpenAI-ja. Nadamo se da će vam ovaj dokument pomoći da bolje integrišete i koristite ovaj API. Ako imate bilo kakvih pitanja, slobodno kontaktirajte naš tim tehničke podrške. diff --git a/sr/guides/platform/wework_bot.mdx b/sr/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..e04ed871b --- /dev/null +++ b/sr/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "WeCom robot" +description: "Platform API guide - Ace Data Cloud" +--- + +Postavite sopstvenu instancu WeCom naloga, prijavite se skeniranjem pomoću mobilnog WeCom-a i čitajte nalog, kontakte, razgovore i lokalno sinhronizovane poruke putem REST API-ja ili MCP-a. Instanca odgovara običnom WeCom nalogu, bez potrebe za privatizovanim serverom ili konfiguracijom domena poslovne e-pošte. + +Trenutno je Alpha. Čitanje naloga je završilo verifikaciju stvarnih razgovora; slanje teksta od strane vlasnika i povratno čitanje događaja su završili stvarno prihvatanje; operacije nad drugim kontaktima, grupama i oporavak novih instanci još zahtevaju prihvatanje u okruženju za postavljanje. Slanje medija, odgovor sa citatom, stvarno @, upravljanje članovima grupe i potvrde isporuke još nisu dostupni. Merodavna je povratna vrednost instance `/api/capabilities`. + +## Postavljanje i prijava + +Otvorite uslugu u kategoriji Deployment i izaberite paket trajanja instance. Nakon postavljanja otvorite stranicu za upravljanje i skenirajte kod pomoću WeCom-a vlasnika naloga; ako je potrebna potvrda na telefonu ili drugi koraci prijave, otvorite udaljenu radnu površinu i unesite lozinku radne površine te instance. API akreditivi i lozinka radne površine su nezavisni. Podaci za prijavu se čuvaju na disku instance, ponovno kreiranje kontejnera zadržava disk; brisanje diska će obrisati lokalnu sesiju. + +Svaka instanca se naplaćuje zasebno i radi u skladu sa kupljenim trajanjem. REST / MCP pozivi se ne naplaćuju dodatno po poruci, a stvarna cena je određena stranicom paketa. Trenutno se podrazumevano referiše na pakete trajanja WeChat robota, a pre konačnog otvaranja potrebno je potvrditi cene u kombinaciji sa resursima za rad. + +## API i MCP + +Koristite API adresu instance na stranici za upravljanje, a svi interfejsi naloga nose `Authorization: Bearer `. Ove putanje pripadaju namenskoj instanci, a ne deljenom API mrežnom prolazu. MCP adresa je adresa instance sa dodatkom `/mcp/` i koristi isti Bearer token. + +| Interfejs | Namena | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Da li je nalog spreman i lista mogućnosti | +| `GET /api/auth/qr` | PNG Base64 trenutnog QR koda za prijavu | +| `GET /api/account` | Trenutni nalog | +| `GET /api/contacts?kind=all` | Interni kolege i eksterni kontakti, može se navesti internal / external | +| `GET /api/conversations` | Lokalni razgovori, zadržavaju originalni ID razgovora | +| `GET /api/messages` | Lokalno sinhronizovane poruke; parametri conversation_id, after_rowid, limit | +| `POST /api/search` | Pretraga kontakata, razgovora i lokalnog teksta | +| `POST /api/messages` | Asinhroni zadatak slanja teksta, mora se navesti Idempotency-Key | +| `POST /api/messages/send` | Isti ulaz za slanje, podržava jedan ili više ciljeva | +| `GET /api/groups/{conversation_id}` | Lokalno sinhronizovane informacije o grupi i članovi | +| `GET /api/tasks` | Nedavni zadaci i rezultati za svaki cilj | +| `GET /api/tasks/{id}` | Upit rezultata slanja | +| `POST /api/tasks/{id}/cancel` | Otkazivanje zadatka koji još nije započet | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Pauziranje automatizacije; nastavak nakon verifikacije vlasnika | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Stanje instance i trenutni ekran, oba zahtevaju autentifikaciju | +| `GET /api/events?after=0` | Događaji poruka sa kursorom koji se može nastaviti | +| `WS /ws` | Tok događaja poruka, Bearer autentifikacija | + +Telo za slanje sadrži `target`, `type: "text"` i `text`. `target` prihvata ID razgovora, ID kontakta, ID poslovnog korisnika ili jedinstveno puno ime; prednost imaju ID-jevi; kada prikazano ime i dalje ne može jedinstveno odrediti cilj, instanca će odbiti operaciju i neće nagađati objekat. Kontakt bez lokalnog razgovora će prvo otvoriti razgovor putem klijenta, a zatim poslati poruku nakon provere stvarnog ID-ja razgovora. Zaglavlje zahteva `Idempotency-Key` sastoji se od 8–128 slova, brojeva ili `_.:-`. Ponovljeni zahtevi za istu operaciju moraju ponovo koristiti isti ključ i isto telo zahteva. + +Zamenom `target` nizom `targets` može se serijski slati na 1–50 jasno navedenih ciljeva. Oba se ne mogu navesti istovremeno. Svi ciljevi prvo završavaju razrešavanje identiteta, a različiti pseudonimi koji upućuju na isti objekat biće odbijeni. Nakon neuspeha jednog cilja, naredna slanja se zaustavljaju, a rezultat zadatka po stavkama beleži `succeeded`, `failed`, `unknown` ili `not_attempted`; delimičan uspeh nemojte smatrati potpunim uspehom. Ovaj proces takođe treba da završi stvarno prihvatanje navedenih kontakata u okruženju za postavljanje. + +Zadaci mogu biti u stanju queued, running, submitting, succeeded, failed, unknown ili cancelled. `succeeded` znači da su nakon slanja u odgovarajućem zapisu razgovora pronađeni tačan tekst i ID poruke servera, dok je `delivered` i dalje null, što ne znači da je druga strana primila poruku. unknown znači da rezultat nije jasan; proverite istoriju zapisa i nemojte ponavljati slanje sa novim ključem. Instanca neće automatski ponovo slati prekinute zadatke. + +Istorija uključuje samo sadržaj koji je klijent već sinhronizovao i ne može garantovati kompletnu istoriju. Netekstualne poruke mogu vratiti tip unknown, a preuzimanje priloga još nije dostupno. Događaji zadržavaju najnovijih 10.000 stavki, a `gap` označava da je kursor već izašao iz prozora zadržavanja. Prvo povezivanje neće ponovo emitovati staru istoriju kao nove poruke. + +`server_accepted` i `server_id` u istoriji poruka mogu se koristiti za proveru da li je server prihvatio lokalnu poruku; kada postoji samo lokalni zapis bez ID-ja servera, slanje se ne može smatrati uspešnim. Ova polja ne predstavljaju da je primalac poruku primio ili pročitao. Zapisi događaja zadržavaju stanje u trenutku generisanja; za upit trenutnog stanja potvrde treba koristiti interfejs istorije poruka. + +## Nalog i akreditivi + +Prijavite samo naloge nad kojima vlasnik ima ovlašćenje za rad. Konfigurišite API token u pouzdanim aplikacijama; on može pristupiti podacima naloga te instance. Ne objavljujte lozinke, QR kodove ili snimke ekrana razgovora na javnim mestima. Pauziranje instance će prekinuti događaje u realnom vremenu. Nakon odjave naloga ili uklanjanja uređaja na mobilnoj strani, potrebno je ponovo se prijaviti. + +Trenutni unos teksta podržava samo jedan red, a novi redovi će biti izričito odbijeni pre slanja. Kada klijent zahteva bezbednosnu verifikaciju ili ponovnu prijavu, vlasnik naloga to treba da završi na udaljenoj radnoj površini; instanca neće zaobići verifikaciju. Zadaci nakon prekida verifikacije mogu vratiti unknown, prvo proverite zapise poruka i nemojte ponovo slati sa novim ključem idempotentnosti. + +Nakon prepoznavanja upita za bezbednosnu verifikaciju, odjave naloga ili promene, red automatizacije će trajno biti pauziran. Nakon završetka verifikacije telefonom, možete nastaviti još neizvršene zadatke putem opcije „Nastavi nakon verifikacije” na konzoli instance; zadaci koji su već poslati, ali čiji je rezultat neizvestan, neće biti ponovo poslati. Uobičajen rad na daljinu takođe može pokrenuti WeCom bezbednosnu verifikaciju. Period od 24 sata bez ponovnog zaključavanja nakon verifikacije, naveden u zvaničnom objašnjenju, ne znači da je detekcija već uklonjena, niti znači da instanca može garantovati dugoročni rad bez nadzora. diff --git a/sv/guides/claude/claude_messages.mdx b/sv/guides/claude/claude_messages.mdx index b5dbd2b85..88b231de5 100644 --- a/sv/guides/claude/claude_messages.mdx +++ b/sv/guides/claude/claude_messages.mdx @@ -1,43 +1,44 @@ --- -title: "Ansökan om och användning av Claude Messages API" +title: "Ansökan och användning av Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude är ett mycket kraftfullt AI-konversationssystem som kan generera flytande och naturliga svar på bara några sekunder genom att mata in en prompt. Claude Messages API är Anthropics officiella, inbyggda API-format. Till skillnad från det OpenAI-kompatibla formatet (Chat Completion) använder det Anthropics egen struktur för begäranden och svar, vilket gör det möjligt att bättre utnyttja Claudes unika funktioner, såsom multimodala innehållsinmatningar, verktygsanrop, djupgående tänkande (Extended Thinking) och andra avancerade funktioner. +Anthropic Claude är ett mycket kraftfullt AI-konversationssystem som kan generera flytande och naturliga svar på bara några sekunder genom att mata in en prompt. Claude Messages API är Anthropics officiella inbyggda API-format. Till skillnad från det OpenAI-kompatibla formatet (Chat Completion) använder det Anthropics egen struktur för förfrågningar och svar, vilket gör det möjligt att bättre utnyttja Claudes unika funktioner, såsom multimodala innehållsinmatningar, verktygsanrop, fördjupat tänkande (Extended Thinking) och andra avancerade funktioner. -Detta dokument introducerar huvudsakligen användningsprocessen för Claude Messages API. Med hjälp av det kan vi använda ett inbyggt gränssnitt som överensstämmer med Anthropics officiella gränssnitt för att anropa Claudes konversationsfunktioner. +Detta dokument introducerar främst användningsprocessen för Claude Messages API-operationer. Med hjälp av det kan vi använda samma inbyggda gränssnitt som Anthropic officiellt erbjuder för att anropa Claudes konversationsfunktioner. ## Ansökningsprocess -För att använda Claude Messages API, gå först till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att hämta din API Token och spara den för senare användning. +För att använda Claude Messages API går du först till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att hämta din API Token och spara den för senare användning. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Om du ännu inte är inloggad eller registrerad omdirigeras du automatiskt till inloggningssidan för att registrera dig och logga in. När det är klart återgår du automatiskt till den aktuella sidan. +Om du ännu inte är inloggad eller registrerad omdirigeras du automatiskt till inloggningssidan där du uppmanas att registrera dig och logga in. När det är klart återvänder du automatiskt till den aktuella sidan. -**En API Token kan anropa alla plattformens tjänster, utan att behöva ansöka separat för varje tjänst.** Vid första ansökan får du gratis kvot för en kostnadsfri testupplevelse; om kvoten inte räcker till kan du fylla på det allmänna saldot i [konsolen](https://platform.acedata.cloud/console/coin). +**En API Token kan anropa alla plattformstjänster, utan att du behöver ansöka separat för varje tjänst.** Vid den första ansökan får du gratis kredit för kostnadsfri testning; när krediten är otillräcklig kan du fylla på det gemensamma saldot i [konsolen](https://platform.acedata.cloud/console/coin). > 📘 Fullständig dokumentation: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) ## Grundläggande användning -Claude Messages API:s begärandesökväg är `/v1/messages`, vilket är samma som Anthropics officiella API. Vi behöver minst ange tre obligatoriska parametrar: +Claude Messages API:s förfrågningssökväg är `/v1/messages`, vilket överensstämmer med Anthropics officiella API. Vi behöver åtminstone ange tre obligatoriska parametrar: -- `model`: Välj Claude-modellen som ska användas. `claude-opus-5-5` tillhandahålls endast via Messages API, stöder 1 miljon Token-kontext, högst 128K Token i utdata och aktiverar alltid adaptivt tänkande. Den senaste flaggskeppsmodellen är `claude-fable-5-1` (1 miljon Token-kontext, högst 128K Token i utdata); den tidigare `claude-fable-5` behålls fortfarande för kompatibilitet. `claude-sonnet-5-5` har lagts till i den inbyggda Messages-seriens gränssnitt och stöder bildinmatning och adaptivt tänkande; dess officiella referenspriser för inmatning, utdata och cacheläsning är 2, 10 respektive 0,20 USD per miljon Token. -- `messages`: Arrayen med inmatade meddelanden, där varje meddelande innehåller `role` (roll) och `content` (innehåll), och `role` stöder `user` och `assistant`. -- `max_tokens`: Maximalt antal Token i utdata, används för att begränsa längden på ett enskilt svar. +- `model`: Välj Claude-modellen som ska användas. `claude-opus-5-5` erbjuds endast via Messages API, stöder 1 miljon Token kontext, maximalt utdata på 128K Token och har alltid adaptivt tänkande aktiverat. Den senaste flaggskeppsmodellen är `claude-fable-5-1` (1 miljon Token kontext, maximalt utdata på 128K Token); den tidigare `claude-fable-5` behålls fortfarande för kompatibilitet. `claude-sonnet-5-5` har lagts till i den inbyggda Messages-seriens gränssnitt och stöder bildinmatning och adaptivt tänkande; dess officiella referenspriser för indata, utdata och cacheläsning är 2, 10 respektive 0,20 USD per miljon Token. +- `messages`: Matrisen med inmatade meddelanden, där varje meddelande innehåller `role` (roll) och `content` (innehåll), och `role` stöder `user` och `assistant`. +- `max_tokens`: Maximalt antal token för utdata, används för att begränsa längden på ett enskilt svar. Vanliga valfria parametrar: - `system`: Systemprompt, används för att ange modellens beteende och roll. -- `temperature`: Slumpmässighet vid generering, mellan 0 och 1; ju högre värde, desto mer varierande blir svaret. -- `stream`: Om strömmande svar ska användas; om den anges som `true` kan en effekt av att returnera tecken för tecken uppnås. +- `temperature`: Genereringsslumpmässighet, mellan 0 och 1; ju högre värde, desto mer varierande blir svaren. +- `stream`: Om strömmande svar ska användas; ange `true` för att uppnå en effekt där resultatet returneras tecken för tecken. - `stop_sequences`: Anpassade stoppsekvenser; modellen slutar generera när den stöter på dessa texter. -- `top_p`: Parameter för kärnurval, används tillsammans med temperature för att styra slumpmässigheten i genereringen. -- `top_k`: Samplar endast bland de K alternativ som har högst sannolikhet. +- `top_p`: Parameter för kärnurval, som tillsammans med temperature styr slumpmässigheten i genereringen. +- `top_k`: Sampla endast bland de K alternativ med högst sannolikhet. - `tools`: Verktygsdefinitioner, används för att låta modellen anropa externa funktioner. - `tool_choice`: Styr hur modellen använder de tillhandahållna verktygen. -- `cache_control`: Skapar automatiskt en cachebrytpunkt vid det sista cachebara innehållsblocket i begäran; kan också skrivas på ett specifikt innehållsblock. +- `cache_control`: Skapa automatiskt en cachebrytpunkt vid det sista cachebara innehållsblocket i förfrågan; kan även skrivas på ett specifikt innehållsblock. +- `metadata`: Valfritt objekt för förfrågningsmetadata. `metadata.user_id` är en sträng och kan överföra en anpassad användaridentifierare från anroparen, till exempel `{"user_id":"example-user-001"}`; det rekommenderas att använda en stabil identifierare som inte innehåller personuppgifter. Den ersätter inte `Authorization`-autentisering och behöver inte skrivas in i konversationsinnehållet i `messages`. ### cURL-exempel @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -106,25 +109,25 @@ Efter anropet returneras resultatet enligt följande: } ``` -Beskrivning av fälten i returresultatet: - +Förklaring av fälten i returresultatet: - `id`: Den unika identifieraren för detta meddelande. - `type`: Alltid `message`. - `role`: Alltid `assistant`. -- `content`: Array med svarsinnnehåll, där varje element innehåller `type` (till exempel `text`) och motsvarande innehåll. +- `content`: En array med svarsinnnehåll, där varje element innehåller `type` (t.ex. `text`) och motsvarande innehåll. - `model`: Namnet på modellen som behandlar begäran. -- `stop_reason`: Orsak till stopp. Stabila värden inkluderar `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (det aktuella assistant-innehållet kan skickas tillbaka oförändrat för att fortsätta), `refusal` och `model_context_window_exceeded`. -- `stop_sequence`: Om genereringen stoppas på grund av en anpassad stoppsekvens visas den matchande texten för stoppsekvensen. -- `stop_details`: När `stop_reason` är `refusal` kan detta innehålla avslagskategori och beskrivning. -- `usage`: Token-användningsstatistik. `input_tokens` är ocachead inmatning; `cache_creation_input_tokens` och `cache_read_input_tokens` är cachelagring respektive cacheläsning; `output_tokens` är det totala antalet Token i utdata. Om `output_tokens_details.thinking_tokens` returneras är detta värde en delmängd av `output_tokens` och ska inte läggas till igen vid beräkning av total mängd eller kostnad. Denna detalj kan vara `null` eller utelämnas när någon auktoritativ räkning saknas. -- `usage.cache_creation`: Valfria TTL-detaljer för cachelagring, inklusive `ephemeral_5m_input_tokens` och `ephemeral_1h_input_tokens`. När objektet finns är summan av de två lika med `cache_creation_input_tokens`; att fältet är `null` eller utelämnas betyder att det aktuella svaret inte har någon tillgänglig TTL-uppdelning och får inte tolkas som `0`. -- `usage.cost`: Icke-strömmande svar kan innehålla ett objekt för kvotförbrukning som registrerats av Ace Data Cloud, där `amount` är den faktiska förbrukningen denna gång, `currency` är mätenheten och `list_amount` är beloppet före rabatt (om tillämpligt). Fable 5.1:s officiella grundpris för cacheläsning är $0.25 per miljon Token, och grundpriserna för 5-minuters- och 1-timmes-cachelagring är $12.50 respektive $20 per miljon Token; plattformens faktiska priser beräknas utifrån paketrabatter. +- `stop_reason`: Orsaken till stoppet. Stabila värden inkluderar `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (du kan returnera det aktuella assistant-innehållet oförändrat för att fortsätta), `refusal` och `model_context_window_exceeded`. +- `stop_sequence`: Om stoppet beror på en anpassad stoppsekvens visas den matchande stoppsekvenstexten. +- `stop_details`: När `stop_reason` är `refusal` kan detta innehålla en avslagskategori och en beskrivning. +- `usage`: Tokenanvändningsstatistik. `input_tokens` är ocachad indata; `cache_creation_input_tokens` och `cache_read_input_tokens` är cache-skrivning respektive cache-läsning; `output_tokens` är det totala antalet utdata-token. Om `output_tokens_details.thinking_tokens` returneras är detta värde en delmängd av `output_tokens`; lägg inte till det igen vid beräkning av total mängd eller kostnad. Denna detalj kan vara `null` eller utelämnas när det saknas en auktoritativ räkning. +- `usage.cache_creation`: Valfria TTL-detaljer för cache-skrivning, inklusive `ephemeral_5m_input_tokens` och `ephemeral_1h_input_tokens`. När objektet finns är summan av de två lika med `cache_creation_input_tokens`; ett fält som är `null` eller utelämnat innebär att den aktuella responsen inte har någon tillgänglig TTL-uppdelning och ska inte tolkas som `0`. +- `usage.cost`: Icke-strömmande svar kan innehålla ett objekt för förbrukade krediter som registrerats av Ace Data Cloud, där `amount` är den faktiska förbrukningen för denna gång, `currency` är måttenheten och `list_amount` är beloppet före rabatt (om tillämpligt). Fable 5.1:s officiella grundpris för cache-läsning är $0.25/miljon token, och grundpriserna för 5-minuters- och 1-timmes-cache-skrivning är $12.50 respektive $20/miljon token; plattformens faktiska pris beräknas enligt planrabatten. ## Systemprompt -Claude Messages API stöder inställning av systemprompt via fältet `system`, som används för att definiera modellens beteende, roll och kontext. +Claude Messages API stöder inställning av systempromptar via fältet `system`, som används för att definiera modellens beteende, roll och kontext. ### Python-exempel + ```python import requests @@ -149,11 +152,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Genom att ställa in system-prompten `system` kan du exakt styra Claudes roll och beteende. +Genom att ställa in `system`-prompten kan du exakt styra Claudes roll och beteende. ## Strömmande svar -Detta gränssnitt har även stöd för strömmande svar. Ställ bara parametern `stream` till `true` för att få en stegvis återgivning, vilket är mycket lämpligt för att implementera teckenvis visning på webbsidor. +Detta gränssnitt stöder också strömmande svar. Ställ bara in parametern `stream` till `true` för att få en stegvis retur, vilket är mycket lämpligt för att implementera teckenvis visning på webbsidor. ### Python-exempel @@ -183,16 +186,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Strömmande svar returneras i formatet Server-Sent Events (SSE), där varje rad har prefixet `event:` och `data:`. Typer av strömmande händelser omfattar: +Strömmande svar returneras i formatet Server-Sent Events (SSE), där varje rad har prefixen `event:` och `data:`. Typer av strömmande händelser inkluderar: -- `message_start`: Meddelandet börjar och innehåller meddelandets grundläggande information samt modellnamnet. +- `message_start`: Meddelandet börjar och innehåller grundläggande information om meddelandet och modellnamnet. - `content_block_start`: Innehållsblocket börjar. -- `content_block_delta`: Inkrementell uppdatering av innehållsblocket, som innehåller nyligen genererade textfragment. +- `content_block_delta`: Innehållsblockets inkrementella uppdatering, som innehåller den nyligen genererade textdelen. - `content_block_stop`: Innehållsblocket avslutas. -- `message_delta`: Inkrementell uppdatering på meddelandenivå, som innehåller `stop_reason` och slutlig `usage`-information. Det auktoritativa värdet för `output_tokens_details.thinking_tokens` ska endast läsas från den sista `message_delta.usage`; ackumulera inte över händelser. +- `message_delta`: Inkrementell uppdatering på meddelandenivå, som innehåller `stop_reason` och den slutliga `usage`-informationen. Det auktoritativa värdet för `output_tokens_details.thinking_tokens` ska endast läsas från den sista `message_delta.usage`; ackumulera inte över händelser. - `message_stop`: Meddelandet avslutas. -Utdataeffekten är följande: +Uteffekten är följande: ``` event: message_start @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Som du kan se innehåller händelsen `content_block_delta` i det strömmande svaret textinnehåll som genereras stegvis. Genom att sammanfoga alla `text_delta` kan du få det fullständiga svaret. +Som du kan se innehåller händelsen `content_block_delta` i strömmande svar det stegvis genererade textinnehållet, och du kan få det fullständiga svaret genom att sammanfoga alla `text_delta`. ### JavaScript-exempel @@ -253,7 +256,7 @@ while (true) { ## Fleromgångsdialog -Om du vill integrera funktionen för flersomgångsdialog behöver du ordna meddelanden med rollerna `user` och `assistant` växelvis i arrayen `messages` och skicka med den tidigare dialoghistoriken. +Om du vill ansluta funktionen för flergångsdialog måste du arrangera meddelanden med rollerna `user` och `assistant` växelvis i arrayen `messages` och skicka med den tidigare dialoghistoriken. ### Python-exempel @@ -283,7 +286,6 @@ print(response.json()) ``` Returresultatet är följande: - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -305,13 +307,13 @@ Returresultatet är följande: } ``` -Genom att skicka hela dialoghistoriken i `messages` kan Claude ge korrekta svar med hjälp av sammanhanget. +Genom att skicka den fullständiga konversationshistoriken i `messages` kan Claude ge korrekta svar med hjälp av kontexten. -## Modell för djupgående tänkande +## Modeller för djupgående tänkande Claudes thinking och thinking summary är två olika begrepp: modellen kan utföra intern slutledning, men API:et returnerar inte den ursprungliga tankekedjan. När slutledningsprocessen behöver visas returnerar API:et en bearbetad sammanfattning. -För den aktuella modellen rekommenderas adaptive thinking, och den övergripande slutledningsinsatsen styrs via `output_config.effort`: +För närvarande rekommenderas adaptivt tänkande för modeller, och den övergripande slutledningsinsatsen styrs via `output_config.effort`: ```python import requests @@ -350,26 +352,27 @@ Thinking-blocket i svaret ser ut så här: "signature": "opaque-signature" } ``` + - `display: "summarized"` returnerar en läsbar sammanfattning av tänkandet; det är inte den ursprungliga tankekedjan. -- `display: "omitted"` returnerar `thinking: ""`, men behåller fortfarande en opaque `signature` för att stödja efterföljande konversationer. -- `display: "updates"` är Anthropics beta-läge och kräver `anthropic-beta: thinking-display-updates-2026-08-18`. Den officiella definitionen är att dölja resonemangstexten och visa korta statusuppdateringar mellan verktygsanrop. Plattformen vidarebefordrar denna parameter och beta-begärandehuvudet enligt ursprungsvärdena och tvingar inte omskrivning till `summarized`; det faktiska utdata-innehållet beror på stödet hos den valda modellen. -- `thinking`, `output_config`, effort, samplingsparametrar och nya utökade fält vidarebefordras enligt ursprungsvärdena. Plattformen underhåller inte hårdkodade värdeuppräkningar eller kombinationsbegränsningar per modell och skriver inte heller automatiskt om thinking-läget; huruvida dessa parametrar accepteras avgörs av den valda modellen, och parameterfel som returneras av modellen skickas tillbaka till klienten. +- `display: "omitted"` returnerar `thinking: ""`, men behåller fortfarande den opaque `signature` för att stödja efterföljande konversationer. +- `display: "updates"` är Anthropics beta-läge och kräver `anthropic-beta: thinking-display-updates-2026-08-18`. Den officiella definitionen är att dölja slutledningens brödtext och visa korta statusuppdateringar mellan verktygsanrop. Plattformen vidarebefordrar denna parameter och beta-begärandehuvudet med deras ursprungliga värden och tvingar inte fram omskrivning till `summarized`; det faktiska utdata-innehållet beror på stödet i den valda modellen. +- `thinking`, `output_config`, effort, samplingsparametrar och nya utökade fält vidarebefordras med sina ursprungliga värden. Plattformen upprätthåller inte hårdkodade uppräkningar av värden eller kombinationsbegränsningar per modell, och skriver inte heller automatiskt om thinking-läget; huruvida dessa parametrar accepteras avgörs av den valda modellen, och parameterfel som returneras av modellen skickas vidare till klienten. - Standardvärdet för display för Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 och Opus 4.7 är `omitted`; Opus 4.6, Sonnet 4.6 och tidigare modeller som stöder thinking använder som standard `summarized`. -- Display påverkar endast retur-innehållet och strömningsfördröjningen, stänger inte av resonemang och minskar inte debiteringen för thinking-token. -- Huruvida thinking är aktiverat som standard och standardvärdet för display är två separata frågor. Opus 5 och Sonnet 5 aktiverar adaptive thinking som standard; för Opus 5 är utelämnad `thinking` likvärdigt med adaptive, och utelämnad `output_config.effort` likvärdigt med `high`. Opus 4.8, 4.7 och 4.6 kräver uttrycklig aktivering. -- Thinking och den slutliga brödtexten delar på utmatningsbudgeten `max_tokens`. När budgeten är för liten kan thinking använda större delen av utrymmet, vilket gör att brödtexten blir tom eller trunkerad; höj `max_tokens`, eller använd `low` / `medium` effort för att styra resonemangsinsatsen. +- Display påverkar endast det returnerade innehållet och fördröjningen vid streaming, och stänger inte av slutledning eller minskar debiteringen för thinking-token. +- Huruvida thinking är aktiverat som standard och display-standardvärdet är två separata frågor. Opus 5 och Sonnet 5 har adaptive thinking aktiverat som standard; för Opus 5 är utelämnande av `thinking` likvärdigt med adaptive, och utelämnande av `output_config.effort` likvärdigt med `high`. Opus 4.8, 4.7 och 4.6 kräver uttrycklig aktivering. +- Thinking och den slutliga brödtexten delar på utdata-budgeten `max_tokens`. Om budgeten är för liten kan thinking använda större delen av utrymmet, vilket gör att brödtexten blir tom eller avkortas; öka `max_tokens`, eller använd `low` / `medium` effort för att styra slutledningsinsatsen. - För modeller som tillåter att thinking stängs av kan `thinking: {"type":"disabled"}` skickas. Nya lägen som `between_tools` samt effort-kombinationer beror på den valda modellen; plattformen avvisar dem inte i förväg baserat på gamla modellregler. -- Fast tänkandebudget kan vidarebefordras med `budget_tokens`; nya modeller använder vanligtvis `thinking.type=adaptive` och `output_config.effort`. Huruvida fast budget eller avstängt tänkande stöds beror på den valda modellens aktuella kapacitet. -- Vid flervändningskonversationer och verktygsanrop ska det fullständiga thinking-blocket och signature som returneras av assistant skickas tillbaka oförändrade; ändra inte och generera inte signature själv. -- Parameter-vidarebefordran innebär inte att varje modell stöder alla funktioner. Anrop över protokoll kräver fortfarande konvertering, och stödomfånget samt fel för innehåll som `redacted_thinking` avgörs av den modelltjänst som faktiskt behandlar begäran. +- En fast tänkandebudget kan skickas via `budget_tokens`; nya modeller använder normalt `thinking.type=adaptive` och `output_config.effort`. Huruvida fast budget eller avstängning av tänkande stöds beror på den valda modellens aktuella kapacitet. +- Vid fleromgångskonversationer och verktygsanrop bör det fullständiga thinking-blocket och signature som returneras av assistant skickas tillbaka oförändrade; ändra inte eller generera själv signature. +- Parameter-vidarebefordring innebär inte att varje modell stöder alla funktioner. Anrop över protokoll kräver fortfarande konvertering, och omfattningen av stöd samt fel för innehåll såsom `redacted_thinking` avgörs av den modelltjänst som faktiskt behandlar begäran. -I strömmande begäranden producerar `summarized` `thinking_delta`; `omitted` producerar inte `thinking_delta`, utan behåller endast thinking-blockets livscykel och `signature_delta`. +I strömmande begäranden genererar `summarized` `thinking_delta`; `omitted` genererar inte `thinking_delta`, utan behåller endast thinking-blockets livscykel och `signature_delta`. ## Visuella modeller -Claude stöder multimodala indata och kan bearbeta text och bilder samtidigt. I Messages API kan visuella funktioner användas genom att ange `content` i arrayformat och skicka bildinnehållsblock. +Claude stöder multimodala indata och kan bearbeta text och bilder samtidigt. I Messages API kan visuella funktioner användas genom att ange `content` i array-format och skicka ett bildinnehållsblock. -### Använd Base64-kodade bilder +### Använda Base64-kodade bilder ```python import base64 @@ -415,7 +418,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -### Använd URL-bilder +### Använda URL-bilder ```python import requests @@ -456,7 +459,6 @@ print(response.json()) ``` ### cURL-exempel - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -486,11 +488,11 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ }' ``` -Bildformat som stöds omfattar: `image/jpeg`, `image/png`, `image/gif`, `image/webp`. +Bildformat som stöds inkluderar: `image/jpeg`, `image/png`, `image/gif` och `image/webp`. ## Dokument och PDF -PDF använder innehållsblocket `document` och stöder de två stabila källorna Base64 och URL. Base64-källor måste använda `application/pdf`: +PDF använder innehållsblocket `document` och stöder två stabila källor: Base64 och URL. Base64-källor måste använda `application/pdf`: ```python import base64 @@ -519,7 +521,7 @@ payload = { } ``` -URL-källan skrivs som `{"type":"url","url":"https://example.com/report.pdf"}`. `document` stöder även `text/plain` och `content`-källor som består av text/image-block; valfria fält omfattar `title`, `context` och `citations`. `file_id`-källan i Files API är en separat beta-funktion och ingår inte i detta gränssnitts stabila kontrakt. +URL-källor skrivs som `{"type":"url","url":"https://example.com/report.pdf"}`. `document` stöder även `text/plain` och `content`-källor som består av text-/image-block; valfria fält inkluderar `title`, `context` och `citations`. Files API:s `file_id`-källa tillhör en separat beta-funktion och ingår inte i detta API:s stabila kontrakt. ## Promptcache @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -När exakt positionskontroll krävs kan samma `cache_control` även skrivas på innehållsblocken text, image, document, tool_use, tool_result eller på verktygsdefinitionen. `ttl` stöder `5m` (standard) och `1h`; avgör cache-skrivning och träffar via `usage.cache_creation_input_tokens` och `usage.cache_read_input_tokens`. -När svaret tillhandahåller `usage.cache_creation` gäller att `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Om `cache_creation` är `null` eller utelämnas betyder det att det endast finns en total mängd för cache-skrivning och ingen auktoritativ TTL-uppdelning; behandla då inte någon bucket som ett känt värde på 0, och fakturering och total mängd ska fortfarande baseras på aggregate-fältet. +När exakt kontroll över placeringen behövs kan samma `cache_control` även skrivas på innehållsblocken text, image, document, tool_use och tool_result eller på verktygsdefinitioner. `ttl` stöder `5m` (standard) och `1h`; använd `usage.cache_creation_input_tokens` och `usage.cache_read_input_tokens` för att avgöra cacheskrivning och cacheträffar. + +När svaret tillhandahåller `usage.cache_creation` gäller att `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Om `cache_creation` är `null` eller utelämnas betyder det att endast den totala mängden cacheskrivning finns tillgänglig, utan en auktoritativ TTL-uppdelning; betrakta då inte någon bucket som ett känt värde på 0, utan fakturering och totaler baseras fortfarande på aggregatfältet. -Exempel på returresultat: +Exempel på returnerat resultat: ```json { @@ -563,7 +566,7 @@ Exempel på returresultat: ## Verktygsanrop (Tool Use) -Claude Messages API har inbyggt stöd för verktygsanrop, vilket gör det möjligt för modellen att vid behov anropa dina fördefinierade verktyg/funktioner. +Claude Messages API har inbyggt stöd för verktygsanrop, vilket gör att modellen kan anropa dina fördefinierade verktyg/funktioner vid behov. ### Python-exempel @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -När modellen beslutar att anropa ett verktyg kommer `content` i returresultatet att innehålla ett innehållsblock av typen `tool_use`: +När modellen beslutar att anropa ett verktyg kommer `content` i det returnerade resultatet att innehålla ett innehållsblock av typen `tool_use`: ```json { @@ -637,7 +640,7 @@ När modellen beslutar att anropa ett verktyg kommer `content` i returresultatet } ``` -Observera att `stop_reason` är `tool_use`, vilket anger att modellen behöver anropa verktyget. När du har tagit emot detta resultat behöver du köra verktygsfunktionen och skicka tillbaka resultatet till modellen i form av `tool_result`: +Observera att `stop_reason` är `tool_use`, vilket indikerar att modellen behöver anropa verktyget. När du har tagit emot resultatet behöver du köra verktygsfunktionen och skicka tillbaka resultatet till modellen i form av `tool_result`: ```python payload = { @@ -685,36 +688,35 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Modellen kommer att generera det slutliga svaret på naturligt språk baserat på resultatet som returneras av verktyget. +Modellen genererar ett slutligt svar på naturligt språk baserat på resultatet som verktyget returnerar. -## Skillnader jämfört med Chat Completion API +## Skillnader från Chat Completion API -Ace Data Cloud erbjuder samtidigt två Claude API-format, och de huvudsakliga skillnaderna mellan dem är följande: - -I Messages API representerar `usage.input_tokens` endast ocachad indata, medan `cache_read_input_tokens` och `cache_creation_input_tokens` är separata faktureringsbuckets; alla tre beräknas separat enligt respektive pris. +Ace Data Cloud erbjuder samtidigt två Claude API-format, med följande huvudsakliga skillnader: +Messages API:s `usage.input_tokens` representerar endast ocachad indata, medan `cache_read_input_tokens` och `cache_creation_input_tokens` är separata faktureringsbucketar; alla tre beräknas separat enligt respektive pris. | Funktion | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | -| Format | Anthropic-format i original | OpenAI-kompatibelt format | -| Systemprompt | Separat `system`-fält | Skickas via `role: "system"` i `messages` | -| Svarsstruktur | `content`-array (stöder flera typer) | `choices`-array (innehåller `message`) | -| Strömmande format | SSE-händelser (flera händelsetyper) | SSE `data`-rader | -| Djupgående tänkande | Inbyggd `thinking` och `output_config.effort` | Modellens standardstrategi och kompatibilitetsparametrar | -| Verktygsanrop | Inbyggda `tools` + `input_schema` | OpenAI-kompatibelt `tools`-format | +| Format | Anthropic-nativt format | OpenAI-kompatibelt format | +| Systemprompt | Separat fält `system` | Skickas via `role: "system"` i `messages` | +| Svarsstruktur | Arrayen `content` (stöder flera typer) | Arrayen `choices` (innehåller `message`) | +| Strömmande format | SSE-händelser (flera händelsetyper) | SSE-rader med `data` | +| Djupgående tänkande | Native `thinking` och `output_config.effort` | Modellens standardstrategi och kompatibilitetsparametrar | +| Verktygsanrop | Native `tools` + `input_schema` | OpenAI-kompatibelt `tools`-format | | Tokenstatistik | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Om ditt system redan är integrerat med API:t i OpenAI-format kan du använda Chat Completion API för en sömlös övergång. Om du behöver använda alla Claudes inbyggda funktioner rekommenderas Messages API. +Om ditt system redan är integrerat med ett API i OpenAI-format kan du använda Chat Completion API för att växla sömlöst. Om du behöver använda alla Claudes native funktioner rekommenderas Messages API. ## Felhantering -Felsvar från det offentliga gränssnittet använder Ace Data Clouds plattforms-envelope: `error.code` är en stabil felkod, `error.message` är en beskrivning och `trace_id` används för att felsöka förfrågningar. Vanliga HTTP-statusar inkluderar: +Felsvar för offentliga gränssnitt använder Ace Data Cloud-plattformens envelope: `error.code` är en stabil felkod, `error.message` är en beskrivning och `trace_id` används för att felsöka begäran. Vanliga HTTP-statusar inkluderar: -- `400`: Begäransparametrar eller protokollinnehåll är ogiltiga. -- `401`: Auktoriseringstoken är ogiltig, saknas eller har löpt ut. -- `403`: Åtkomst förbjuden, otillräckligt saldo eller kvotbegränsning. -- `404`: API:t eller modellen finns inte. +- `400`: Begärandeparametrarna eller protokollinnehållet är ogiltigt. +- `401`: Auktoriseringstoken är ogiltig, saknas eller har gått ut. +- `403`: Åtkomst förbjuden, otillräckligt saldo eller begränsad kvot. +- `404`: API:et eller modellen finns inte. - `413`: Begärandetexten är för stor. -- `429`: För många förfrågningar. +- `429`: För många begäranden. - `500` / `503` / `504`: Tjänstfel, tillfälligt otillgänglig eller bearbetningstimeout. ### Exempel på felsvar @@ -732,4 +734,5 @@ Felsvar från det offentliga gränssnittet använder Ace Data Clouds plattforms- Denna felstruktur är Ace Data Clouds körtidskontrakt och motsvarar inte Anthropics officiella fel-envelope; hantera den enligt HTTP-status och `error.code`. ## Slutsats -Genom detta dokument har du redan lärt dig hur du använder Claude Messages API för att anropa Claudes konversationsfunktioner i Anthropic:s ursprungliga format. Messages API stöder omfattande funktioner såsom grundläggande konversationer, systempromptar, strömmande svar, flerrundskonversationer, djupt tänkande, visuell förståelse, PDF-filer, promptcachelagring och verktygsanrop. Om du har några frågor är du välkommen att kontakta vårt tekniska supportteam när som helst. + +Genom detta dokument har du lärt dig hur du använder Claude Messages API för att anropa Claudes konversationsfunktioner i Anthropic-nativt format. Messages API stöder omfattande funktioner såsom grundläggande konversationer, systemprompter, strömmande svar, flervägskonversationer, djupgående tänkande, visuell förståelse, PDF:er, promptcache och verktygsanrop. Om du har några frågor är du välkommen att kontakta vårt tekniska supportteam när som helst. diff --git a/sv/guides/openai/openai_embeddings.mdx b/sv/guides/openai/openai_embeddings.mdx index 29bd54311..051a71cfb 100644 --- a/sv/guides/openai/openai_embeddings.mdx +++ b/sv/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API Ansökan och Användning" +title: "Ansökan och användning av OpenAI Embeddings API" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI ordvektortjänst, som används för att generera ordvektorer som representerar inmatad text. +OpenAI:s ordinbäddningstjänst används för att generera ordinbäddningsresultat som representerar inmatad text. -Detta dokument beskriver huvudsakligen användningsflödet för OpenAI Embeddings API, där vi kan skapa inbäddade vektorer som representerar inmatad text. +Detta dokument introducerar främst användningsprocessen för OpenAI Embeddings API. Med hjälp av det kan vi skapa inbäddningsvektorer som representerar inmatad text。。 ## Ansökningsprocess -För att använda OpenAI Embeddings API, börja med att gå till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att hämta din API-token, som du kan spara för framtida bruk. +För att använda OpenAI Embeddings API, gå först till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att hämta din API-token och spara den för senare användning. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Om du inte har loggat in eller registrerat dig, kommer du automatiskt att omdirigeras till inloggningssidan där du uppmanas att registrera dig och logga in, och efter att ha slutfört detta kommer du automatiskt att återvända till den aktuella sidan. +Om du ännu inte har loggat in eller registrerat dig, omdirigeras du automatiskt till inloggningssidan där du uppmanas att registrera dig och logga in. När det är klart återgår du automatiskt till den aktuella sidan. -**En API-token räcker för att anropa alla tjänster på plattformen, du behöver inte ansöka separat för varje tjänst.** Första gången du ansöker får du en gratis kvot för att prova; om kvoten tar slut kan du ladda på allmän balans i [konsolen](https://platform.acedata.cloud/console/coin). +**En API-token kan anropa alla tjänster på plattformen, utan att behöva ansöka separat för varje tjänst.** Vid första ansökan får du gratis kredit för att kunna prova tjänsten kostnadsfritt; när krediten inte räcker till kan du ladda på ett gemensamt saldo i [konsolen](https://platform.acedata.cloud/console/coin). > 📘 Fullständig dokumentation: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## Grundläggande Användning +## Grundläggande användning -Nu kan du fylla i motsvarande innehåll på gränssnittet, som visas i bilden: +Därefter kan du fylla i motsvarande innehåll i gränssnittet, som visas i bilden:

-Vid första användning av detta gränssnitt behöver vi fylla i minst tre fält, ett är `authorization`, som du enkelt väljer från rullgardinsmenyn. Den andra parametern är `model`, `model` är den vi väljer att använda från OpenAI:s officiella modellkategorier, här har vi huvudsakligen 3 modeller, detaljer kan ses i de modeller vi tillhandahåller. Den sista parametern är `input`, `input` är den text vi behöver konvertera till ordvektorer. +När vi använder detta gränssnitt för första gången behöver vi minst fylla i tre delar. Den ena är `authorization`, som kan väljas direkt i rullgardinslistan. En annan parameter är `model`; `model` är den officiella OpenAI-modellkategori vi väljer att använda. De modeller som för närvarande är tillgängliga är `text-embedding-3-small` och `text-embedding-3-large`. `text-embedding-ada-002` erbjuds inte längre; om ett befintligt vektorindex använder denna äldre modell kan det inte direkt blandas med vektorer från de nya modellerna, utan indexet måste byggas om. Den sista parametern är `input`, och `input` är den text som vi behöver omvandla till ordinbäddningar. -Samtidigt kan du notera att det finns motsvarande anropskod som genereras till höger, du kan kopiera koden och köra den direkt, eller klicka på "Try" knappen för att testa. +Samtidigt kan du se att det finns motsvarande genererad anropskod till höger. Du kan kopiera koden och köra den direkt, eller klicka direkt på knappen ”Try” för att testa. Valfria parametrar: -- `dimensions`: Beskär vektordimensioner, standardutgången är full dimension. -- `encoding_format`: Återvändande format, valfritt `float` eller `base64`. +- `dimensions`: beskär vektordimensioner, fullständig dimension returneras som standard. +- `encoding_format`: returformat, kan vara `float` eller `base64`.

-Python exempel på anropskod: +Exempel på Python-anropskod: ```python import requests @@ -50,8 +50,8 @@ headers = { } payload = { - "input": "Maten var utsökt och servitören...", - "model": "text-embedding-ada-002", + "input": "The food was delicious and the waiter...", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Efter anropet upptäckte vi att returresultatet ser ut som följer: +Efter anropet ser vi att returresultatet är följande: ```json { @@ -97,7 +97,7 @@ Efter anropet upptäckte vi att returresultatet ser ut som följer: ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,32 +105,32 @@ Efter anropet upptäckte vi att returresultatet ser ut som följer: } ``` -Returresultatet innehåller flera fält, som beskrivs nedan: +Returresultatet har flera fält, som introduceras nedan: -- `model`, modellen som användes för att konvertera text till ordvektorer. -- `usage`, tokeninformation som användes för att konvertera text till ordvektorer. -- `data`, resultatet av textens konvertering till ordvektorer. +- `model`, modellen som används för att omvandla denna text till ordinbäddningar. +- `usage`, tokeninformationen som används för att omvandla denna text till ordinbäddningar. +- `data`, resultatet av ordinbäddningarna efter textomvandlingen. -Där `data` innehåller den specifika informationen om ordvektorerna som motsvarar texten, där `embedding` är det genererade resultatet av ordvektorer. +Bland dessa är `data` den specifika informationen som innehåller ordinbäddningarna som motsvarar texten, och dess `embedding` är det specifika genererade resultatet för ordinbäddningarna. ## Felhantering -Vid anrop av API:et, om ett fel uppstår, kommer API:et att returnera motsvarande felkod och information. Till exempel: +Vid anrop av API:t, om ett fel uppstår, returnerar API:t motsvarande felkod och information. Till exempel: -- `400 token_mismatched`: Felaktig begäran, möjligtvis på grund av saknade eller ogiltiga parametrar. -- `400 api_not_implemented`: Felaktig begäran, möjligtvis på grund av saknade eller ogiltiga parametrar. -- `401 invalid_token`: Obefogad, ogiltig eller saknad auktoriseringstoken. -- `429 too_many_requests`: För många begärningar, du har överskridit hastighetsgränsen. -- `500 api_error`: Intern serverfel, något gick fel på servern. +- `400 token_mismatched`: Felaktig begäran, möjligen på grund av saknade eller ogiltiga parametrar. +- `400 api_not_implemented`: Felaktig begäran, möjligen på grund av saknade eller ogiltiga parametrar. +- `401 invalid_token`: Obehörig, ogiltig eller saknad auktoriseringstoken. +- `429 too_many_requests`: För många begäranden, du har överskridit hastighetsgränsen. +- `500 api_error`: Internt serverfel, något gick fel på servern. -### Exempel på felrespons +### Exempel på felsvar ```json { "success": false, "error": { "code": "api_error", - "message": "hämtning misslyckades" + "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } @@ -138,4 +138,4 @@ Vid anrop av API:et, om ett fel uppstår, kommer API:et att returnera motsvarand ## Slutsats -Genom detta dokument har du fått en förståelse för hur du enkelt kan använda OpenAI Embeddings API för att använda den officiella OpenAI:s funktion för att generera ordvektorer. Vi hoppas att detta dokument kan hjälpa dig att bättre integrera och använda detta API. Om du har några frågor, tveka inte att kontakta vårt tekniska supportteam. +Genom detta dokument har du redan förstått hur du använder OpenAI Embeddings API för att enkelt använda den officiella OpenAI-funktionen för generering av ordinbäddningar. Vi hoppas att detta dokument kan hjälpa dig att bättre integrera och använda detta API. Om du har några frågor, kontakta gärna vårt tekniska supportteam när som helst. diff --git a/sv/guides/platform/wework_bot.mdx b/sv/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..a06a165ae --- /dev/null +++ b/sv/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "WeCom-robot" +description: "Platform API guide - Ace Data Cloud" +--- + +Distribuera din egen WeCom-kontoinstans, logga in genom att skanna QR-koden med WeCom på mobilen och läs kontot, kontakter, konversationer och lokalt synkroniserade meddelanden via REST API eller MCP. Instansen motsvarar ett vanligt WeCom-konto och kräver varken en privat server eller konfiguration av företagsdomän för e-post. + +För närvarande Alpha. Kontoläsning har slutfört verklig konversationsverifiering; textsändning av kontoinnehavaren och återläsning av händelser har slutfört verklig acceptanstestning; andra kontakter, gruppåtgärder och återställning av nya instanser behöver fortfarande genomföra acceptanstestning i distributionsmiljön. Mediesändning, citerade svar, verkliga @-omnämnanden, hantering av gruppmedlemmar och leveranskvitton är ännu inte tillgängliga. Utgå från returvärdet för instansens `/api/capabilities`. + +## Distribution och inloggning + +Aktivera tjänsten i kategorin Deployment och välj ett instanspaket med tidsperiod. Efter distributionen öppnar du administrationssidan och skannar QR-koden med WeCom för själva kontot; om mobilbekräftelse eller andra inloggningssteg krävs öppnar du fjärrskrivbordet och anger skrivbordslösenordet för den instansen. API-autentiseringsuppgifter och skrivbordslösenord är separata. Inloggningsdata sparas på instansdisken; om behållaren återskapas bevaras disken; om disken tas bort raderas den lokala sessionen. + +Varje instans debiteras separat och körs under den köpta tidsperioden. REST-/MCP-anrop debiteras inte separat per meddelande, och det faktiska priset gäller enligt paketsidan. För närvarande används som standard tidsperiodspaket för WeChat-robotar som referens, och prissättningen behöver slutligt bekräftas utifrån körresurserna innan offentlig lansering. + +## API och MCP + +Använd instansens API-adress på administrationssidan och inkludera `Authorization: Bearer ` i alla kontoanrop. Dessa sökvägar tillhör den dedikerade instansen och är inte en delad API-gateway. MCP-adressen är instansadressen med `/mcp/` tillagd och använder samma Bearer-token. + +| Gränssnitt | Funktion | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Om kontot är redo och kapacitetslista | +| `GET /api/auth/qr` | Aktuell PNG Base64 för inloggnings-QR-kod | +| `GET /api/account` | Aktuellt konto | +| `GET /api/contacts?kind=all` | Interna kollegor och externa kontakter, kan ange internal / external | +| `GET /api/conversations` | Lokala konversationer, behåller ursprungliga konversations-ID:n | +| `GET /api/messages` | Lokalt synkroniserade meddelanden; parametrarna conversation_id, after_rowid, limit | +| `POST /api/search` | Sökning av kontakter, konversationer och lokal text | +| `POST /api/messages` | Asynkron uppgift för textsändning, måste ange Idempotency-Key | +| `POST /api/messages/send` | Samma sändningsingång, stöder ett eller flera mål | +| `GET /api/groups/{conversation_id}` | Lokalt synkroniserad gruppinformation och medlemmar | +| `GET /api/tasks` | Senaste uppgifter och resultat för varje mål | +| `GET /api/tasks/{id}` | Hämta sändningsresultat | +| `POST /api/tasks/{id}/cancel` | Avbryt uppgifter som ännu inte har påbörjats | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Pausa automatisering; återuppta efter verifiering av kontoinnehavaren | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Instansstatus och aktuell skärmbild, båda kräver autentisering | +| `GET /api/events?after=0` | Meddelandehändelser med återställbar markör | +| `WS /ws` | Händelseström för meddelanden, Bearer-autentisering | + +Sändningskroppen innehåller `target`, `type: "text"` och `text`. `target` accepterar konversations-ID, kontakt-ID, företagsanvändar-ID eller ett unikt fullständigt namn; använd ID i första hand; om visningsnamnet fortfarande inte kan identifiera ett mål unikt avvisar instansen åtgärden och gissar inte objektet. För kontakter utan lokal konversation öppnas först konversationen via klienten, och meddelandet skickas efter att det faktiska konversations-ID:t har kontrollerats. Begärandehuvudet `Idempotency-Key` består av 8–128 bokstäver, siffror eller `_.:-`. Upprepade begäranden för samma åtgärd måste återanvända samma nyckel och samma begärandekropp. + +Genom att ersätta `target` med arrayen `targets` kan du skicka seriellt till 1–50 uttryckligen angivna mål. Båda kan inte anges samtidigt. Alla mål slutför identitetsupplösning först, och olika alias som pekar på samma objekt avvisas. Efter att ett mål misslyckas stoppas efterföljande sändningar, och uppgiftsresultatet registrerar per objekt `succeeded`, `failed`, `unknown` eller `not_attempted`; behandla inte partiell framgång som fullständig framgång. Detta flöde behöver även slutföra verklig acceptanstestning av angivna kontakter i distributionsmiljön. + +Uppgifter kan vara i tillstånden queued, running, submitting, succeeded, failed, unknown eller cancelled. `succeeded` betyder att exakt text och servermeddelande-ID hittades i motsvarande konversationspost efter inskickning, `delivered` är fortfarande null och betyder inte att motparten har mottagit det. unknown betyder att resultatet är oklart; kontrollera historiken och upprepa inte sändningen med en ny nyckel. Instansen skickar inte automatiskt om avbrutna uppgifter. + +Historiken innehåller endast innehåll som klienten redan har synkroniserat och kan inte garantera fullständig historik. Icke-textmeddelanden kan returnera typen unknown, och nedladdning av bilagor är ännu inte tillgänglig. Händelser behåller de senaste 10 000 posterna, och `gap` betyder att markören redan har överskridit bevarandefönstret. Den första anslutningen spelar inte upp gammal historik som nya meddelanden. + +`server_accepted` och `server_id` i meddelandehistoriken kan användas för att kontrollera om servern har accepterat det lokala meddelandet; om endast en lokal post visas utan server-ID kan sändningen inte anses lyckad. Dessa fält betyder inte att mottagaren har tagit emot eller läst meddelandet. Händelseposter bevarar statusen vid tidpunkten då de skapades; använd meddelandehistorikens gränssnitt för att fråga aktuell bekräftelsestatus. + +## Konto och autentiseringsuppgifter + +Logga endast in på konton som du själv har rätt att använda. Konfigurera API-token i betrodda applikationer; den kan komma åt kontodata för den instansen. Publicera inte lösenord, QR-koder eller chattskärmbilder på offentliga platser. Att pausa instansen avbryter realtidshändelser. Om kontot loggas ut eller enheten tas bort från mobilen måste du logga in igen. + +Aktuell textinmatning stöder endast en rad; radbrytningar avvisas uttryckligen före sändning. När klienten kräver säkerhetsverifiering eller ny inloggning ska kontoinnehavaren slutföra detta via fjärrskrivbordet; instansen kringgår inte verifieringen. Uppgifter efter ett avbrott i verifieringen kan returnera unknown; kontrollera först meddelandeposten och skicka inte igen med en ny idempotensnyckel. + +När en säkerhetsverifieringsprompt, kontoutloggning eller ändring identifieras pausas automatiseringskön permanent. När mobilverifieringen har slutförts kan du fortsätta uppgifter som ännu inte har körts via ”Återuppta efter verifiering” i instanskonsolen; uppgifter som redan har skickats in men har osäkra resultat skickas inte igen. Normalt distansarbete kan också utlösa WeCom-säkerhetsverifiering. Det fönster på 24 timmar efter verifiering då låsning inte sker enligt officiell dokumentation betyder inte att detektering redan har eliminerats, och betyder inte heller att instansen kan garantera långvarig obevakad drift. diff --git a/uk/guides/claude/claude_messages.mdx b/uk/guides/claude/claude_messages.mdx index cbfa7b840..570d2c919 100644 --- a/uk/guides/claude/claude_messages.mdx +++ b/uk/guides/claude/claude_messages.mdx @@ -1,21 +1,21 @@ --- -title: "Заявка та використання Claude Messages API" +title: "Подання заявки та використання Claude Messages API" description: "Claude AI API guide - Ace Data Cloud" --- -Anthropic Claude — це надзвичайно потужна система AI-діалогів: достатньо ввести промпт, і вона зможе за кілька секунд згенерувати плавну та природну відповідь. Claude Messages API — це офіційний нативний формат API від Anthropic. На відміну від формату, сумісного з OpenAI (Chat Completion), він використовує власну структуру запитів і відповідей Anthropic, що дає змогу краще використовувати унікальні можливості Claude, такі як мультимодальне введення контенту, виклик інструментів, глибоке мислення (Extended Thinking) та інші розширені функції. +Anthropic Claude — це дуже потужна система AI-діалогів, яка може генерувати плавні й природні відповіді всього за кілька секунд після введення підказки. Claude Messages API — це офіційний нативний формат API Anthropic. На відміну від формату, сумісного з OpenAI (Chat Completion), він використовує власну структуру запитів і відповідей Anthropic, що дає змогу краще використовувати унікальні можливості Claude, такі як мультимодальне введення контенту, виклик інструментів, глибоке мислення (Extended Thinking) та інші розширені функції. -Цей документ переважно описує процес використання операцій Claude Messages API. За його допомогою ми можемо використовувати нативний інтерфейс, узгоджений з офіційним Anthropic, для виклику діалогових функцій Claude. +У цьому документі переважно описано процес використання операцій Claude Messages API. За його допомогою ми можемо використовувати нативний інтерфейс, узгоджений з офіційним Anthropic, для виклику функції діалогу Claude. ## Процес подання заявки -Щоб використовувати Claude Messages API, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token, і збережіть його для подальшого використання. +Щоб використовувати Claude Messages API, спочатку отримайте ваш API Token у [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) і збережіть його для подальшого використання. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Якщо ви ще не увійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення ви автоматично повернетеся на поточну сторінку. +Якщо ви ще не ввійшли або не зареєструвалися, вас буде автоматично перенаправлено на сторінку входу, де буде запропоновано зареєструватися та ввійти. Після завершення ви автоматично повернетеся на поточну сторінку. -**Один API Token дає змогу викликати всі сервіси платформи, без необхідності подавати окрему заявку для кожного сервісу.** Під час першої заявки надається безкоштовний ліміт для безкоштовного ознайомлення; якщо ліміту недостатньо, ви можете поповнити універсальний баланс у [консолі](https://platform.acedata.cloud/console/coin). +**Один API Token дає змогу викликати всі сервіси платформи, не потрібно подавати окрему заявку для кожного сервісу.** Під час першого подання заявки надається безкоштовний ліміт, яким можна безкоштовно скористатися; якщо ліміту недостатньо, ви можете поповнити загальний баланс у [консолі](https://platform.acedata.cloud/console/coin). > 📘 Повна документація: [Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) @@ -23,21 +23,22 @@ Anthropic Claude — це надзвичайно потужна система A Шлях запиту Claude Messages API — `/v1/messages`, що відповідає офіційному API Anthropic. Нам потрібно надати щонайменше три обов’язкові параметри: -- `model`: вибір моделі Claude для використання. `claude-opus-5-5` надається лише через Messages API, підтримує контекст у 1 мільйон Token, максимальний вивід 128K Token і завжди активує адаптивне мислення. Найновішим флагманом є `claude-fable-5-1` (контекст у 1 мільйон Token, максимальний вивід 128K Token); попередній `claude-fable-5` усе ще збережено для сумісності. `claude-sonnet-5-5` додано до нативних інтерфейсів серії Messages, він підтримує введення зображень і адаптивне мислення; його офіційні довідкові ціни за введення, виведення та читання кешу становлять відповідно 2, 10 і 0,20 долара США за мільйон Token. -- `messages`: масив вхідних повідомлень, де кожне повідомлення містить `role` (роль) і `content` (вміст), а `role` підтримує `user` та `assistant`. +- `model`: вибір моделі Claude для використання. `claude-opus-5-5` надається лише через Messages API, підтримує контекст у 1 мільйон Token, максимальний вихід 128K Token і завжди активує адаптивне мислення. Найновіша флагманська модель — `claude-fable-5-1` (контекст у 1 мільйон Token, максимальний вихід 128K Token); попередня `claude-fable-5` усе ще збережена для сумісності. `claude-sonnet-5-5` додано до нативного інтерфейсу серії Messages, вона підтримує введення зображень і адаптивне мислення; її офіційні довідкові ціни за введення, виведення та читання кешу становлять відповідно 2, 10 і 0,20 долара США за мільйон Token. +- `messages`: масив вхідних повідомлень, де кожне повідомлення містить `role` (роль) і `content` (вміст), а `role` підтримує `user` і `assistant`. - `max_tokens`: максимальна кількість вихідних token, що використовується для обмеження довжини однієї відповіді. Поширені необов’язкові параметри: -- `system`: системний промпт, що використовується для налаштування поведінки та ролі моделі. +- `system`: системна підказка, що використовується для налаштування поведінки та ролі моделі. - `temperature`: випадковість генерації, від 0 до 1; що більше значення, то більш розгалуженою буде відповідь. -- `stream`: чи використовувати потокову відповідь; встановлення `true` дає змогу реалізувати ефект посимвольного повернення. -- `stop_sequences`: користувацькі послідовності зупинки; модель припинить генерацію, коли зустріне цей текст. +- `stream`: чи використовувати потокову відповідь; встановлення значення `true` дає змогу реалізувати ефект посимвольного повернення. +- `stop_sequences`: користувацькі послідовності зупинки; модель припиняє генерацію, коли зустрічає цей текст. - `top_p`: параметр ядерної вибірки, що разом із temperature контролює випадковість генерації. - `top_k`: вибірка лише з K варіантів із найвищою ймовірністю. - `tools`: визначення інструментів, що використовуються для виклику моделлю зовнішніх функцій. - `tool_choice`: контролює, як модель використовує надані інструменти. -- `cache_control`: автоматично створює точку зупинки кешу на останньому кешованому блоці вмісту запиту; також може бути записаний у конкретному блоці вмісту. +- `cache_control`: автоматично створює контрольну точку кешу в останньому кешованому блоці вмісту запиту; також може бути записаний у конкретному блоці вмісту. +- `metadata`: необов’язковий об’єкт метаданих запиту. `metadata.user_id` є рядком і може передавати користувацький ідентифікатор користувача від сторони, що викликає, наприклад `{"user_id":"example-user-001"}`; рекомендується використовувати стабільний ідентифікатор, що не містить персональної інформації. Він не замінює автентифікацію `Authorization` і його також не потрібно записувати у вміст діалогу `messages`. ### Приклад cURL @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -83,7 +86,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Після виклику результат, що повертається, має такий вигляд: +Після виклику результат повертається таким: ```json { @@ -107,24 +110,24 @@ print(response.json()) ``` Опис полів результату, що повертається: - -- `id`: унікальний ідентифікатор цього повідомлення. -- `type`: завжди `message`. -- `role`: завжди `assistant`. -- `content`: масив вмісту відповіді, де кожен елемент містить `type` (наприклад, `text`) і відповідний вміст. -- `model`: назва моделі, що обробляє запит. -- `stop_reason`: причина зупинки. Стабільні значення включають `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`, `pause_turn` (можна передати поточний вміст assistant без змін, щоб продовжити), `refusal` і `model_context_window_exceeded`. -- `stop_sequence`: якщо зупинка сталася через користувацьку послідовність зупинки, відображається текст відповідної послідовності зупинки. -- `stop_details`: коли `stop_reason` має значення `refusal`, може містити категорію та пояснення відмови. -- `usage`: статистика використання token. `input_tokens` — це некешоване введення; `cache_creation_input_tokens` і `cache_read_input_tokens` — відповідно запис і читання кешу; `output_tokens` — це загальна кількість вихідних token. Якщо повертається `output_tokens_details.thinking_tokens`, це значення є підмножиною `output_tokens`; не додавайте його повторно під час обчислення загальної кількості чи вартості. Ця деталізація може бути `null` або бути пропущена, коли немає авторитетного підрахунку. -- `usage.cache_creation`: необов’язкова деталізація TTL запису кешу, що містить `ephemeral_5m_input_tokens` і `ephemeral_1h_input_tokens`. Коли об’єкт існує, сума двох значень дорівнює `cache_creation_input_tokens`; якщо поле має значення `null` або пропущене, це означає, що в поточній відповіді немає доступного розподілу TTL, і його не можна інтерпретувати як `0`. -- `usage.cost`: непотокова відповідь може містити об’єкт споживання ліміту, записаний Ace Data Cloud, де `amount` — фактичне споживання цього разу, `currency` — одиниця вимірювання, а `list_amount` — сума до знижки (за наявності). Офіційна базова ціна читання кешу Fable 5.1 становить $0.25/мільйон Token, а базові ціни запису кешу на 5 хвилин і 1 годину становлять відповідно $12.50 та $20/мільйон Token; фактична ціна платформи розраховується відповідно до знижки тарифного плану. - -## Системний промпт - -Claude Messages API підтримує налаштування системного промпту через поле `system`, що використовується для визначення поведінки, ролі та контексту моделі. +- `id`：унікальний ідентифікатор цього повідомлення. +- `type`：завжди `message`. +- `role`：завжди `assistant`. +- `content`：масив вмісту відповіді, кожен елемент містить `type` (наприклад, `text`) і відповідний вміст. +- `model`：назва моделі, що обробляє запит. +- `stop_reason`：причина зупинки. Стабільні значення включають `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（можна повернути поточний вміст assistant без змін, щоб продовжити）、`refusal` і `model_context_window_exceeded`. +- `stop_sequence`：якщо зупинка сталася через налаштовану послідовність зупинки, відображається текст послідовності зупинки, що збіглася. +- `stop_details`：коли `stop_reason` має значення `refusal`, може містити категорію та пояснення відмови. +- `usage`：статистика використання token. `input_tokens` — некешований ввід; `cache_creation_input_tokens` і `cache_read_input_tokens` — відповідно запис і читання кешу; `output_tokens` — загальна кількість вихідних token. Якщо повертається `output_tokens_details.thinking_tokens`, це значення є підмножиною `output_tokens`, тому під час обчислення загальної кількості або вартості не додавайте його повторно. За відсутності авторитетного підрахунку ця деталізація може бути `null` або пропущена. +- `usage.cache_creation`：необов’язкові відомості про TTL запису кешу, що містять `ephemeral_5m_input_tokens` і `ephemeral_1h_input_tokens`. Якщо об’єкт існує, сума цих двох значень дорівнює `cache_creation_input_tokens`; поле зі значенням `null` або пропущене означає, що поточна відповідь не має доступного розподілу за TTL, і його не можна тлумачити як `0`. +- `usage.cost`：непотокові відповіді можуть містити об’єкт витрати квоти, записаний Ace Data Cloud, де `amount` — фактична витрата цього разу, `currency` — одиниця вимірювання, а `list_amount` — сума до знижки (за наявності). Офіційна базова ціна читання кешу для Fable 5.1 становить $0.25/млн Token, а базові ціни запису кешу на 5 хвилин і 1 годину становлять відповідно $12.50 і $20/млн Token; фактичні ціни платформи перераховуються відповідно до знижок тарифного плану. + +## Системні підказки + +Claude Messages API підтримує встановлення системних підказок через поле `system`, що використовується для визначення поведінки, ролі та контексту моделі. ### Приклад Python + ```python import requests @@ -149,11 +152,11 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Налаштувавши системний промпт `system`, можна точно контролювати роль і спосіб поведінки Claude. +Налаштувавши підказку `system`, можна точно контролювати роль і поведінку Claude. -## Потокова відповідь +## Потокові відповіді -Цей інтерфейс також підтримує потокові відповіді: встановіть параметр `stream` у значення `true`, щоб отримувати поступове повернення результату, що дуже підходить для реалізації посимвольного відображення на вебсторінках. +Цей інтерфейс також підтримує потокові відповіді: встановіть параметр `stream` у значення `true`, щоб отримувати результат поступово, що особливо підходить для реалізації посимвольного відображення на вебсторінках. ### Приклад Python @@ -183,16 +186,16 @@ for line in response.iter_lines(): print(line.decode("utf-8")) ``` -Потокова відповідь повертається у форматі Server-Sent Events (SSE), кожен рядок має префікс `event:` і `data:`. Типи потокових подій включають: +Потокові відповіді повертаються у форматі Server-Sent Events (SSE), кожен рядок починається з `event:` і `data:`. Типи потокових подій включають: -- `message_start`: початок повідомлення, містить базову інформацію про повідомлення та назву моделі. -- `content_block_start`: початок блоку вмісту. -- `content_block_delta`: інкрементальне оновлення блоку вмісту, містить новостворений фрагмент тексту. -- `content_block_stop`: завершення блоку вмісту. -- `message_delta`: інкрементальне оновлення на рівні повідомлення, містить `stop_reason` та остаточну інформацію `usage`. Авторитетне значення `output_tokens_details.thinking_tokens` слід читати лише з останнього `message_delta.usage`, не накопичуйте його між подіями. -- `message_stop`: завершення повідомлення. +- `message_start`：початок повідомлення, містить базову інформацію про повідомлення та назву моделі. +- `content_block_start`：початок блоку вмісту. +- `content_block_delta`：інкрементальне оновлення блоку вмісту, містить новостворений фрагмент тексту. +- `content_block_stop`：завершення блоку вмісту. +- `message_delta`：інкрементальне оновлення на рівні повідомлення, містить `stop_reason` та остаточну інформацію `usage`. Авторитетне значення `output_tokens_details.thinking_tokens` слід зчитувати лише з останнього `message_delta.usage`, не накопичуйте його між подіями. +- `message_stop`：завершення повідомлення. -Результат виведення має такий вигляд: +Ефект виведення такий: ``` event: message_start @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -Як видно, у потоковій відповіді подія `content_block_delta` містить поступово створений текстовий вміст; об'єднавши всі `text_delta`, можна отримати повну відповідь. +Як видно, у потоковій відповіді події `content_block_delta` містять поступово згенерований текстовий вміст; об’єднавши всі `text_delta`, можна отримати повну відповідь. ### Приклад JavaScript @@ -253,7 +256,7 @@ while (true) { ## Багатораундовий діалог -Якщо ви хочете підключити функцію багатораундового діалогу, потрібно почергово розмістити повідомлення з ролями `user` та `assistant` у масиві `messages` і передати разом усю попередню історію діалогу. +Якщо ви хочете підключити функцію багатораундового діалогу, потрібно почергово розміщувати повідомлення з ролями `user` і `assistant` у масиві `messages`, передаючи разом із ними попередню історію діалогу. ### Приклад Python @@ -282,8 +285,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Результат повернення має такий вигляд: - +Результат повернення такий: ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -307,11 +309,11 @@ print(response.json()) Передаючи повну історію діалогу в `messages`, Claude може надавати точні відповіді з урахуванням контексту. -## Модель глибокого мислення +## Моделі глибокого мислення -thinking і thinking summary Claude — це два різні поняття: модель може виконувати внутрішні міркування, але API не повертає первинний ланцюжок думок. Коли потрібно відобразити процес міркувань, API повертає оброблений підсумок. +thinking і thinking summary у Claude — це два різні поняття: модель може виконувати внутрішнє міркування, але API не повертає необроблений ланцюжок думок. Коли потрібно показати процес міркування, API повертає оброблений підсумок. -Для поточної моделі рекомендовано використовувати adaptive thinking і керувати загальними витратами на міркування через `output_config.effort`: +Для поточних моделей рекомендовано використовувати adaptive thinking і керувати загальними витратами на міркування через `output_config.effort`: ```python import requests @@ -350,26 +352,27 @@ print(response.json()) "signature": "opaque-signature" } ``` -- `display: "summarized"` повертає читабельний підсумок міркувань; це не вихідний ланцюжок думок. -- `display: "omitted"` повертає `thinking: ""`, але все одно зберігає непрозорий `signature` для підтримки подальшого діалогу. -- `display: "updates"` є beta-режимом Anthropic, що потребує `anthropic-beta: thinking-display-updates-2026-08-18`. Офіційне визначення — приховувати основний текст міркувань і показувати короткі оновлення прогресу між викликами інструментів. Платформа передає цей параметр і beta-заголовок без змін і не примусово переписує його на `summarized`; фактичний вміст виводу залежить від підтримки вибраної моделі. -- `thinking`, `output_config`, effort, параметри семплювання та нові поля розширень передаються без змін. Платформа не підтримує жорстко закодовані за моделями переліки значень чи обмеження комбінацій і не переписує автоматично режими thinking; чи приймаються ці параметри, визначає вибрана модель, а помилки параметрів, повернуті моделлю, передаються клієнту. -- Значення display за замовчуванням для Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 та Opus 4.7 — `omitted`; Opus 4.6, Sonnet 4.6 та ранніші моделі з підтримкою thinking за замовчуванням використовують `summarized`. -- Display впливає лише на вміст відповіді та затримку потокової передачі, не вимикає міркування й не зменшує тарифікацію thinking token. -- Чи ввімкнено thinking за замовчуванням і значення display за замовчуванням — два незалежні питання. Opus 5 і Sonnet 5 за замовчуванням вмикають adaptive thinking; для Opus 5 пропуск `thinking` еквівалентний adaptive, а пропуск `output_config.effort` еквівалентний `high`. Opus 4.8, 4.7 і 4.6 потребують явного ввімкнення. -- Thinking і фінальний основний текст спільно використовують вихідний бюджет `max_tokens`. Якщо бюджет замалий, thinking може зайняти більшу частину ліміту, через що основний текст буде порожнім або обрізаним; збільште `max_tokens` або використовуйте effort `low` / `medium`, щоб контролювати вкладення в міркування. -- Для моделей, що дозволяють вимкнути thinking, можна передати `thinking: {"type":"disabled"}`. Нові режими, як-от `between_tools`, і комбінації effort залежать від вибраної моделі; платформа не відхиляє їх завчасно на основі старих правил для моделей. -- Фіксований бюджет міркувань можна передати через `budget_tokens`; нові моделі зазвичай використовують `thinking.type=adaptive` та `output_config.effort`. Чи підтримується фіксований бюджет або вимкнення міркувань, залежить від поточних можливостей вибраної моделі. -- Під час багатораундових діалогів і викликів інструментів слід повертати повний блок thinking та signature, які повернув assistant, без змін; не змінюйте й не генеруйте signature самостійно. -- Передавання параметрів без змін не означає, що кожна модель підтримує всі функції. Виклики між протоколами все одно потребують перетворення, а діапазон підтримки та помилки для такого вмісту, як `redacted_thinking`, визначаються сервісом моделі, який фактично обробляє запит. - -У потокових запитах `summarized` створює `thinking_delta`; `omitted` не створює `thinking_delta`, зберігаючи лише життєвий цикл блоку thinking та `signature_delta`. + +- `display: "summarized"` повертає читабельний підсумок міркування; це не необроблений ланцюжок думок. +- `display: "omitted"` повертає `thinking: ""`, але все одно зберігає непрозорий `signature` для підтримки наступних діалогів. +- `display: "updates"` — це beta-режим Anthropic, який потребує передачі `anthropic-beta: thinking-display-updates-2026-08-18`. Офіційне визначення — приховувати основний текст міркування та показувати короткі оновлення прогресу між викликами інструментів. Платформа передає цей параметр і beta-заголовок запиту без змін та не примусово переписує його на `summarized`; фактичний вміст виводу залежить від підтримки обраної моделі. +- `thinking`, `output_config`, effort, параметри семплювання та нові поля розширень передаються без змін. Платформа не підтримує жорстко закодований за моделями перелік значень або обмеження комбінацій і не переписує автоматично режими thinking; те, чи приймаються ці параметри, визначається обраною моделлю, а помилки параметрів, що повертає модель, передаються назад клієнту. +- Значенням display за замовчуванням для Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 і Opus 4.7 є `omitted`; моделі Opus 4.6, Sonnet 4.6 і більш ранні моделі з підтримкою thinking за замовчуванням використовують `summarized`. +- Display впливає лише на вміст відповіді та затримку потокової передачі, але не вимикає міркування й не зменшує тарифікацію thinking token. +- Чи увімкнено thinking за замовчуванням і значення display за замовчуванням — це два незалежні питання. Opus 5 і Sonnet 5 за замовчуванням вмикають adaptive thinking; для Opus 5 пропуск `thinking` еквівалентний adaptive, а пропуск `output_config.effort` еквівалентний `high`. Opus 4.8, 4.7 і 4.6 потребують явного ввімкнення. +- Thinking і фінальний текст спільно використовують вихідний бюджет `max_tokens`. Якщо бюджет надто малий, thinking може зайняти більшу частину ліміту, через що текст буде порожнім або обрізаним; збільште `max_tokens` або використовуйте effort `low` / `medium` для контролю витрат на міркування. +- Для моделей, що дозволяють вимкнути thinking, можна передати `thinking: {"type":"disabled"}`. Нові режими, такі як `between_tools`, а також комбінації effort залежать від обраної моделі; платформа не відхиляє їх заздалегідь на основі старих правил для моделей. +- Фіксований бюджет міркування можна передати через `budget_tokens`; нові моделі зазвичай використовують `thinking.type=adaptive` і `output_config.effort`. Чи підтримується фіксований бюджет або вимкнення thinking, визначається поточними можливостями обраної моделі. +- У багатораундових діалогах і викликах інструментів слід передавати назад повний блок thinking та signature, повернуті assistant, без змін; не змінюйте та не генеруйте signature самостійно. +- Передача параметрів без змін не означає, що кожна модель підтримує всі функції. Виклики між протоколами все одно потребують перетворення, а діапазон підтримки та помилки для такого вмісту, як `redacted_thinking`, визначаються сервісом моделі, який фактично обробляє запит. + +У потокових запитах `summarized` створює `thinking_delta`; `omitted` не створює `thinking_delta`, зберігаючи лише життєвий цикл блоку thinking і `signature_delta`. ## Візуальні моделі -Claude підтримує мультимодальний ввід і може одночасно обробляти текст та зображення. У Messages API можливості візуального розпізнавання можна використовувати, встановивши `content` у формат масиву та передавши блок вмісту зображення. +Claude підтримує мультимодальний ввід і може одночасно обробляти текст і зображення. У Messages API візуальні можливості можна використовувати, встановивши `content` у формат масиву та передавши блок вмісту зображення. -### Використання зображень, закодованих у Base64 +### Використання зображень із кодуванням Base64 ```python import base64 @@ -456,7 +459,6 @@ print(response.json()) ``` ### Приклад cURL - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -490,7 +492,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ ## Документи та PDF -PDF використовує блок вмісту `document` і підтримує два стабільні джерела: Base64 та URL. Джерело Base64 обов’язково має використовувати `application/pdf`: +PDF використовують блок вмісту `document`, підтримуючи два стабільні джерела: Base64 і URL. Джерело Base64 повинно використовувати `application/pdf`: ```python import base64 @@ -519,11 +521,11 @@ payload = { } ``` -URL-джерело записується як `{"type":"url","url":"https://example.com/report.pdf"}`. `document` також підтримує `text/plain` і джерело `content`, що складається з блоків text/image; необов’язкові поля включають `title`, `context` та `citations`. Джерело `file_id` API Files належить до окремої beta-функції та не входить до стабільного контракту цього інтерфейсу. +URL-джерело записується як `{"type":"url","url":"https://example.com/report.pdf"}`. `document` також підтримує `text/plain` і джерело `content`, що складається з блоків text/image; необов’язкові поля включають `title`, `context` і `citations`. Джерело `file_id` Files API належить до окремої beta-функції та не входить до стабільного контракту цього інтерфейсу. -## Кешування підказок +## Кешування промптів -Верхньорівневий `cache_control` автоматично розміщує точку зупинки кешу на останньому кешованому блоці: +`cache_control` верхнього рівня автоматично розміщує точку кешування на останньому кешованому блоці: ```python payload = { @@ -534,11 +536,12 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` -Коли потрібно точно контролювати позицію, той самий `cache_control` також можна записати в блоки вмісту text, image, document, tool_use, tool_result або у визначення інструменту. `ttl` підтримує `5m` (за замовчуванням) і `1h`; будь ласка, використовуйте `usage.cache_creation_input_tokens` та `usage.cache_read_input_tokens`, щоб визначити запис у кеш і влучання в кеш. -Коли відповідь надає `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Якщо `cache_creation` має значення `null` або пропущений, це означає, що є лише загальний обсяг запису в кеш, без авторитетного розподілу за TTL; у такому разі не вважайте жоден bucket відомим як 0, а тарифікація та загальний обсяг усе ще мають ґрунтуватися на aggregate-полі. +Коли потрібен точний контроль позиції, той самий `cache_control` також можна записати в блоки вмісту text, image, document, tool_use, tool_result або у визначення інструменту. `ttl` підтримує `5m` (за замовчуванням) і `1h`; визначайте запис у кеш і влучання в кеш за допомогою `usage.cache_creation_input_tokens` та `usage.cache_read_input_tokens`. + +Коли відповідь надає `usage.cache_creation`, `ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`. Якщо `cache_creation` має значення `null` або пропущено, це означає, що існує лише загальний обсяг запису в кеш без авторитетного розподілу за TTL; у такому разі не вважайте жоден bucket відомим як 0, а для білінгу й загальної кількості все одно орієнтуйтеся на aggregate-поля. -Приклад результату, що повертається: +Приклад результату повернення: ```json { @@ -561,9 +564,9 @@ payload = { } ``` -## Виклик інструментів (Tool Use) +## Виклики інструментів (Tool Use) -Claude Messages API нативно підтримує функцію виклику інструментів, дозволяючи моделі за потреби викликати попередньо визначені вами інструменти/функції. +Claude Messages API нативно підтримує функцію виклику інструментів, дозволяючи моделі за потреби викликати заздалегідь визначені вами інструменти/функції. ### Приклад Python @@ -606,7 +609,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Коли модель вирішує викликати інструмент, у результаті, що повертається, `content` міститиме блок вмісту типу `tool_use`: +Коли модель вирішує викликати інструмент, `content` у результаті повернення міститиме блок вмісту типу `tool_use`: ```json { @@ -637,7 +640,7 @@ print(response.json()) } ``` -Зверніть увагу, що `stop_reason` має значення `tool_use`, що вказує на потребу моделі викликати інструмент. Після отримання цього результату вам потрібно виконати функцію інструменту та передати результат назад моделі у формі `tool_result`: +Зверніть увагу, що `stop_reason` має значення `tool_use`, що означає, що моделі потрібно викликати інструмент. Після отримання цього результату вам потрібно виконати функцію інструменту та повернути результат моделі у формі `tool_result`: ```python payload = { @@ -685,14 +688,13 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Модель на основі результату, поверненого інструментом, згенерує остаточну відповідь природною мовою. +Модель згенерує остаточну відповідь природною мовою на основі результату, поверненого інструментом. ## Відмінності від Chat Completion API -Ace Data Cloud одночасно надає два формати Claude API, основні відмінності між ними такі: - -`usage.input_tokens` у Messages API позначає лише некешований ввід, а `cache_read_input_tokens` і `cache_creation_input_tokens` є незалежними тарифікованими bucket-ами; усі три обчислюються окремо за відповідними цінами. +Ace Data Cloud одночасно надає два формати Claude API, їхні основні відмінності такі: +`usage.input_tokens` у Messages API означає лише некешований ввід, а `cache_read_input_tokens` і `cache_creation_input_tokens` є окремими білінговими bucket-ами; усі три обчислюються окремо за відповідними цінами. | Характеристика | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | Формат | Нативний формат Anthropic | OpenAI-сумісний формат | @@ -703,7 +705,7 @@ Ace Data Cloud одночасно надає два формати Claude API, | Виклик інструментів | Нативні `tools` + `input_schema` | OpenAI-сумісний формат `tools` | | Статистика Token | `output_tokens_details.thinking_tokens` | `completion_tokens_details.reasoning_tokens` | -Якщо ваша система вже інтегрована з API формату OpenAI, ви можете використовувати Chat Completion API для безшовного перемикання. Якщо вам потрібно використовувати всі нативні можливості Claude, рекомендується використовувати Messages API. +Якщо ваша система вже інтегрована з API формату OpenAI, ви можете використовувати Chat Completion API для безшовного переходу. Якщо вам потрібно використовувати всі нативні можливості Claude, рекомендується використовувати Messages API. ## Обробка помилок @@ -711,7 +713,7 @@ Ace Data Cloud одночасно надає два формати Claude API, - `400`: параметри запиту або вміст протоколу недійсні. - `401`: токен авторизації недійсний, відсутній або прострочений. -- `403`: доступ заборонено, недостатньо балансу або квота обмежена. +- `403`: доступ заборонено, недостатньо балансу або обмежено квоту. - `404`: API або модель не існує. - `413`: тіло запиту завелике. - `429`: забагато запитів. @@ -729,7 +731,8 @@ Ace Data Cloud одночасно надає два формати Claude API, } ``` -Ця структура помилки є контрактом часу виконання Ace Data Cloud і не дорівнює офіційному envelope помилки Anthropic; будь ласка, обробляйте її відповідно до HTTP-статусу та `error.code`. +Ця структура помилки є контрактом часу виконання Ace Data Cloud і не є еквівалентною офіційному error envelope Anthropic; обробляйте її відповідно до HTTP-статусу та `error.code`. ## Висновок -Завдяки цьому документу ви вже дізналися, як використовувати Claude Messages API для виклику функцій діалогу Claude у нативному форматі Anthropic. Messages API підтримує такі багаті функції, як базовий діалог, системні підказки, потокові відповіді, багатораундові діалоги, глибоке мислення, візуальне розуміння, PDF, кешування підказок і виклик інструментів. Якщо у вас виникнуть будь-які запитання, будь ласка, не соромтеся звертатися до нашої команди технічної підтримки. + +Завдяки цьому документу ви вже дізналися, як використовувати Claude Messages API для виклику функцій діалогу Claude у нативному форматі Anthropic. Messages API підтримує багаті можливості, такі як базовий діалог, системні промпти, потокові відповіді, багатораундові діалоги, глибоке мислення, візуальне розуміння, PDF, кешування промптів і виклик інструментів. Якщо у вас виникнуть будь-які запитання, будь ласка, звертайтеся до нашої команди технічної підтримки у будь-який час. diff --git a/uk/guides/openai/openai_embeddings.mdx b/uk/guides/openai/openai_embeddings.mdx index d48fdb96e..2005aebbd 100644 --- a/uk/guides/openai/openai_embeddings.mdx +++ b/uk/guides/openai/openai_embeddings.mdx @@ -1,42 +1,42 @@ --- -title: "OpenAI Embeddings API заявка та використання" +title: "Подання заявки та використання OpenAI Embeddings API" description: "OpenAI generation API guide - Ace Data Cloud" --- -OpenAI сервіс векторів слів, призначений для генерації векторних результатів, що представляють вхідний текст. +Сервіс векторів слів OpenAI, що використовується для генерації результатів векторів слів, які представляють вхідний текст. -Цей документ в основному описує процес використання OpenAI Embeddings API, за допомогою якого ми можемо створити вектор вбудовування, що представляє вхідний текст. +Цей документ переважно описує процес використання операцій OpenAI Embeddings API, за допомогою якого ми можемо створювати вектори вбудовування, що представляють вхідний текст。。 -## Процес заявки +## Процес подання заявки -Щоб використовувати OpenAI Embeddings API, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) для отримання вашого API Token, залиште його на випадок потреби. +Щоб використовувати OpenAI Embeddings API, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token і зберегти його для подальшого використання. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти, після чого ви автоматично повернетеся на цю сторінку. +Якщо ви ще не увійшли або не зареєструвалися, вас автоматично буде перенаправлено на сторінку входу із запрошенням зареєструватися та увійти, після завершення вас буде автоматично повернуто на поточну сторінку. -**Один API Token дозволяє викликати всі сервіси платформи, не потрібно окремо подавати заявку на кожен сервіс.** Перший запит на отримання токена надає безкоштовний ліміт, ви можете безкоштовно протестувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в [консолі](https://platform.acedata.cloud/console/coin). +**Один API Token може викликати всі сервіси платформи, немає потреби подавати окрему заявку для кожного сервісу.** Під час першого подання заявки буде надано безкоштовний ліміт, який можна безкоштовно випробувати; коли ліміту недостатньо, можна поповнити загальний баланс у [консолі](https://platform.acedata.cloud/console/coin). > 📘 Повна документація: [OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) -## Основне використання +## Базове використання -Далі ви можете заповнити відповідні поля на інтерфейсі, як показано на малюнку: +Далі можна заповнити відповідний вміст в інтерфейсі, як показано на зображенні:

-При першому використанні цього інтерфейсу нам потрібно заповнити принаймні три поля: одне з них - `authorization`, яке можна вибрати безпосередньо зі списку. Інший параметр - `model`, `model` - це категорія моделі, яку ми вибираємо для використання з сайту OpenAI, тут у нас є 3 основні моделі, деталі можна переглянути в наданих моделях. Останній параметр - `input`, `input` - це текст, який ми хочемо перетворити на вектор слів. +Під час першого використання цього інтерфейсу нам потрібно заповнити щонайменше три поля: одне з них — `authorization`, його можна безпосередньо вибрати у розкривному списку. Інший параметр — `model`, `model` — це категорія моделі з офіційного сайту OpenAI, яку ми обираємо для використання; наразі доступні моделі `text-embedding-3-small` і `text-embedding-3-large`. `text-embedding-ada-002` більше не надається; якщо наявний векторний індекс використовує цю стару модель, не можна безпосередньо змішувати вектори нової моделі, потрібно повторно створити індекс. Останній параметр — `input`, `input` — це текст для векторизації слів, який нам потрібно перетворити. -Ви також можете помітити, що праворуч є відповідний код виклику, який ви можете скопіювати та запустити, або просто натиснути кнопку «Спробувати» для тестування. +Водночас ви можете помітити, що праворуч є генерація відповідного коду виклику, ви можете скопіювати код і запустити його безпосередньо, або безпосередньо натиснути кнопку «Try» для тестування. -Додаткові параметри: +Необов’язкові параметри: -- `dimensions`: обрізка розмірності вектора, за замовчуванням виводиться повна розмірність. -- `encoding_format`: формат повернення, можна вибрати `float` або `base64`. +- `dimensions`: обрізання розмірності вектора, за замовчуванням виводиться повна розмірність. +- `encoding_format`: формат повернення, доступні `float` або `base64`.

-Приклад коду виклику на Python: +Приклад коду виклику Python: ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -Після виклику ми отримуємо наступний результат: +Після виклику ми бачимо, що результат повернення має такий вигляд: ```json { @@ -97,7 +97,7 @@ print(response.text) ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,22 +105,22 @@ print(response.text) } ``` -У повернутому результаті є кілька полів, описаних нижче: +Результат повернення загалом містить кілька полів, описаних нижче: -- `model`, модель, що використовується для перетворення тексту на вектор слів. -- `usage`, інформація про токени, що використовуються для перетворення тексту на вектор слів. -- `data`, результати векторизації тексту. +- `model` — модель, використана для цього перетворення тексту у вектор слів. +- `usage` — інформація про token, використані для цього перетворення тексту у вектор слів. +- `data` — результат вектора слів після перетворення тексту. -Серед `data` міститься конкретна інформація про вектори слів, а `embedding` - це конкретний результат згенерованого вектора слів. +Серед них `data` містить конкретну інформацію про вектор слів, що відповідає тексту, а `embedding` у ньому є конкретним згенерованим результатом вектора слів. ## Обробка помилок -При виклику API, якщо виникає помилка, API повертає відповідний код помилки та інформацію. Наприклад: +Під час виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад: -- `400 token_mismatched`: Неправильний запит, можливо, через відсутні або недійсні параметри. -- `400 api_not_implemented`: Неправильний запит, можливо, через відсутні або недійсні параметри. +- `400 token_mismatched`: Неправильний запит, можливо через відсутні або недійсні параметри. +- `400 api_not_implemented`: Неправильний запит, можливо через відсутні або недійсні параметри. - `401 invalid_token`: Неавторизовано, недійсний або відсутній токен авторизації. -- `429 too_many_requests`: Занадто багато запитів, ви перевищили ліміт запитів. +- `429 too_many_requests`: Забагато запитів, ви перевищили обмеження частоти. - `500 api_error`: Внутрішня помилка сервера, щось пішло не так на сервері. ### Приклад відповіді з помилкою @@ -138,4 +138,4 @@ print(response.text) ## Висновок -Завдяки цьому документу ви дізналися, як легко використовувати OpenAI Embeddings API для генерації векторів слів від офіційного OpenAI. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, не соромтеся звертатися до нашої команди технічної підтримки. +За допомогою цього документа ви вже дізналися, як легко використовувати функцію генерації векторів слів офіційного OpenAI через OpenAI Embeddings API. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас виникнуть будь-які запитання, будь ласка, у будь-який час звертайтеся до нашої команди технічної підтримки. diff --git a/uk/guides/platform/wework_bot.mdx b/uk/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..644130b59 --- /dev/null +++ b/uk/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "Корпоративний WeChat-бот" +description: "Platform API guide - Ace Data Cloud" +--- + +Розгорніть власний екземпляр облікового запису корпоративного WeChat, увійдіть за допомогою сканування QR-коду в мобільному корпоративному WeChat, використовуйте REST API або MCP для читання облікового запису, контактів, чатів і локально синхронізованих повідомлень. Екземпляр відповідає звичайному обліковому запису корпоративного WeChat і не потребує приватного сервера або налаштування домену корпоративної пошти. + +Наразі це Alpha-версія. Читання облікового запису пройшло реальну перевірку сеансів; надсилання текстових повідомлень від імені власника та зворотне читання подій пройшли реальне приймання; інші контакти, операції з групами та відновлення нового екземпляра ще мають пройти перевірку в середовищі розгортання. Надсилання медіа, відповіді з цитуванням, реальний @, керування учасниками груп і підтвердження доставки ще не відкриті. Будь ласка, орієнтуйтеся на значення, яке повертає екземпляр `/api/capabilities`. + +## Розгортання та вхід + +У категорії Deployment відкрийте сервіс і виберіть тариф тривалості екземпляра. Після розгортання відкрийте сторінку керування та відскануйте QR-код корпоративного WeChat обліковим записом власника; якщо потрібне підтвердження на телефоні або інші кроки входу, відкрийте віддалений робочий стіл і введіть пароль робочого столу цього екземпляра. Облікові дані API та пароль робочого столу є незалежними. Дані входу зберігаються на диску екземпляра; при перебудові контейнера диск зберігається; видалення диска видалить локальний сеанс. + +Кожен екземпляр оплачується окремо та працює відповідно до придбаної тривалості. Виклики REST / MCP не оплачуються окремо за повідомлення, фактична ціна визначається сторінкою тарифу. Наразі за замовчуванням використовується довідковий тариф тривалості для WeChat-бота, перед остаточним відкриттям необхідно підтвердити ціноутворення з урахуванням ресурсів виконання. + +## API та MCP + +Використовуйте API-адресу екземпляра зі сторінки керування, усі інтерфейси облікового запису передають `Authorization: Bearer <токен API екземпляра>`. Ці шляхи належать спеціальному екземпляру, а не спільному API-шлюзу. Адреса MCP — це адреса екземпляра з додаванням `/mcp/`, використовується той самий Bearer token. + +| Інтерфейс | Призначення | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | Чи готовий обліковий запис та список можливостей | +| `GET /api/auth/qr` | Поточний QR-код входу PNG Base64 | +| `GET /api/account` | Поточний обліковий запис | +| `GET /api/contacts?kind=all` | Внутрішні колеги та зовнішні контакти, можна вказати internal / external | +| `GET /api/conversations` | Локальні чати, збереження оригінального ID чату | +| `GET /api/messages` | Локально синхронізовані повідомлення; параметри conversation_id, after_rowid, limit | +| `POST /api/search` | Пошук контактів, чатів і локального тексту | +| `POST /api/messages` | Асинхронне завдання надсилання тексту, необхідно надати Idempotency-Key | +| `POST /api/messages/send` | Той самий вхід надсилання, підтримує одну або кілька цілей | +| `GET /api/groups/{conversation_id}` | Локально синхронізована інформація про групи та учасників | +| `GET /api/tasks` | Останні завдання та результати для кожної цілі | +| `GET /api/tasks/{id}` | Запит результату надсилання | +| `POST /api/tasks/{id}/cancel` | Скасування завдань, які ще не розпочалися | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | Призупинення автоматизації; відновлення після перевірки власника | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | Стан екземпляра та поточний екран, обидва потребують автентифікації | +| `GET /api/events?after=0` | Події повідомлень із можливістю відновлення курсора | +| `WS /ws` | Потік подій повідомлень, автентифікація Bearer | + +Тіло надсилання містить `target`, `type: "text"` і `text`. `target` приймає ID чату, ID контакту, ID користувача підприємства або унікальне повне ім’я; переважно використовувати ID; якщо відображуване ім’я все ще не може однозначно визначити об’єкт, екземпляр відхилить операцію і не буде вгадувати об’єкт. Контакти без локального чату спочатку відкриють чат через клієнт і після перевірки фактичного ID чату виконають надсилання. Заголовок запиту `Idempotency-Key` містить 8–128 символів: літери, цифри або `_.:-`. Повторні запити однієї операції повинні використовувати той самий ключ і те саме тіло запиту. + +Заміна `target` на масив `targets` дозволяє послідовне надсилання 1–50 чітко визначеним цілям. Обидва параметри не можна надавати одночасно. Усі цілі спочатку проходять ідентифікаційний аналіз, різні псевдоніми, що вказують на один об’єкт, будуть відхилені. Якщо одна з цілей не вдається, подальше надсилання припиняється, результати завдання записуються окремо як `succeeded`, `failed`, `unknown` або `not_attempted`; не вважайте частковий успіх повним успіхом. Цей процес також має пройти реальну перевірку в середовищі розгортання для визначених контактів. + +Завдання можуть перебувати у стані queued, running, submitting, succeeded, failed, unknown або cancelled. `succeeded` означає, що після надсилання було знайдено точний текст у відповідному чаті та ID повідомлення сервера, `delivered` все ще має значення null і не означає, що інша сторона отримала повідомлення. unknown означає, що результат невизначений, перевірте історію записів і не надсилайте повторно з новим ключем. Екземпляр не буде автоматично повторно надсилати перервані завдання. + +Історія містить лише вміст, який уже синхронізував клієнт, і не може гарантувати повну історію. Нетекстові повідомлення можуть повертатися з типом unknown, завантаження вкладень ще не відкрите. Події зберігають останні 10 000 записів, `gap` означає, що курсор перевищив вікно збереження. Під час першого підключення стара історія не буде повторно відтворюватися як нові повідомлення. + +`server_accepted` і `server_id` в історії повідомлень можна використовувати для перевірки, чи прийняв сервер локальне повідомлення; якщо є лише локальний запис без ID сервера, не можна вважати надсилання успішним. Ці поля не означають, що одержувач отримав або прочитав повідомлення. Записи подій зберігають стан на момент створення, для запиту поточного підтвердженого стану слід використовувати інтерфейс історії повідомлень. + +## Обліковий запис і облікові дані + +Використовуйте лише облікові записи, якими маєте право керувати особисто. Налаштовуйте API token лише у довірених застосунках; він може отримувати доступ до даних облікового запису цього екземпляра. Не публікуйте паролі, QR-коди або скриншоти чатів у відкритих місцях. Призупинення екземпляра перерве події в реальному часі. Після виходу з облікового запису або видалення пристрою на мобільному телефоні потрібно повторно увійти. + +Поточне введення тексту підтримує лише один рядок, переноси рядків будуть явно відхилені перед надсиланням. Якщо клієнт вимагає безпечної перевірки або повторного входу, власник облікового запису повинен виконати це через віддалений робочий стіл; екземпляр не буде обходити перевірку. Завдання після переривання перевірки можуть повернути unknown, спочатку перевірте записи повідомлень і не надсилайте повторно з новим ключем ідемпотентності. + +Після виявлення запиту безпеки, виходу з облікового запису або зміни облікового запису черга автоматизації буде збережена та призупинена. Після завершення перевірки телефону можна через консоль екземпляра «Відновити після перевірки» продовжити невиконані завдання; завдання, які вже були відправлені, але мають невизначений результат, не будуть повторно надсилатися. Звичайна віддалена офісна робота також може викликати перевірку безпеки корпоративного WeChat. Офіційне пояснення про відсутність блокування протягом 24 годин після перевірки не означає, що виявлення було усунено, і не означає, що екземпляр може гарантувати довготривалу роботу без нагляду. diff --git a/zh-Hans/guides/claude/claude_messages.mdx b/zh-Hans/guides/claude/claude_messages.mdx index ad0472176..38bb38336 100644 --- a/zh-Hans/guides/claude/claude_messages.mdx +++ b/zh-Hans/guides/claude/claude_messages.mdx @@ -38,6 +38,7 @@ Claude Messages API 的请求路径为 `/v1/messages`，与 Anthropic 官方 API - `tools`：工具定义，用于让模型调用外部函数。 - `tool_choice`：控制模型如何使用提供的工具。 - `cache_control`：在请求的最后一个可缓存内容块处自动创建缓存断点；也可写在具体内容块上。 +- `metadata`：可选的请求元数据对象。`metadata.user_id` 为字符串，可传递调用方自定义的用户标识，例如 `{"user_id":"example-user-001"}`；建议使用不含个人信息的稳定标识。它不替代 `Authorization` 鉴权，也不需要写进 `messages` 对话内容。 ### cURL 示例 @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] diff --git a/zh-Hans/guides/openai/openai_embeddings.mdx b/zh-Hans/guides/openai/openai_embeddings.mdx index 9b4b36f03..d6276655d 100644 --- a/zh-Hans/guides/openai/openai_embeddings.mdx +++ b/zh-Hans/guides/openai/openai_embeddings.mdx @@ -25,7 +25,7 @@ OpenAI 词向量服务，用于生成表示输入文本的词向量结果。

-在第一次使用该接口时，我们至少需要填写三个内容，一个是 `authorization`，直接在下拉列表里面选择即可。另一个参数是 `model`， `model` 就是我们选择使用 OpenAI 官网模型类别，这里我们主要有 3 种模型，详情可以看我们提供的模型。最后一个参数是`input`，`input` 是我们需要转换的词向量文本。 +在第一次使用该接口时，我们至少需要填写三个内容，一个是 `authorization`，直接在下拉列表里面选择即可。另一个参数是 `model`， `model` 就是我们选择使用 OpenAI 官网模型类别，当前可用模型为 `text-embedding-3-small` 和 `text-embedding-3-large`。`text-embedding-ada-002` 已停止提供；已有向量索引若使用该旧模型，不能直接混用新模型的向量，需要重新建索引。最后一个参数是`input`，`input` 是我们需要转换的词向量文本。 同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。 @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -97,7 +97,7 @@ print(response.text) ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 diff --git a/zh-Hans/guides/platform/wework_bot.mdx b/zh-Hans/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..eb176a965 --- /dev/null +++ b/zh-Hans/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "企业微信机器人" +description: "Platform 集成指南 - Ace Data Cloud" +--- + +部署属于自己的企业微信账号实例，使用手机企业微信扫码登录，通过 REST API 或 MCP 读取账号、联系人、会话与本地同步消息。实例对应普通企业微信账号，无需私有化服务器或企业邮箱域名配置。 + +当前为 Alpha。账号读取已完成真实会话验证；本人文本发送及事件读回已完成真实验收；其他联系人、群操作和新实例恢复仍需完成部署环境验收。媒体发送、引用回复、真实 @、群成员管理和送达回执尚未开放。请以实例 `/api/capabilities` 返回值为准。 + +## 部署与登录 + +在 Deployment 分类开通服务并选择实例时长套餐。部署后打开管理页，使用账号本人的企业微信扫码；如需手机确认或其他登录步骤，打开远程桌面并输入该实例的桌面密码。API 凭据与桌面密码独立。登录资料保存在实例磁盘中，重建容器保留磁盘；删除磁盘会删除本地会话。 + +每个实例独立收费，按已购买的时长运行。REST / MCP 调用不按消息另行收费，实际价格以套餐页面为准。当前默认参考微信机器人的时长套餐，最终开放前需结合运行资源完成定价确认。 + +## API 与 MCP + +使用管理页中的实例 API 地址，所有账号接口携带 `Authorization: Bearer <实例 API token>`。这些路径属于专属实例，不是共享 API 网关。MCP 地址为实例地址加 `/mcp/`，使用相同 Bearer token。 + +| 接口 | 作用 | +| --- | --- | +| `GET /api/status`、`GET /api/auth/status` | 账号是否就绪与能力清单 | +| `GET /api/auth/qr` | 当前登录二维码 PNG Base64 | +| `GET /api/account` | 当前账号 | +| `GET /api/contacts?kind=all` | 内部同事与外部联系人，可指定 internal / external | +| `GET /api/conversations` | 本地会话，保留原始会话 ID | +| `GET /api/messages` | 本地同步消息；conversation_id、after_rowid、limit 参数 | +| `POST /api/search` | 联系人、会话与本地文本搜索 | +| `POST /api/messages` | 文本发送异步任务，必须提供 Idempotency-Key | +| `POST /api/messages/send` | 相同发送入口，支持单个或多个目标 | +| `GET /api/groups/{conversation_id}` | 本地同步的群信息及成员 | +| `GET /api/tasks` | 最近任务及各目标的结果 | +| `GET /api/tasks/{id}` | 查询发送结果 | +| `POST /api/tasks/{id}/cancel` | 取消尚未开始的任务 | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | 暂停自动化；本人验证后恢复 | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | 实例状态与当前画面，均需鉴权 | +| `GET /api/events?after=0` | 可恢复游标的消息事件 | +| `WS /ws` | 消息事件流，Bearer 鉴权 | + +发送体包含 `target`、`type: "text"` 和 `text`。`target` 接受会话 ID、联系人 ID、企业用户 ID 或唯一的完整名称；优先使用 ID；显示名称仍不能唯一定位时，实例会拒绝操作，不会猜测对象。没有本地会话的联系人会先通过客户端打开会话，并核对实际会话 ID 后发送。请求头 `Idempotency-Key` 是 8–128 位字母、数字或 `_.:-`。同一操作重复请求必须复用相同键和相同请求体。 + +将 `target` 换为 `targets` 数组可串行发送给 1–50 个明确指定的目标。两者不能同时提供。全部目标先完成身份解析，指向同一对象的不同别名会被拒绝。某一目标失败后停止后续发送，任务结果逐项记录 `succeeded`、`failed`、`unknown` 或 `not_attempted`；不要把部分成功当成全部成功。此流程还需在部署环境完成指定联系人的真实验收。 + +任务可能处于 queued、running、submitting、succeeded、failed、unknown 或 cancelled。`succeeded` 表示提交后在对应会话记录中找到了准确文本及服务器消息 ID，`delivered` 仍为 null，不代表对方已收到。unknown 表示结果不明确，请检查历史记录，不要用新键重复发送。实例不会自动重发中断的任务。 + +历史仅包含客户端已经同步的内容，不能保证全部历史。非文本消息可能返回 unknown 类型，附件下载尚未开放。事件保留最近 10,000 条，`gap` 表示游标已超出保留窗口。首次连接不会把旧历史当作新消息重播。 + +消息历史中的 `server_accepted` 和 `server_id` 可用于核对服务器是否已接受本地消息；仅出现本地记录而没有服务器 ID 时，不能认定发送成功。这些字段不代表接收方已收到或阅读。事件记录保留生成时的状态，查询当前确认状态应使用消息历史接口。 + +## 账号和凭据 + +仅登录本人有权操作的账号。将 API token 配置到可信应用中；它可访问该实例的账号数据。不要将密码、二维码或聊天截图发布到公共位置。暂停实例会中断实时事件。账号登出或手机端移除设备后，需要重新登录。 + +当前文本输入只支持单行，换行会在发送前明确拒绝。客户端要求安全验证或重新登录时，应由账号本人在远程桌面完成；实例不会绕过验证。验证中断后的任务可能返回 unknown，请先查询消息记录，不要以新幂等键重发。 + +识别到安全验证提示、账号退出或变更后，自动化队列会持久化暂停。完成手机验证后，可通过实例控制台“验证后恢复”继续尚未执行的任务；已经提交但结果不确定的任务不会重发。正常远程办公也可能触发企业微信安全验证。官方说明的验证后 24 小时不再锁定窗口，不代表已经消除检测，也不代表实例可以保证长期无人值守。 diff --git a/zh-Hant/guides/claude/claude_messages.mdx b/zh-Hant/guides/claude/claude_messages.mdx index 23c37a657..353ec9320 100644 --- a/zh-Hant/guides/claude/claude_messages.mdx +++ b/zh-Hant/guides/claude/claude_messages.mdx @@ -5,7 +5,7 @@ description: "Claude AI 整合指南 - Ace Data Cloud" Anthropic Claude 是一款非常強大的 AI 對話系統，只要輸入提示詞，就能在短短幾秒內生成流暢自然的回覆。Claude Messages API 是 Anthropic 官方原生的 API 格式，與 OpenAI 相容格式（Chat Completion）不同，它採用 Anthropic 自有的請求和回應結構，能夠更好地利用 Claude 的獨特能力，如多模態內容輸入、工具呼叫、深度思考（Extended Thinking）等進階特性。 -本文件主要介紹 Claude Messages API 操作的使用流程，利用它我們可以使用與 Anthropic 官方一致的原生介面來呼叫 Claude 的對話功能。 +本文檔主要介紹 Claude Messages API 操作的使用流程，利用它我們可以使用與 Anthropic 官方一致的原生介面來呼叫 Claude 的對話功能。 ## 申請流程 @@ -15,7 +15,7 @@ Anthropic Claude 是一款非常強大的 AI 對話系統，只要輸入提示 如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。 -**一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。 +**一個 API Token 即可呼叫平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。 > 📘 完整文件：[Claude Messages API →](https://platform.acedata.cloud/documents/claude-messages) @@ -38,6 +38,7 @@ Claude Messages API 的請求路徑為 `/v1/messages`，與 Anthropic 官方 API - `tools`：工具定義，用於讓模型呼叫外部函式。 - `tool_choice`：控制模型如何使用提供的工具。 - `cache_control`：在請求的最後一個可快取內容區塊處自動建立快取斷點；也可寫在具體內容區塊上。 +- `metadata`：可選的請求中繼資料物件。`metadata.user_id` 為字串，可傳遞呼叫方自訂的使用者識別，例如 `{"user_id":"example-user-001"}`；建議使用不含個人資訊的穩定識別。它不替代 `Authorization` 鑑權，也不需要寫進 `messages` 對話內容。 ### cURL 範例 @@ -49,6 +50,7 @@ curl -X POST 'https://api.acedata.cloud/v1/messages' \ -d '{ "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ { "role": "user", @@ -74,6 +76,7 @@ headers = { payload = { "model": "claude-fable-5-1", "max_tokens": 1024, + "metadata": {"user_id": "example-user-001"}, "messages": [ {"role": "user", "content": "Hello, Claude"} ] @@ -107,24 +110,24 @@ print(response.json()) ``` 返回結果欄位說明： - - `id`：本次訊息的唯一識別碼。 - `type`：始終為 `message`。 - `role`：始終為 `assistant`。 - `content`：回覆內容陣列，每個元素包含 `type`（如 `text`）和對應的內容。 - `model`：處理請求的模型名稱。 -- `stop_reason`：停止原因。穩定取值包括 `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（可把目前 assistant 內容原樣回傳以繼續）、`refusal` 和 `model_context_window_exceeded`。 +- `stop_reason`：停止原因。固定取值包括 `end_turn`、`max_tokens`、`stop_sequence`、`tool_use`、`pause_turn`（可將目前 assistant 內容原樣回傳以繼續）、`refusal` 和 `model_context_window_exceeded`。 - `stop_sequence`：如果因自訂停止序列而停止，顯示符合的停止序列文字。 - `stop_details`：當 `stop_reason` 為 `refusal` 時，可能包含拒絕類別和說明。 -- `usage`：token 使用統計。`input_tokens` 是未快取輸入；`cache_creation_input_tokens` 和 `cache_read_input_tokens` 分別是快取寫入與讀取；`output_tokens` 是全部輸出 token 數。若返回 `output_tokens_details.thinking_tokens`，該值是 `output_tokens` 的子集，計算總量或費用時不要再次相加。該明細沒有權威計數時可能為 `null` 或省略。 +- `usage`：Token 使用統計。`input_tokens` 是未快取輸入；`cache_creation_input_tokens` 和 `cache_read_input_tokens` 分別是快取寫入與讀取；`output_tokens` 是全部輸出 Token 數。若回傳 `output_tokens_details.thinking_tokens`，該值是 `output_tokens` 的子集，計算總量或費用時不要再次相加。該明細沒有權威計數時可能為 `null` 或省略。 - `usage.cache_creation`：可選的快取寫入 TTL 明細，包含 `ephemeral_5m_input_tokens` 與 `ephemeral_1h_input_tokens`。物件存在時，兩項之和等於 `cache_creation_input_tokens`；欄位為 `null` 或省略表示目前回應沒有可用的 TTL 拆分，不能按 `0` 解讀。 -- `usage.cost`：非串流回應可能包含 Ace Data Cloud 記錄的額度消耗物件，其中 `amount` 是本次實際消耗、`currency` 是計量單位，`list_amount` 是折扣前金額（如有）。Fable 5.1 的官方快取讀取基價為 $0.25/百萬 Token，5 分鐘與 1 小時快取寫入基價分別為 $12.50 和 $20/百萬 Token；平台實際價格按方案折扣換算。 +- `usage.cost`：非串流回應可能包含 Ace Data Cloud 記錄的額度消耗物件，其中 `amount` 是本次實際消耗、`currency` 是計量單位，`list_amount` 是折扣前金額（如有）。Fable 5.1 的官方快取讀取基價為 $0.25/百萬 Token，5 分鐘與 1 小時快取寫入基價分別為 $12.50 和 $20/百萬 Token；平台實際價格依方案折扣換算。 ## 系統提示詞 Claude Messages API 支援透過 `system` 欄位設定系統提示詞，用於定義模型的行為、角色和上下文。 ### Python 範例 + ```python import requests @@ -187,7 +190,7 @@ for line in response.iter_lines(): - `message_start`：訊息開始，包含訊息的基本資訊和模型名稱。 - `content_block_start`：內容區塊開始。 -- `content_block_delta`：內容區塊增量更新，包含新生成的文字片段。 +- `content_block_delta`：內容區塊增量更新，包含新產生的文字片段。 - `content_block_stop`：內容區塊結束。 - `message_delta`：訊息層級的增量更新，包含 `stop_reason` 和最終的 `usage` 資訊。`output_tokens_details.thinking_tokens` 的權威值只應從最後一個 `message_delta.usage` 讀取，不要跨事件累加。 - `message_stop`：訊息結束。 @@ -220,7 +223,7 @@ event: message_stop data: {"type":"message_stop"} ``` -可以看到，串流回應中的 `content_block_delta` 事件包含了逐步生成的文字內容，透過拼接所有 `text_delta` 即可獲得完整回覆。 +可以看到，串流回應中 `content_block_delta` 事件包含了逐步產生的文字內容，透過拼接所有 `text_delta` 即可獲得完整回覆。 ### JavaScript 範例 @@ -253,7 +256,7 @@ while (true) { ## 多輪對話 -如果您想要串接多輪對話功能，需要在 `messages` 陣列中交替排列 `user` 和 `assistant` 角色的訊息，將之前的對話歷史一併傳入。 +如果您想要串接多輪對話功能，需要在 `messages` 陣列中交替排列 `user` 和 `assistant` 角色的訊息，將先前的對話歷史一併傳入。 ### Python 範例 @@ -283,7 +286,6 @@ print(response.json()) ``` 回傳結果如下： - ```json { "id": "msg_01Y1wfQmd89g968TVbFu57Yc", @@ -309,7 +311,7 @@ print(response.json()) ## 深度思考模型 -Claude 的 thinking 與 thinking summary 是兩個不同概念：模型可以進行內部推理，但 API 不會回傳原始思維鏈。需要展示推理過程時，API 回傳的是經過處理的摘要。 +Claude 的 thinking 與 thinking summary 是兩個不同概念：模型可以進行內部推理，但 API 不會返回原始思維鏈。需要展示推理過程時，API 返回的是經過處理的摘要。 目前模型建議使用 adaptive thinking，並透過 `output_config.effort` 控制整體推理投入： @@ -341,7 +343,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -回應中的 thinking 區塊形如： +回應中的 thinking 區塊形式如下： ```json { @@ -350,20 +352,21 @@ print(response.json()) "signature": "opaque-signature" } ``` + - `display: "summarized"` 返回可讀的思考摘要；它不是原始思維鏈。 - `display: "omitted"` 返回 `thinking: ""`，但仍保留 opaque `signature` 以支援後續對話。 -- `display: "updates"` 是 Anthropic 的 beta 模式，需攜帶 `anthropic-beta: thinking-display-updates-2026-08-18`。官方定義是隱藏推理正文、顯示工具呼叫之間的簡短進度更新。平台按原值傳遞該參數和 beta 請求標頭，不會強制改寫為 `summarized`；實際輸出內容取決於所選模型的支援情況。 -- `thinking`、`output_config`、effort、採樣參數及新增擴充欄位按原值傳遞。平台不維護按模型硬編碼的取值列舉、組合限制，也不自動改寫 thinking 模式；是否接受這些參數由所選模型判斷，模型返回的參數錯誤會傳回用戶端。 +- `display: "updates"` 是 Anthropic 的 beta 模式，需攜帶 `anthropic-beta: thinking-display-updates-2026-08-18`。官方定義是隱藏推理正文、顯示工具呼叫之間的簡短進度更新。平台會依原值傳遞該參數和 beta 請求標頭，不會強制改寫為 `summarized`；實際輸出內容取決於所選模型的支援情況。 +- `thinking`、`output_config`、effort、取樣參數及新增擴充欄位會依原值傳遞。平台不維護依模型硬編碼的取值列舉、組合限制，也不會自動改寫 thinking 模式；是否接受這些參數由所選模型判斷，模型返回的參數錯誤會傳回用戶端。 - Fable 5.1、Fable 5、Opus 5、Sonnet 5、Opus 4.8 和 Opus 4.7 的 display 預設值為 `omitted`；Opus 4.6、Sonnet 4.6 及更早支援 thinking 的模型預設使用 `summarized`。 -- Display 只影響返回內容和串流延遲，不關閉推理，也不減少 thinking token 的計費。 +- Display 只影響返回內容和串流延遲，不會關閉推理，也不會減少 thinking token 的計費。 - 是否預設啟用 thinking 與 display 預設值是兩個獨立問題。Opus 5、Sonnet 5 預設啟用 adaptive thinking；對 Opus 5，省略 `thinking` 等同於 adaptive，省略 `output_config.effort` 等同於 `high`。Opus 4.8、4.7 和 4.6 需要明確啟用。 -- Thinking 與最終正文共同佔用 `max_tokens` 輸出預算。預算過小時，thinking 可能佔用大部分額度，使正文為空或被截斷；請提高 `max_tokens`，或使用 `low` / `medium` effort 控制推理投入。 -- 對允許關閉 thinking 的模型，可傳 `thinking: {"type":"disabled"}`。`between_tools` 等新增模式以及 effort 組合取決於所選模型；平台不依據舊的型號規則提前拒絕。 +- Thinking 與最終正文共同占用 `max_tokens` 輸出預算。預算過小時，thinking 可能占用大部分額度，使正文為空或被截斷；請提高 `max_tokens`，或使用 `low` / `medium` effort 控制推理投入。 +- 對允許關閉 thinking 的模型，可傳入 `thinking: {"type":"disabled"}`。`between_tools` 等新增模式以及 effort 組合取決於所選模型；平台不會依據舊的型號規則提前拒絕。 - 固定思考預算可透過 `budget_tokens` 傳遞；新模型通常使用 `thinking.type=adaptive` 和 `output_config.effort`。是否支援固定預算或關閉思考，以所選模型的目前能力為準。 - 多輪對話和工具呼叫時，應將 assistant 返回的完整 thinking 區塊及 signature 原樣傳回；不要修改或自行產生 signature。 -- 參數透傳不代表每個模型都支援所有功能。跨協定呼叫仍需轉換，`redacted_thinking` 等內容的支援範圍和錯誤由實際處理請求的模型服務決定。 +- 參數透傳不代表每個模型都支援所有功能。跨協議呼叫仍需轉換，`redacted_thinking` 等內容的支援範圍和錯誤由實際處理請求的模型服務決定。 -串流請求中，`summarized` 會產生 `thinking_delta`；`omitted` 不產生 `thinking_delta`，只保留 thinking 區塊生命週期和 `signature_delta`。 +串流請求中，`summarized` 會產生 `thinking_delta`；`omitted` 不會產生 `thinking_delta`，只保留 thinking 區塊生命週期和 `signature_delta`。 ## 視覺模型 @@ -383,7 +386,7 @@ headers = { "content-type": "application/json" } -# 读取并编码图片 +# 讀取並編碼圖片 with open("image.png", "rb") as f: image_data = base64.standard_b64encode(f.read()).decode("utf-8") @@ -456,7 +459,6 @@ print(response.json()) ``` ### cURL 範例 - ```bash curl -X POST 'https://api.acedata.cloud/v1/messages' \ -H 'accept: application/json' \ @@ -534,6 +536,7 @@ payload = { "messages": [{"role": "user", "content": "Summarize the key points."}] } ``` + 需要精確控制位置時，也可把同樣的 `cache_control` 寫在 text、image、document、tool_use、tool_result 內容區塊或工具定義上。`ttl` 支援 `5m`（預設）與 `1h`；請透過 `usage.cache_creation_input_tokens` 和 `usage.cache_read_input_tokens` 判斷快取寫入與命中。 當回應提供 `usage.cache_creation` 時，`ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens`。若 `cache_creation` 為 `null` 或省略，表示只有快取寫入總量、沒有權威 TTL 拆分；此時不要將任一 bucket 當作已知的 0，計費和總量仍以 aggregate 欄位為準。 @@ -685,18 +688,17 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -模型會基於工具回傳的結果，產生最終的自然語言回覆。 +模型會基於工具回傳的結果，生成最終的自然語言回覆。 -## 與 Chat Completion API 的差異 +## 與 Chat Completion API 的區別 -Ace Data Cloud 同時提供兩種 Claude API 格式，兩者的主要差異如下： - -Messages API 的 `usage.input_tokens` 僅表示未快取輸入，`cache_read_input_tokens` 與 `cache_creation_input_tokens` 是獨立計費分桶；三者會分別依對應價格計算。 +Ace Data Cloud 同時提供兩種 Claude API 格式，兩者的主要區別如下： +Messages API 的 `usage.input_tokens` 僅表示未快取輸入，`cache_read_input_tokens` 與 `cache_creation_input_tokens` 是獨立計費分桶；三者會分別按對應價格計算。 | 特性 | Messages API (`/v1/messages`) | Chat Completion API (`/v1/chat/completions`) | | -------- | --------------------------------------- | -------------------------------------------- | | 格式 | Anthropic 原生格式 | OpenAI 相容格式 | -| 系統提示詞 | 獨立的 `system` 欄位 | 透過 `messages` 中 `role: "system"` 傳遞 | +| 系統提示詞 | 獨立的 `system` 欄位 | 透過 `messages` 中的 `role: "system"` 傳遞 | | 回應結構 | `content` 陣列（支援多種類型） | `choices` 陣列（包含 `message`） | | 串流格式 | SSE 事件（多種事件類型） | SSE `data` 行 | | 深度思考 | 原生 `thinking` 與 `output_config.effort` | 模型預設策略與相容參數 | @@ -732,4 +734,5 @@ Messages API 的 `usage.input_tokens` 僅表示未快取輸入，`cache_read_inp 該錯誤結構是 Ace Data Cloud 的執行階段契約，不等同於 Anthropic 官方錯誤 envelope；請依 HTTP 狀態與 `error.code` 處理。 ## 結論 + 透過本文檔，您已經了解如何使用 Claude Messages API 以 Anthropic 原生格式呼叫 Claude 的對話功能。Messages API 支援基本對話、系統提示詞、串流回應、多輪對話、深度思考、視覺理解、PDF、提示快取和工具呼叫等豐富功能。如有任何問題，請隨時聯絡我們的技術支援團隊。 diff --git a/zh-Hant/guides/openai/openai_embeddings.mdx b/zh-Hant/guides/openai/openai_embeddings.mdx index 7bea12c7d..7ff59b8c3 100644 --- a/zh-Hant/guides/openai/openai_embeddings.mdx +++ b/zh-Hant/guides/openai/openai_embeddings.mdx @@ -3,40 +3,40 @@ title: "OpenAI Embeddings API 申請及使用" description: "OpenAI generation 整合指南 - Ace Data Cloud" --- -OpenAI 詞向量服務，用於生成表示輸入文本的詞向量結果。 +OpenAI 詞向量服務，用於生成表示輸入文字的詞向量結果。 -本文檔主要介紹 OpenAI Embeddings API 操作的使用流程，利用它我們可以創建表示輸入文本的嵌入向量。。 +本文檔主要介紹 OpenAI Embeddings API 操作的使用流程，利用它我們可以建立表示輸入文字的嵌入向量。。 ## 申請流程 -要使用 OpenAI Embeddings API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 獲取您的 API Token，留作備用。 +要使用 OpenAI Embeddings API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 取得您的 API Token，留作備用。 ![](https://cdn.acedata.cloud/dvc3cg.jpg) -如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。 +如果您尚未登入或註冊，會自動跳轉到登入頁面邀請您註冊和登入，完成後會自動返回目前頁面。 -**一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用餘額。 +**一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。 -> 📘 完整文檔：[OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) +> 📘 完整文件：[OpenAI Embeddings API →](https://platform.acedata.cloud/documents/openai-embeddings) ## 基本使用 -接下來就可以在界面上填寫對應的內容，如圖所示： +接下來就可以在介面上填寫對應的內容，如圖所示：

-在第一次使用該接口時，我們至少需要填寫三個內容，一個是 `authorization`，直接在下拉列表裡面選擇即可。另一個參數是 `model`， `model` 就是我們選擇使用 OpenAI 官網模型類別，這裡我們主要有 3 種模型，詳情可以看我們提供的模型。最後一個參數是`input`，`input` 是我們需要轉換的詞向量文本。 +在第一次使用該介面時，我們至少需要填寫三個內容，一個是 `authorization`，直接在下拉清單裡面選擇即可。另一個參數是 `model`， `model` 就是我們選擇使用 OpenAI 官網模型類別，目前可用模型為 `text-embedding-3-small` 和 `text-embedding-3-large`。`text-embedding-ada-002` 已停止提供；既有向量索引若使用該舊模型，不能直接混用新模型的向量，需要重新建立索引。最後一個參數是`input`，`input` 是我們需要轉換的詞向量文字。 -同時您可以注意到右側有對應的調用代碼生成，您可以複製代碼直接運行，也可以直接點擊「Try」按鈕進行測試。 +同時您可以注意到右側有對應的呼叫程式碼生成，您可以複製程式碼直接執行，也可以直接點擊「Try」按鈕進行測試。 可選參數： -- `dimensions`：裁剪向量維度，默認輸出完整維度。 -- `encoding_format`：返回格式，可選 `float` 或 `base64`。 +- `dimensions`：裁剪向量維度，預設輸出完整維度。 +- `encoding_format`：回傳格式，可選 `float` 或 `base64`。

-Python 樣例調用代碼： +Python 範例呼叫程式碼： ```python import requests @@ -51,7 +51,7 @@ headers = { payload = { "input": "The food was delicious and the waiter...", - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "encoding_format": "float" } @@ -59,7 +59,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.text) ``` -調用之後，我們發現返回結果如下： +呼叫之後，我們發現回傳結果如下： ```json { @@ -97,7 +97,7 @@ print(response.text) ] } ], - "model": "text-embedding-ada-002", + "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 @@ -105,25 +105,25 @@ print(response.text) } ``` -返回結果一共有多個字段，介紹如下： +回傳結果一共有多個欄位，介紹如下： -- `model`，此次文本轉詞向量所採用的模型。 -- `usage`，此次文本轉詞向量所使用的token信息。 -- `data`，文本轉化後的詞向量結果。 +- `model`，此次文字轉詞向量所採用的模型。 +- `usage`，此次文字轉詞向量所使用的 token 資訊。 +- `data`，文字轉換後的詞向量結果。 -其中 `data` 是包含了文本對應的詞向量的具體信息，它裡面的 `embedding` 是生成的詞向量具體結果。 +其中 `data` 是包含了文字對應的詞向量的具體資訊，它裡面的 `embedding` 是生成的詞向量具體結果。 ## 錯誤處理 -在調用 API 時，如果遇到錯誤，API 會返回相應的錯誤代碼和信息。例如： +在呼叫 API 時，如果遇到錯誤，API 會回傳相應的錯誤代碼和資訊。例如： -- `400 token_mismatched`：Bad request, possibly due to missing or invalid parameters. -- `400 api_not_implemented`：Bad request, possibly due to missing or invalid parameters. -- `401 invalid_token`：Unauthorized, invalid or missing authorization token. -- `429 too_many_requests`：Too many requests, you have exceeded the rate limit. -- `500 api_error`：Internal server error, something went wrong on the server. +- `400 token_mismatched`：錯誤請求，可能是因為缺少或無效的參數。 +- `400 api_not_implemented`：錯誤請求，可能是因為缺少或無效的參數。 +- `401 invalid_token`：未授權，無效或缺少授權 Token。 +- `429 too_many_requests`：請求過多，您已超過速率限制。 +- `500 api_error`：內部伺服器錯誤，伺服器發生了問題。 -### 錯誤響應示例 +### 錯誤回應範例 ```json { @@ -138,4 +138,4 @@ print(response.text) ## 結論 -通過本文檔，您已經了解了如何使用 OpenAI Embeddings API 輕鬆使用官方 OpenAI 的詞向量生成的功能。希望本文檔能幫助您更好地對接和使用該 API。如有任何問題，請隨時聯繫我們的技術支持團隊。 +透過本文檔，您已經瞭解了如何使用 OpenAI Embeddings API 輕鬆使用官方 OpenAI 的詞向量生成功能。希望本文檔能幫助您更好地串接和使用該 API。如有任何問題，請隨時聯絡我們的技術支援團隊。 diff --git a/zh-Hant/guides/platform/wework_bot.mdx b/zh-Hant/guides/platform/wework_bot.mdx new file mode 100644 index 000000000..d04b41f47 --- /dev/null +++ b/zh-Hant/guides/platform/wework_bot.mdx @@ -0,0 +1,56 @@ +--- +title: "企業微信機器人" +description: "Platform 整合指南 - Ace Data Cloud" +--- + +部署屬於自己的企業微信帳號實例，使用手機企業微信掃碼登入，透過 REST API 或 MCP 讀取帳號、聯絡人、會話與本機同步訊息。實例對應一般企業微信帳號，無需私有化伺服器或企業信箱網域設定。 + +目前為 Alpha。帳號讀取已完成真實會話驗證；本人文字發送及事件讀回已完成真實驗收；其他聯絡人、群組操作和新實例復原仍需完成部署環境驗收。媒體發送、引用回覆、真實 @、群組成員管理和送達回條尚未開放。請以實例 `/api/capabilities` 回傳值為準。 + +## 部署與登入 + +在 Deployment 分類開通服務並選擇實例時長方案。部署後開啟管理頁面，使用帳號本人的企業微信掃碼；如需手機確認或其他登入步驟，開啟遠端桌面並輸入該實例的桌面密碼。API 憑據與桌面密碼獨立。登入資料保存在實例磁碟中，重建容器會保留磁碟；刪除磁碟會刪除本機會話。 + +每個實例獨立收費，按已購買的時長運行。REST / MCP 呼叫不按訊息另行收費，實際價格以方案頁面為準。目前預設參考微信機器人的時長方案，最終開放前需結合運行資源完成定價確認。 + +## API 與 MCP + +使用管理頁面中的實例 API 位址，所有帳號介面攜帶 `Authorization: Bearer <實例 API token>`。這些路徑屬於專屬實例，不是共用 API 閘道。MCP 位址為實例位址加 `/mcp/`，使用相同 Bearer token。 + +| 介面 | 作用 | +| -------------------------------------------------------- | ------------------------------------------- | +| `GET /api/status`、`GET /api/auth/status` | 帳號是否就緒與能力清單 | +| `GET /api/auth/qr` | 目前登入 QR Code PNG Base64 | +| `GET /api/account` | 目前帳號 | +| `GET /api/contacts?kind=all` | 內部同事與外部聯絡人，可指定 internal / external | +| `GET /api/conversations` | 本機會話，保留原始會話 ID | +| `GET /api/messages` | 本機同步訊息；conversation_id、after_rowid、limit 參數 | +| `POST /api/search` | 聯絡人、會話與本機文字搜尋 | +| `POST /api/messages` | 文字發送非同步任務，必須提供 Idempotency-Key | +| `POST /api/messages/send` | 相同發送入口，支援單個或多個目標 | +| `GET /api/groups/{conversation_id}` | 本機同步的群組資訊及成員 | +| `GET /api/tasks` | 最近任務及各目標的結果 | +| `GET /api/tasks/{id}` | 查詢發送結果 | +| `POST /api/tasks/{id}/cancel` | 取消尚未開始的任務 | +| `POST /api/runtime/pause`、`POST /api/runtime/resume` | 暫停自動化；本人驗證後恢復 | +| `GET /api/diagnostics`、`GET /api/diagnostics/screenshot` | 實例狀態與目前畫面，均需驗證 | +| `GET /api/events?after=0` | 可復原游標的訊息事件 | +| `WS /ws` | 訊息事件串流，Bearer 驗證 | + +發送內容包含 `target`、`type: "text"` 和 `text`。`target` 接受會話 ID、聯絡人 ID、企業使用者 ID 或唯一的完整名稱；優先使用 ID；顯示名稱仍無法唯一定位時，實例會拒絕操作，不會猜測對象。沒有本機會話的聯絡人會先透過用戶端開啟會話，並核對實際會話 ID 後發送。請求標頭 `Idempotency-Key` 是 8–128 位字母、數字或 `_.:-`。同一操作重複請求必須重複使用相同金鑰和相同請求內容。 + +將 `target` 換為 `targets` 陣列可循序發送給 1–50 個明確指定的目標。兩者不能同時提供。全部目標先完成身分解析，指向同一對象的不同別名會被拒絕。某一目標失敗後停止後續發送，任務結果逐項記錄 `succeeded`、`failed`、`unknown` 或 `not_attempted`；不要把部分成功當成全部成功。此流程還需在部署環境完成指定聯絡人的真實驗收。 + +任務可能處於 queued、running、submitting、succeeded、failed、unknown 或 cancelled。`succeeded` 表示提交後在對應會話記錄中找到了準確文字及伺服器訊息 ID，`delivered` 仍為 null，不代表對方已收到。unknown 表示結果不明確，請檢查歷史記錄，不要用新金鑰重複發送。實例不會自動重發中斷的任務。 + +歷史僅包含用戶端已經同步的內容，不能保證全部歷史。非文字訊息可能回傳 unknown 類型，附件下載尚未開放。事件保留最近 10,000 筆，`gap` 表示游標已超出保留視窗。首次連線不會把舊歷史當作新訊息重播。 + +訊息歷史中的 `server_accepted` 和 `server_id` 可用於核對伺服器是否已接受本機訊息；僅出現本機記錄而沒有伺服器 ID 時，不能認定發送成功。這些欄位不代表接收方已收到或閱讀。事件記錄保留產生時的狀態，查詢目前確認狀態應使用訊息歷史介面。 + +## 帳號和憑據 + +僅登入本人有權操作的帳號。將 API token 設定到可信任應用程式中；它可存取該實例的帳號資料。不要將密碼、QR Code 或聊天截圖發布到公開位置。暫停實例會中斷即時事件。帳號登出或手機端移除裝置後，需要重新登入。 + +目前文字輸入只支援單行，換行會在發送前明確拒絕。用戶端要求安全驗證或重新登入時，應由帳號本人在遠端桌面完成；實例不會繞過驗證。驗證中斷後的任務可能回傳 unknown，請先查詢訊息記錄，不要以新冪等金鑰重發。 + +識別到安全驗證提示、帳號登出或變更後，自動化佇列會持久化暫停。完成手機驗證後，可透過實例控制台「驗證後恢復」繼續尚未執行的任務；已經提交但結果不確定的任務不會重發。正常遠端辦公也可能觸發企業微信安全驗證。官方說明的驗證後 24 小時不再鎖定視窗，不代表已經消除偵測，也不代表實例可以保證長期無人值守。