diff --git a/ar/guides/aichat/aichat2_conversations.mdx b/ar/guides/aichat/aichat2_conversations.mdx index 924c9bdc8..e69f409f7 100644 --- a/ar/guides/aichat/aichat2_conversations.mdx +++ b/ar/guides/aichat/aichat2_conversations.mdx @@ -1,36 +1,36 @@ --- -title: "دليل تكامل AI Chat v2 API" +title: "شرح تكامل AI Chat v2 API" description: "AI Dialogue API guide - Ace Data Cloud" --- -يُعد AI Chat v2 API (`/aichat2/conversations`) واجهة محادثة من الجيل الجديد، وهو إصدار مطور بالكامل من [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). واستنادًا إلى بساطة v1 وإدارته للمحادثات متعددة الجولات، فإنه يوسّع: +يُعد AI Chat v2 API (`/aichat2/conversations`) واجهة المحادثة من الجيل الجديد، وهو إصدار مطوّر بشكل شامل من [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). يستند إلى بساطة v1 وإدارة المحادثات متعددة الجولات، ويوسّعها عبر: -- **إدخال مستخدم متعدد الوسائط**: من خلال حقل `message` منظّم، يمكن إرسال نص + صور + كتل ملفات مباشرةً، دون الحاجة إلى إرفاقها بشكل غير مباشر باستخدام `references` أولًا. -- **استدعاء أدوات بأسلوب Agent**: يتضمن مجموعة مدمجة من أدوات البحث عبر الإنترنت، وجلب صفحات الويب، وقراءة الملفات، وغيرها، كما يمكن إرفاق خوادم MCP المصرح بها من المستخدم (Google Drive وNotion وSlack وGitHub وغيرها)، بحيث يستطيع النموذج استدعاء الأدوات ذاتيًا عدة مرات ضمن طلب واحد لإكمال المهام المعقدة. -- **أحداث تدفق منظّمة**: من خلال `accept: text/event-stream` أو `application/x-ndjson`، يمكن الحصول على أحداث مثل `text_delta` و`tool_use` و`tool_result` و`thinking` و`citation` و`card` و`artifact` لكل token على حدة، مما يسهّل عرضها بشكل منفصل في الواجهة الأمامية وفقًا لنوعها. -- **قابل للمقاطعة / الاستئناف**: عندما يحتاج النموذج إلى معلومات إضافية من المستخدم، فإنه يصدر حدث `ask_user_question` ويتوقف مؤقتًا؛ ويمكن متابعة العملية في الاستدعاء التالي عبر تعبئة الإجابة باستخدام `tool_results`. -- **إجراءات CRUD جديدة**: يمكن إكمال `retrieve` / `retrieve_batch` / `update` / `delete` عبر حقل `action` على نفس endpoint، دون الحاجة إلى API إضافي لإدارة المحادثات. -- **قائمة نماذج يتم تحديثها باستمرار**: تدعم افتراضيًا نماذج حديثة مثل GPT-5.4 وClaude Opus 4.8 وClaude Sonnet 4.6 وGemini 3.1 Pro وGLM 5.1 وDeepSeek V4 وKimi K3 وغيرها. +- **إدخال مستخدم متعدد الوسائط**: أرسل النص + الصور + كتل الملفات مباشرةً عبر حقل `message` المنظّم، دون الحاجة إلى إرفاقها بشكل غير مباشر باستخدام `references` أولًا. +- **استدعاء أدوات بأسلوب Agent**: يتضمن مجموعة أدوات مدمجة للبحث عبر الإنترنت وجلب صفحات الويب وقراءة الملفات وغيرها، كما يمكن إرفاق خوادم MCP المصرّح بها من المستخدم (Google Drive وNotion وSlack وGitHub وغيرها)، بحيث يستطيع النموذج استدعاء الأدوات ذاتيًا عدة مرات ضمن طلب واحد لإكمال المهام المعقدة. +- **أحداث تدفق منظّمة**: عبر `accept: text/event-stream` أو `application/x-ndjson`، يمكنك الحصول على أحداث مثل `text_delta` و`tool_use` و`tool_result` و`thinking` و`citation` و`card` و`artifact` لكل token، مما يسهّل عرض كل نوع على حدة في الواجهة الأمامية. +- **قابل للمقاطعة / الاستئناف**: عندما يحتاج النموذج إلى معلومات إضافية من المستخدم، سيصدر حدث `ask_user_question` ويتوقف مؤقتًا؛ وفي الاستدعاء التالي، يكفي إعادة ملء الإجابة عبر `tool_results` للمتابعة. +- **إجراءات CRUD جديدة**: أكمل `retrieve` / `retrieve_batch` / `update` / `delete` عبر حقل `action` على نفس endpoint، دون الحاجة إلى API إضافية لإدارة المحادثات. +- **قائمة نماذج يتم تحديثها باستمرار**: يتصل افتراضيًا بنماذج معاصرة مثل GPT-5.4 وClaude Opus 4.8 وClaude Sonnet 4.6 وGemini 3.1 Pro وGLM 5.1 وDeepSeek V4 وKimi K3 وغيرها. -وفي الوقت نفسه، فهو **متوافق تمامًا مع v1 من حيث جسم الطلب**: يكفي تمرير `model` + `question` (+ اختياريًا `stateful` / `id` / `references` / `preset`) للحصول على استجابة JSON من `{answer, id}` مكافئة لـ v1، لذا لا تحتاج إلى إعادة كتابة العميل عند الترحيل من `/aichat/conversations`، بل يكفي تغيير المسار إلى `/aichat2/conversations`. +وفي الوقت نفسه، فهو **متوافق بالكامل مع v1 من ناحية جسم الطلب**: يكفي تمرير `model` + `question` (+ اختياريًا `stateful` / `id` / `references` / `preset`) للحصول على استجابة JSON من `{answer, id}` مكافئة لـ v1، لذا لا تحتاج إلى إعادة كتابة العميل عند الترحيل من `/aichat/conversations`، بل يكفي تغيير المسار إلى `/aichat2/conversations`. > إذا كنت تستخدم حاليًا `/aichat/conversations`، فستستمر الواجهة القديمة في تقديم الخدمة، ويمكنك الترحيل بالوتيرة التي تناسبك. ## عملية التقديم -لاستخدام AI Chat v2 API، انتقل أولًا إلى [وحدة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. +لاستخدام AI Chat v2 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). > 📘 الوثائق الكاملة: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## الاستخدام الأساسي -إن أبسط طريقة للاستخدام مطابقة تمامًا لـ v1: مرّر `model` + `question`، واحصل على `{answer, id}`. +أبسط استخدام مطابق تمامًا لـ v1: مرّر `model` + `question`، واحصل على `{answer, id}`. مثال CURL: @@ -45,7 +45,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -النتيجة المعادة: +النتيجة المُعادة: ```json { @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -يمكن رؤية قيم `model` المتاحة مباشرةً من القائمة المنسدلة في لوحة Try على اليمين، وتشمل الفئات الشائعة: +يمكن الاطلاع مباشرةً على قيم `model` المتاحة من القائمة المنسدلة في لوحة Try على اليمين، وتشمل الفئات الشائعة: - OpenAI: `gpt-5.4-mini` و`gpt-5.4-nano` و`gpt-5.2-pro` و`gpt-5.1-all` و`gpt-5-all` و`gpt-4.1` و`gpt-4o` و`gpt-4o-image` و`o3` و`o4-mini` وغيرها - Anthropic: `claude-opus-4-8` و`claude-opus-4-7` و`claude-opus-4-6` و`claude-opus-4-5-20251101` و`claude-sonnet-4-6` و`claude-sonnet-4-5-20250929` و`claude-haiku-4-5-20251001` وغيرها @@ -88,9 +88,9 @@ print(response.json()) للاطلاع على قواعد التسعير المحددة، راجع بطاقة Pricing في صفحة الخدمة. -## محادثات متعددة الجولات +## محادثة متعددة الجولات -كما في v1، مرّر `stateful: true` لتفعيل حفظ المحادثة، وستعيد API قيمة `id`؛ وفي الطلبات اللاحقة، يكفي إعادة إرسال `id` لمتابعة المحادثة، دون الحاجة إلى إدارة سجل messages بنفسك. +كما في v1، مرّر `stateful: true` لتفعيل حفظ المحادثة، وستُرجع API قيمة `id`؛ وفي الطلبات اللاحقة، يكفي إعادة إرسال `id` لمتابعة المحادثة، دون الحاجة إلى إدارة سجل messages بنفسك. الطلب الأول: @@ -115,7 +115,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -الطلب الثاني، مع تضمين نفس `id`: +الطلب الثاني، مع تضمين `id` نفسه: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -136,17 +136,17 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> القيمة الافتراضية لـ `stateful` هي `true`، وحذفها مكافئ لتمرير `true` صراحةً. إذا كنت لا تريد أن يحفظ الخادم هذه الجولة من المحادثة، يمكنك تعيين `stateful: false` صراحةً. +> القيمة الافتراضية لـ `stateful` هي `true`، وحذفها يعادل تمرير `true` بشكل صريح. إذا كنت لا ترغب في أن يحفظ الخادم هذه الجولة من المحادثة، يمكنك تعيين `stateful: false` بشكل صريح. ## الاستجابة المتدفقة -يدعم v2 صيغتين للتدفق، ويتم الاختيار وفقًا لترويسة `accept`: +يدعم الإصدار v2 تنسيقين للتدفق، ويتم الاختيار وفقًا لترويسة `accept`: | السيناريو | `accept` | شكل البيانات | | --------------------- | ---------------------- | ------------------------------------------ | -| واجهة ويب / EventSource | `text/event-stream` | `data: {json}\n\n`، والسطر الأخير هو `data: [DONE]\n\n` | +| واجهة ويب أمامية / EventSource | `text/event-stream` | `data: {json}\n\n`، والسطر الأخير `data: [DONE]\n\n` | | خادم / CLI / تحليل تدفق Node | `application/x-ndjson` | كائن JSON واحد في كل سطر | -| لا حاجة إلى التدفق | `application/json`（الافتراضي） | إرجاع `{answer, id}` دفعةً واحدة | +| لا حاجة إلى التدفق | `application/json`（افتراضي） | إرجاع `{answer, id}` دفعة واحدة | ### مثال NDJSON @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -كل سطر في NDJSON هو حدث منظم، والأكثر شيوعًا هو `text_delta`: +كل سطر في NDJSON هو حدث منظّم، وأكثرها شيوعًا هو `text_delta`: ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +195,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: ### مثال SSE -استخدام `EventSource` في المتصفح لا يدعم تخصيص نص الطلب، ويوصى باستخدام `fetch` + التحليل اليدوي بالتقسيم حسب `\n\n`: +لا يدعم استخدام `EventSource` في المتصفح نص طلب مخصصًا، ويُوصى باستخدام `fetch` + التحليل اليدوي بالتقسيم وفقًا لـ `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +236,24 @@ while (true) { | `type` | المعنى | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | مقطع نصي تدريجي من إجابة المساعد. يشير `content` إلى المحتوى الجديد؛ وللتوافق مع v1، يحمل الحدث نفسه أيضًا `delta_answer` (يساوي `content`) و`id`. | +| `text_delta` | مقطع نصي تزايدي من إجابة المساعد. يمثل `content` المحتوى الجديد؛ وللتوافق مع v1، يحمل الحدث نفسه أيضًا `delta_answer` (يساوي `content`) و`id`. | | `thinking` | عملية تفكير النموذج (تظهر فقط عندما يكشف النموذج المحدد عن reasoning). | | `tool_use` | يقرر النموذج استدعاء أداة، ويحمل الحدث `tool_id` و`tool_name` و`input`. | -| `tool_result` | نتيجة تنفيذ الأداة، وتُقرن مع `tool_use` السابقة عبر `tool_id`، ويشير `is_error` إلى ما إذا كان التنفيذ قد فشل. | -| `card` | بطاقة منظمة ناتجة من الأداة (مثل الصور ومعاينات الروابط)، ومناسبة للعرض المباشر. | -| `citation` | عنوان URL للمصدر المستخدم لإضافة مرجع إلى مقطع النص المقابل. | -| `ask_user_question` | يصدر عندما يحتاج النموذج إلى أن يضيف المستخدم معلومات، وتدخل المحادثة في حالة `awaiting_user_input`، راجع [استئناف المحادثة الموقوفة](#恢复暂停的对话) أدناه. | -| `artifact` | منتج مستقل ينشئه النموذج (مثل كتلة برمجية أو مستند)، يمكن حفظه أو تنزيله. | -| `system_message` | رسالة تنبيه من النظام (ليست محتوى المستخدم أو المساعد)، وتُستخدم فقط لتنبيهات واجهة المستخدم. | -| `compact` | حدث تم فيه ضغط السياق الداخلي، ولا يحتاج إلى معالجة خاصة. | +| `tool_result` | نتيجة تنفيذ الأداة، وتقترن مع `tool_use` السابقة عبر `tool_id`، ويشير `is_error` إلى ما إذا كان التنفيذ قد فشل. | +| `card` | بطاقة منظّمة تنتجها الأداة (مثل الصور ومعاينات الروابط)، ومناسبة للعرض المباشر. | +| `citation` | يُستخدم لتكملة عنوان URL للمصدر المرجعي لمقطع النص المقابل. | +| `ask_user_question` | يصدر عندما يحتاج النموذج إلى أن يضيف المستخدم معلومات، وتدخل المحادثة في حالة `awaiting_user_input`، راجع [استئناف المحادثات المتوقفة](#恢复暂停的对话) أدناه. | +| `artifact` | مخرج مستقل ينشئه النموذج (مثل كتلة كود أو مستند)، ويمكن حفظه أو تنزيله. | +| `system_message` | معلومات مطالبة من النظام (ليست محتوى المستخدم أو المساعد)، وتُستخدم فقط لتنبيهات واجهة المستخدم. | +| `compact` | حدث تم فيه ضغط السياق الداخلي، ولا يتطلب معالجة خاصة. | | `error` | حدث خطأ في هذه الجولة، ويصف `message` محتوى الخطأ. | -| `done` | انتهت الاستجابة المتدفقة، وتحمل `usage` (بما في ذلك `prompt_tokens` / `completion_tokens` / `total_tokens`) و`terminal_reason`. | +| `done` | تنتهي الاستجابة المتدفقة، وتحمل `usage` (بما في ذلك `prompt_tokens` / `completion_tokens` / `total_tokens`) و`terminal_reason`. | -بالنسبة إلى العملاء الذين يهتمون فقط بالإجابة النهائية، فإن تجميع `content` لجميع أحداث `text_delta` يعادل `answer` في وضع `application/json`. +بالنسبة إلى العملاء الذين يهتمون فقط بالإجابة النهائية، فإن تجميع `content` لكل `text_delta` يعادل `answer` في وضع `application/json`. ## إدخال متعدد الوسائط -إذا كان إدخال المستخدم يتضمن صورة أو ملفًا، مرر `message` (مصفوفة) بدلًا من `question`. كل عنصر في المصفوفة هو كتلة محتوى: +إذا كان إدخال المستخدم يتضمن صورة أو ملفًا، فمرّر `message` (مصفوفة) بدلًا من `question`. كل عنصر في المصفوفة هو كتلة محتوى: ```json { @@ -270,50 +270,50 @@ while (true) { - `text` — نص عادي، وحقل `text` مطلوب. - `image_url` — صورة، وحقل `image_url.url` مطلوب. -- `file_url` — ملف (مثل PDF وCSV وTXT)، وحقل `file_url.url` مطلوب. +- `file_url` — ملف (PDF أو CSV أو TXT وغيرها)، وحقل `file_url.url` مطلوب. ### العلاقة مع `references` في v1 -للتوافق مع العملاء القدامى، لا يزال v2 يتعرف على الحقل `references: ["https://...", ...]`: +للتوافق مع العملاء القدامى، لا يزال v2 يتعرّف على الحقل `references: ["https://...", ...]`: - إذا كانت لاحقة URL هي `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`، فسيتم تحويلها تلقائيًا إلى كتلة `image_url`؛ -- الامتدادات الأخرى تتحول إلى كتلة `file_url`؛ +- يتم تحويل الامتدادات الأخرى إلى كتلة `file_url`؛ - إذا تم توفير `question` أيضًا في الوقت نفسه، فسيتم وضعه في المقدمة ككتلة `text`. -لذلك، إذا كنت تريد فقط الترحيل من v1 ولا تريد تعديل جسم الطلب، فما عليك سوى تغيير المسار إلى `/aichat2/conversations`، وسيستمر استخدام `references` الأصلي بالعمل كالمعتاد. +لذلك، إذا كنت تريد فقط الترحيل من v1 ولا تريد تعديل جسم الطلب، فكل ما عليك هو تغيير المسار إلى `/aichat2/conversations`، وسيستمر استخدام `references` الأصلي في العمل كالمعتاد. -إذا كنت تحتاج إلى تحكم أدق (مثل وضع صور متعددة بين النصوص، أو عندما يكون الترتيب مهمًا) فاستخدم مصفوفة `message` مباشرةً. +إذا كنت تحتاج إلى تحكم أكثر دقة (مثل وضع عدة صور بين النصوص، أو عندما يكون الترتيب مهمًا جدًا)، فاستخدم مصفوفة `message` مباشرةً. -## استدعاء الأدوات و MCP +## استدعاءات الأدوات و MCP -التحسين الأساسي في v2 هو أن النموذج يمكنه استدعاء الأدوات ذاتيًا لإكمال المهام متعددة الخطوات، **وهذا مفعّل افتراضيًا**، ولا يحتاج العميل إلى إجراء أي إعدادات إضافية في الطلب. السيناريوهات الشائعة: +التحسين الأساسي في v2 هو أن النموذج يمكنه استدعاء الأدوات بشكل مستقل لإكمال المهام متعددة الخطوات، **وهذا مفعّل افتراضيًا**، ولا يحتاج العميل إلى إجراء أي إعدادات إضافية في الطلب. السيناريوهات الشائعة: -- يسأل المستخدم: «ساعدني في البحث عن المعارض الجديدة في شنغهاي مؤخرًا» → يستدعي النموذج web search المدمج → يرتب النتائج في إجابة. -- يسأل المستخدم: «اقرأ هذا الـ PDF ثم اكتب ملخصًا» → يستدعي النموذج file_read → يكتب الملخص. -- يكون المستخدم قد فوّض Google Drive / GitHub / Notion وغيرها في [Connections](https://platform.acedata.cloud/connections) → يمكن للنموذج استدعاء أدوات MCP المقابلة لقراءة بياناته وكتابتها. +- يسأل المستخدم: «ساعدني في البحث عن المعارض الجديدة في شنغهاي مؤخرًا» → يستدعي النموذج بحث الويب المدمج → ينظم النتائج في إجابة. +- يسأل المستخدم: «اقرأ ملف PDF هذا ثم اكتب ملخصًا» → يستدعي النموذج file_read → يكتب ملخصًا. +- يكون المستخدم قد فوّض Google Drive / GitHub / Notion وغيرها في [Connections](https://platform.acedata.cloud/connections) → يمكن للنموذج استدعاء أدوات MCP المقابلة لقراءة بياناتها وكتابتها. -في تدفقات NDJSON / SSE، تظهر استدعاءات الأدوات من خلال نوعي الأحداث `tool_use` و`tool_result`، على سبيل المثال: +في تدفقات NDJSON / SSE، يتم عرض استدعاءات الأدوات من خلال نوعي الأحداث `tool_use` و `tool_result`، على سبيل المثال: ```json -{"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} +{"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"معارض شنغهاي ربيع 2026"},"id":"f2f4b3e8-..."} {"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."} -{"type":"text_delta","content":"目前","delta_answer":"目前","id":"f2f4b3e8-..."} -{"type":"text_delta","content":"上海","delta_answer":"上海","id":"f2f4b3e8-..."} +{"type":"text_delta","content":"حاليًا","delta_answer":"حاليًا","id":"f2f4b3e8-..."} +{"type":"text_delta","content":"شنغهاي","delta_answer":"شنغهاي","id":"f2f4b3e8-..."} ... ``` -إذا كنت لا تريد عرض تفاصيل استدعاء الأدوات في الواجهة الأمامية، فما عليك سوى تجاهل أحداث `tool_use` / `tool_result` / `card` / `citation`، إذ إن المخرجات النهائية للنموذج ستستمر في التدفق عبر `text_delta`. +إذا كنت لا تريد عرض تفاصيل استدعاءات الأدوات في الواجهة الأمامية، فما عليك سوى تجاهل أنواع الأحداث `tool_use` / `tool_result` / `card` / `citation`، إذ سيستمر تدفق الإخراج النهائي للنموذج عبر `text_delta`. -يمكن لـ `max_turns` تحديد الحد الأقصى لعدد جولات الاستدعاء الذاتي للأدوات التي يمكن للنموذج تنفيذها في هذا الطلب، ويحدد النظام الأساسي الحد الافتراضي. يمكن لتعيينه بقيمة صغيرة (مثل `max_turns: 1`) فرض إجابة واحدة ومنع أي استدعاءات للأدوات. +يمكن لـ `max_turns` تقييد الحد الأقصى لعدد جولات استدعاء النموذج الذاتي للأدوات في هذا الطلب، ويتراوح من 1 إلى 500، والقيمة الافتراضية هي 500 عند حذفه. يمكن أن يؤدي تعيينه إلى قيمة صغيرة (مثل `max_turns: 1`) إلى فرض إجابة واحدة، وعدم السماح بأي استدعاء للأدوات. -## التنفيذ غير المتزامن والتفويض دون مراقبة +## التنفيذ غير المتزامن والتفويض غير المراقب -إذا كان استدعاؤك يأتي من Webhook للتنبيهات، أو CI/CD، أو نظام مراقبة، أو مهام خلفية أخرى، فيمكنك تعيين `async: true` لجعل الواجهة تعيد معرّف المهمة فورًا وتواصل التنفيذ في الخلفية: +إذا كان استدعاؤك يأتي من Webhook للتنبيهات، أو CI/CD، أو نظام مراقبة، أو مهام خلفية أخرى، يمكنك تعيين `async: true` لجعل الواجهة تُرجع معرّف المهمة فورًا وتستمر في التنفيذ في الخلفية: ```json { "model": "gpt-5.5", "async": true, - "question": "خدمتي أطلقت إنذارًا، استخدم WeChat الشخصي لإشعار مجموعة WeChat «AceDataCloud团队»……" + "question": "خدمتي أطلقت إنذارًا، أرسل إشعارًا إلى مجموعة WeChat «فريق AceDataCloud» باستخدام WeChat الشخصي..." } ``` @@ -328,9 +328,9 @@ while (true) { } ``` -بعد ذلك، يمكنك استخدام `action: retrieve` + `id` للاستعلام عن نتائج المحادثة؛ ويمكنك أيضًا توفير `callback_url`، وبعد اكتمال المهمة سترسل المنصة `{ status, answer, usage, error }` عبر POST إلى عنوان الاستدعاء الخلفي الخاص بك. يجب أن يستخدم `callback_url` بروتوكول `http` / `https`، ولا يمكن إدخال `localhost` أو عنوان IP خاص حرفيًّا مباشرةً. +بعد ذلك، يمكنك استخدام `action: retrieve` + `id` للاستعلام عن نتيجة المحادثة؛ كما يمكنك أيضًا تقديم `callback_url`، وبعد اكتمال المهمة ستقوم المنصة بإرسال `{ status, answer, usage, error }` عبر POST إلى عنوان رد الاتصال الخاص بك. يجب أن يستخدم `callback_url` بروتوكول `http` / `https`، ولا يمكن ملء `localhost` أو عنوان IP خاص حرفيًا مباشرةً. -لا يكون هناك عادةً شخص قادر على النقر للتأكيد في المهام الخلفية. إذا كنت تريد أن تنفذ بعض Skills أو MCP Server إجراءات مثل الإرسال أو النشر أو الكتابة في وضع عدم المراقبة، فيرجى تمرير قائمة التفويض المسبق صراحةً في جسم الطلب: +عادةً لا يوجد شخص يمكنه النقر للتأكيد في المهام الخلفية. إذا كنت تريد أن تقوم بعض Skill أو MCP Server بتنفيذ إجراءات مثل الإرسال، أو النشر، أو الكتابة في الوضع غير المراقب، فالرجاء تمرير قائمة تفويض مسبق صراحةً في جسم الطلب: ```json { @@ -338,13 +338,13 @@ while (true) { "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "خدمتي أطلقت إنذارًا، استخدم WeChat الشخصي لإشعار مجموعة WeChat «AceDataCloud团队»……" + "question": "خدمتي أطلقت إنذارًا، أرسل إشعارًا إلى مجموعة WeChat «فريق AceDataCloud» باستخدام WeChat الشخصي..." } ``` -القيم في `allowed_skills` هي slug للـ Skill المتصل؛ والقيم في `allowed_mcp_servers` هي slug للـ MCP Server المتصل. تظل الـ Skill / MCP Server غير المدرجة ضمن التفويض المسبق قادرة فقط على المعاينة أو dry-run أو رفض تنفيذ عمليات الكتابة في وضع عدم المراقبة. +القيم في `allowed_skills` هي slug للـ Skill المتصلة؛ والقيم في `allowed_mcp_servers` هي slug للـ MCP Server المتصلة. لا يزال بإمكان Skill / MCP Server غير المدرجة في التفويض المسبق في الوضع غير المراقب المعاينة فقط، أو dry-run، أو رفض تنفيذ عمليات الكتابة. -إذا كنت تحتاج إلى تحكم أدق، فيمكنك أيضًا استخدام كائن `unattended_policy` المكافئ: +إذا كنت تحتاج إلى تحكم أكثر دقة، يمكنك أيضًا استخدام كائن `unattended_policy` المكافئ: ```json { @@ -356,26 +356,26 @@ while (true) { } ``` -التفويض المسبق هو هاتان القائمتان بحد ذاتهما: كون القائمة فارغة يعني عدم تفويض أي قدرات، ولا حاجة إلى حقول تبديل إضافية. +التفويض المسبق هو هاتان القائمتان نفسهما: تعني القائمة الفارغة عدم تفويض أي قدرة، ولا حاجة إلى حقل مفتاح إضافي. -ملاحظة: التفويض المسبق يعني فقط أن «هذا الطلب يسمح لهذه القدرات بتجاوز التأكيد البشري في وضع عدم المراقبة». يجب أن يظل الـ Skill المحدد يدعم `--unattended-confirm` أو آلية الأمان المقابلة؛ وإلا فسيستمر في dry-run ولن ينفذ عمليات الكتابة مباشرةً. +ملاحظة: يمثل التفويض المسبق فقط أن «هذا الطلب يسمح لهذه القدرات بتجاوز التأكيد اليدوي في الوضع غير المراقب». يجب أن تدعم Skill المحددة أيضًا `--unattended-confirm` أو آلية الأمان المقابلة؛ وإلا فستستمر في dry-run، ولن تنفذ عمليات الكتابة مباشرةً. -## استئناف المحادثات المعلّقة +## استئناف المحادثات المتوقفة -تجعل بعض الأدوات النموذج «يسأل المستخدم سؤالًا»، وعندها سيصدر النموذج حدث `ask_user_question`، وتتجمد المحادثة في حالة `awaiting_user_input`: +بعض الأدوات تجعل النموذج «يسأل المستخدم سؤالًا»، وعندها يصدر النموذج حدث `ask_user_question`، وتتجمد المحادثة في حالة `awaiting_user_input`: ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "هل تريد أن يكون التقرير المُنشأ بالصينية أم بالإنجليزية؟", + "question": "هل تريد أن يكون التقرير المُنشأ باللغة الصينية أم الإنجليزية؟", "options": ["الصينية", "الإنجليزية"], "id": "f2f4b3e8-..." } ``` -اعرض هذا الحدث كبطاقة في الواجهة الأمامية ليختار المستخدم الإجابة، ثم أرسل الطلب التالي باستخدام نفس `id`، وأعد تعبئة الإجابة عبر `tool_results`: +اعرض هذا الحدث كبطاقة في الواجهة الأمامية ليختار المستخدم الإجابة، ثم ابدأ الطلب التالي باستخدام `id` نفسه، وأعد تعبئة الإجابة عبر `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -389,21 +389,21 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ "tool_results": [ { "tool_use_id": "toolu_01XYZW", - "output": "中文" + "output": "الصينية" } ] }' ``` -يجب أن يكون `tool_use_id` في جسم الطلب **مطابقًا تمامًا** لـ `tool_id` وقت التعليق؛ وسيؤدي عدم التطابق إلى إرجاع 400. عندما يكون `tool_results` موجودًا في الطلب، سيتم تجاهل كل من `question` / `message` / `references`. +يجب أن يكون `tool_use_id` في جسم الطلب **مطابقًا تمامًا** لـ `tool_id` عند التوقف؛ وسيتم إرجاع 400 إذا لم يكن متطابقًا. عند وجود `tool_results` في الطلب في الوقت نفسه، سيتم تجاهل كل من `question` / `message` / `references`. -إذا قرر المستخدم التخلي عن هذا السؤال، فما عليك سوى تمرير `question` / `message` جديد، وستقوم المنصة تلقائيًا بوضع علامة «تخطاه المستخدم» على استدعاء الأداة المعلّق. +إذا قرر المستخدم التخلي عن هذا السؤال، فما عليه سوى تمرير `question` / `message` جديد، وستقوم المنصة تلقائيًا بوضع علامة «تخطاه المستخدم» على استدعاء الأداة المتوقف. ## إدارة المحادثات (CRUD) -يوفر v2 إدارة خفيفة للمحادثات عبر الحقل `action` على نفس endpoint، دون الحاجة إلى إنشاء API إضافي. +يوفر v2 إدارة خفيفة للمحادثات عبر حقل `action` على نفس endpoint، دون الحاجة إلى فتح API إضافي. +### `action: retrieve` —— جلب محادثة -### `action: retrieve` —— جلب محادثة واحدة ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -يعيد مستند المحادثة الكامل (بما في ذلك سجل `messages` و`model` و`title` و`tools_used` وغيرها). +يعيد مستند المحادثة الكامل (بما في ذلك سجل `messages`، و`model`، و`title`، و`tools_used`، وغير ذلك). -### `action: retrieve_batch` —— سرد ملخصات المحادثات +### `action: retrieve_batch` —— إدراج ملخصات المحادثات ```json { @@ -428,9 +428,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -يعيد `{ items: [...], total }`. **لا يتضمن الملخص `messages`**، وهو مناسب لقائمة الشريط الجانبي؛ إذا فتح المستخدم محادثة معينة، فاستخدم بعد ذلك `action: retrieve` لجلب رسائلها الكاملة بشكل منفصل. +يعيد `{ items: [...], total }`. **لا يحتوي الملخص على `messages`**، وهو مناسب لقائمة الشريط الجانبي؛ إذا فتح المستخدم محادثة معيّنة، فاستخدم بعد ذلك `action: retrieve` لجلب رسائلها الكاملة بشكل منفصل. -معلمات التصفية الاختيارية: `user_id`، `application_id`، `model_group`، `model`. +معلمات التصفية الاختيارية: `user_id`، و`application_id`، و`model_group`، و`model`. ### `action: update` —— تغيير العنوان أو إعادة كتابة السجل @@ -442,9 +442,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -يمكن أيضًا تمرير `messages`، لكن الخادم سيجري تحققًا صارمًا من schema (يجب أن تكون بصيغة `ToolUseContent` المطوية)، وسيعيد 400 إذا لم تتوافق. عمومًا، يُنصح باستخدامه فقط لتغيير `title`. +يمكن أيضًا تمرير `messages`، لكن الخادم سيجري تحققًا صارمًا من schema (ويجب أن تكون بصيغة `ToolUseContent` المطوية)، وسيعيد 400 إذا لم تتوافق. عمومًا، يُنصح باستخدامه فقط لتغيير `title`. -### `action: delete` —— حذف محادثة واحدة +### `action: delete` —— حذف محادثة ```json { @@ -453,21 +453,21 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -يعيد `{ id, success: true }`. لا يمكن الاستعادة بعد الحذف، يرجى التأكيد قبل الاستدعاء. +يعيد `{ id, success: true }`. لا يمكن الاستعادة بعد الحذف، يُرجى التأكيد قبل الاستدعاء. ## الترحيل السلس من v1 -إذا كنت تستخدم بالفعل [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations)، فلن تحتاج تقريبًا إلى تعديل الكود للترحيل إلى v2: +إذا كنت تستخدم بالفعل [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations)، فإن الترحيل إلى v2 لا يتطلب تقريبًا أي تعديل في الكود: 1. غيّر URL من `https://api.acedata.cloud/aichat/conversations` إلى `https://api.acedata.cloud/aichat2/conversations`. -2. إذا كنت تمرر سابقًا اسم نموذج v1 (مثل `gpt-3.5` و`gpt-4-browsing` وغيرهما)، فيُوصى عند التبديل إلى v2 بالترقية إلى نماذج حديثة (مثل `gpt-5.4` و`claude-opus-4-8` و`gemini-3.1-pro-preview` وغيرهم). -3. تظل حقول تدفق NDJSON متوافقة مع الإصدارات السابقة: لا يزال كل حدث `text_delta` يحمل `delta_answer` و`id`، لذلك لا يحتاج العميل الذي كان يحلل `delta_answer` سطرًا بسطر إلى أي تعديل. +2. إذا كنت تمرر سابقًا اسم نموذج v1 (مثل `gpt-3.5`، و`gpt-4-browsing`، وغير ذلك)، فيُنصح عند التبديل إلى v2 بالترقية إلى نماذج حديثة (مثل `gpt-5.4`، و`claude-opus-4-8`، و`gemini-3.1-pro-preview`، وغير ذلك). +3. تبقى حقول تدفق NDJSON متوافقة مع الإصدارات السابقة: لا يزال كل حدث `text_delta` يحمل `delta_answer` و`id`، لذلك لا يحتاج العميل الذي كان يحلل `delta_answer` سطرًا بسطر إلى أي تعديل. -بعد الترحيل، يمكنك تفعيل قدرات v2 الجديدة حسب الحاجة (رسالة `message` متعددة الوسائط، وSSE، واستدعاء الأدوات، وCRUD عبر `action`) والتقدم بالوتيرة المناسبة. +بعد الترحيل، يمكن تمكين قدرات v2 الجديدة حسب الحاجة (مثل `message` متعدد الوسائط، وSSE، واستدعاء الأدوات، وCRUD عبر `action`) والتقدم بالوتيرة المناسبة. ## معالجة الأخطاء -تكون استجابة الخطأ موحّدة كالتالي: +استجابة الخطأ موحدة كالتالي: ```json { @@ -481,14 +481,14 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ الأخطاء الشائعة: -- `400 bad_request`: حقول مطلوبة مفقودة، أو عدم تطابق `tool_use_id`، أو schema غير صالح لـ `messages`، وغيرها. -- `401 invalid_token`: ترويسة `authorization` غير صحيحة. -- `404 not_found`: لا توجد المحادثة المقابلة لـ `id` عند استخدام `action: retrieve / update / delete`. -- `429 too_many_requests`: تم تشغيل حد المعدل. -- `500 chat_error`: خطأ من LLM المصدر أو `completion_tokens=0` في هذه الجولة (يُعامل على أنه غير مستهلك، ولن تُفرض رسوم). +- `400 bad_request`: حقول إلزامية مفقودة، أو عدم تطابق `tool_use_id`، أو schema غير صالح لـ `messages`، وغير ذلك. +- `401 invalid_token`: رأس `authorization` غير صحيح. +- `404 not_found`: لا توجد المحادثة المطابقة لـ `id` عند `action: retrieve / update / delete`. +- `429 too_many_requests`: تم تفعيل حد المعدل. +- `500 chat_error`: خطأ من LLM العلوي أو `completion_tokens=0` في هذه الجولة (يُعامل على أنه غير مستهلك، ولن يتم فرض رسوم). في الاستجابة المتدفقة، يُصدر الخطأ كحدث `{"type":"error","message":"..."}`، ثم ينتهي التدفق مباشرةً. ## الخلاصة -ترتقي واجهة AI Chat v2 API بالمحادثات، مع الحفاظ على التوافق مع v1، من «أسئلة وأجوبة أحادية الجولة / متعددة الجولات» إلى «محادثات قابلة للرصد بأسلوب Agent»: إدخال متعدد الوسائط، واستدعاء الأدوات، وإمكانية الإيقاف / الاستئناف، وأحداث منظمة متدفقة، وCRUD مدمج. يُنصح بأن تستخدم عمليات التكامل الجديدة v2 مباشرةً؛ ويمكن لعمليات تكامل v1 الحالية الترحيل بسلاسة على مراحل. إذا كانت لديك أي أسئلة، فيُرجى التواصل مع فريق الدعم الفني لدينا في أي وقت. +يرتقي AI Chat v2 API بالمحادثات، مع الحفاظ على التوافق مع v1، من «أسئلة وأجوبة لجولة واحدة / جولات متعددة» إلى «محادثات قابلة للرصد وموجهة بالـ Agent»: إدخال متعدد الوسائط، واستدعاء الأدوات، وإمكانية الإيقاف / الاستئناف، وأحداث منظمة متدفقة، وCRUD مدمج. يُنصح بالاستفادة من v2 مباشرةً عند التكامل الجديد؛ أما تكاملات v1 الحالية فيمكنها الترحيل بسلاسة على مراحل. إذا كانت لديكم أي أسئلة، يُرجى التواصل مع فريق الدعم الفني لدينا في أي وقت. diff --git a/ar/guides/platform/hermes_managed.mdx b/ar/guides/platform/hermes_managed.mdx index 32319008d..d8e354a0b 100644 --- a/ar/guides/platform/hermes_managed.mdx +++ b/ar/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "نشر Hermes Agent الخاص" +title: "نشر Hermes" description: "Platform API guide - Ace Data Cloud" --- -تقدم Ace Data Cloud مدخل نشر Hermes Agent الخاص. هذا المدخل هو خدمة خاضعة للتحكم، وتكون إمكانية الاستخدام والموارد المتاحة وفقًا لما يظهر حاليًا في وحدة التحكم. +إنشاء مثيل حاوية Hermes مستقل لكل Application. يُستخدم افتراضيًا صورة أساسية بإصدار ثابت، مع الاحتفاظ بالوظائف الأصلية؛ وتوفر المنصة الشراء والتجديد والتخزين الدائم وإدارة النشر. -## خطوات الاستخدام +## الإنشاء والشراء -1. ابحث عن **نشر Hermes Agent الخاص** في المنصة. -2. اختر التكوينات المتاحة وأنشئ الخدمة وفقًا لتعليمات الصفحة. -3. انتظر حتى تظهر حالة الجاهزية في المنصة. -4. استخدم المدخل والبيانات المقدمة في الصفحة للوصول إلى المثيل. -5. أرسل أولاً `Reply only OK`، ثم ابدأ المهمة الحقيقية. +1. افتح [نشر Hermes](https://platform.acedata.cloud/services/hermes) وأنشئ Application. +2. اختر باقة المدة في صفحة الشراء، وأكمل الدفع. +3. ارجع إلى صفحة الإعداد، ويمكنك اختيار نموذج الدردشة الخاص بالمنصة من القائمة المنسدلة، وعرض سعر النموذج الحالي. ستنشئ المنصة بيانات اعتماد API مستقلة لهذا المثيل؛ ويمكنك أيضًا إيقاف تكامل المنصة وإعداده بنفسك في وحدة التحكم الأصلية. +4. اختر إنشاء بيانات اعتماد الوصول تلقائيًا، أو عيّن كلمة مرور/Token قويًا خاصًا بك، ثم ابدأ النشر بعد التأكيد. بيانات اعتماد الوصول وبيانات اعتماد API للنموذج مستقلة عن بعضها. +5. بعد أن يصبح المثيل جاهزًا، احصل على عنوان الوصول وبيانات تسجيل الدخول من صفحة الإدارة. +6. سجّل الدخول إلى وحدة التحكم الأصلية، واضبط موفر النموذج والمفاتيح والقنوات الخاصة بك. -تكون النماذج، والبيانات، والسلوكيات المتعلقة بالتخزين والحذف وفقًا لصفحة الإنشاء ونافذة التأكيد؛ لا تأخذ YAML من دليل Hermes المحلي كعقد نشر على المنصة مباشرة. قم بتصدير البيانات التي تحتاج إلى الاحتفاظ بها قبل الحذف. +تُحتسب رسوم النشر وفق مدة الباقة، وتكون الأسعار المحددة بالدولار الأمريكي والمدة وفقًا لصفحة الشراء. تُحتسب رسوم استدعاء النموذج بشكل منفصل؛ ولا يمنح شراء مدة النشر رصيدًا للنموذج. عند تمكين تكامل المنصة، تفتح بيانات اعتماد API المخصصة فقط واجهة الدردشة المقابلة للنموذج المحدد، وتُحتسب الاستدعاءات بشكل منفصل من رصيدك على المنصة. يتم شراء كل Application وتجديده وإدارته بشكل منفصل. -إذا لم تظهر وحدة التحكم مدخل الإنشاء، فهذا يعني أن الحساب الحالي لم يتم فتحه لهذه الخدمة، يمكنك استخدام [معالج Hermes التفاعلي](https://platform.acedata.cloud/documents/hermes-wizard-integration) أو [التكوين اليدوي](https://platform.acedata.cloud/documents/hermes-manual-integration). +## كلمات المرور وبيانات الاعتماد والإعدادات اللاحقة + +تُضبط بيانات اعتماد الوصول قبل بدء التشغيل الأول. تستخدم طريقة الإنشاء التلقائي بيانات اعتماد عشوائية، ويجب أن تتكون كلمة المرور المخصصة من 16 حرفًا على الأقل، وOpenClaw Token من 32 حرفًا على الأقل. لا تحفظ المسودات كلمات المرور؛ وقد تحتاج إلى إدخالها مجددًا بعد تبديل الصفحة. بعد النشر، لا يمكن إلا لمالك Application والمسؤولين عرض بيانات اعتماد الوصول. + +لا يُعاد استخدام بيانات اعتماد API للنموذج بين المثيلات، وتمتد صلاحيتها مع تجديد النشر، وتُلغى عند حذف المثيل. بعد تهيئة النشر، يُرجى تعديل النماذج والقنوات في وحدة التحكم الأصلية؛ وإذا غيّرت اختيارك إلى نموذج من خدمة أخرى، فاضبط أولًا تفويض الواجهة المقابلة في إدارة بيانات اعتماد المنصة، أو استخدم بيانات الاعتماد المناسبة. لن تؤدي إعادة النشر العادية إلى الكتابة فوق الإعدادات الأصلية. ستُرفض عمليات النشر الجديدة مؤقتًا في بيئات النشر التي لم تجتز التحقق من الإصدار، يُرجى الاتصال بالدعم. + +## الإصدار والبيانات + +تعرض صفحة الإعداد إصدار الصورة المنشور حاليًا. تستخدم المثيلات الجديدة الإصدار المنشور حاليًا للخدمة؛ ولن تُستبدل المثيلات الموجودة تلقائيًا مع تحديثات الدليل. ستطبق إعادة النشر إصدار الخدمة الحالي، يُرجى النسخ الاحتياطي أولًا والتأكد من متطلبات الترقية للإصدار المستخدم. + +يوفر كل مثيل افتراضيًا حدًا أقصى قدره 1 CPU و2 GiB من الذاكرة و10 GiB من التخزين الدائم. يحتفظ إعادة التشغيل ببيانات المثيل. سيؤدي حذف النشر يدويًا أو الاسترداد عند انتهاء الصلاحية إلى حذف التخزين، يُرجى تصدير البيانات التي تحتاج إلى الاحتفاظ بها مسبقًا. + +## التجديد وانتهاء الصلاحية + +جدّد في صفحة الشراء الخاصة بـ Application الحالي، وستمتد فترة الصلاحية وفقًا لقواعد المدة الحالية للمنصة. بعد انتهاء الصلاحية، يتم تعليق نقطة الوصول، ويؤدي التجديد خلال فترة السماح إلى استعادة الوصول؛ وسيتم استرداد المثيل والبيانات بعد تجاوز فترة السماح. يُرجى الرجوع إلى وقت انتهاء الصلاحية وحالة الفوترة وتنبيهات الحذف في صفحة الإدارة. + +## تسجيل الدخول إلى واجهة الإدارة + +انسخ عنوان Dashboard واسم المستخدم `admin` وكلمة المرور من صفحة إدارة النشر، ثم افتحها وسجّل الدخول. تُتاح معلومات تسجيل الدخول فقط لمالك Application ومسؤولي المنصة. يتم إعداد النماذج والمهارات والقنوات في واجهة Hermes الأصلية. + +## الأسئلة الشائعة + +- **لماذا لا يزال المثيل الجديد غير قادر على الرد؟** يعني اكتمال النشر أن الحاوية جاهزة؛ تحتاج إلى إعداد النموذج وبيانات الاعتماد في الواجهة الأصلية قبل بدء الاستخدام. +- **هل توجد إضافات إضافية أو نموذج fallback مثبت مسبقًا؟** لا تُضاف افتراضيًا، اضبطها حسب الحاجة في الواجهة الأصلية. +- **كيف يتم تحديث المثيل الموجود؟** يتم الاحتفاظ بـ Application والطلب الأصليين، ويُستخدم إصدار الخدمة الحالي عند إعادة النشر؛ انسخ البيانات احتياطيًا أولًا وتحقق من توافق الإصدار قبل الترقية. +- **ماذا أفعل عند فشل بدء التشغيل؟** تحقق أولًا من سجلات النشر والأحداث، واضبط النموذج بعد التأكد من أن المثيل جاهز. لا تكشف كلمة مرور المثيل ومفاتيحه في التعليقات العامة أو لقطات الشاشة. diff --git a/ar/guides/platform/wework_bot.mdx b/ar/guides/platform/wework_bot.mdx deleted file mode 100644 index 450591586..000000000 --- a/ar/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/de/guides/aichat/aichat2_conversations.mdx index d9a35ec96..942fb1d7f 100644 --- a/de/guides/aichat/aichat2_conversations.mdx +++ b/de/guides/aichat/aichat2_conversations.mdx @@ -1,36 +1,36 @@ --- -title: "Anleitung zur AI Chat v2 API-Integration" +title: "AI Chat v2 API-Integrationsanleitung" description: "AI Dialogue API guide - Ace Data Cloud" --- -Die AI Chat v2 API (`/aichat2/conversations`) ist eine Dialogschnittstelle der neuen Generation und eine umfassend aktualisierte Version der [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Auf Grundlage der Einfachheit und des gehosteten Mehr-Runden-Dialogs von v1 erweitert sie Folgendes: +Die AI Chat v2 API (`/aichat2/conversations`) ist die Dialogschnittstelle der neuen Generation und eine umfassend aktualisierte Version der [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Auf Grundlage der einfachen, gehosteten Mehrturn-Dialoge von v1 erweitert sie um: -- **Multimodale Benutzereingaben**: Text-, Bild- und Dateiblöcke können direkt über das strukturierte Feld `message` übergeben werden, ohne sie zuerst indirekt über `references` anzuhängen. -- **Agent-basierte Tool-Aufrufe**: Eine Reihe integrierter Tools für Websuche, Webseiten-Abruf, Dateilesen usw. ist enthalten; außerdem können vom Benutzer autorisierte MCP-Server (Google Drive, Notion, Slack, GitHub usw.) eingebunden werden. Das Modell kann Tools innerhalb einer Anfrage mehrfach eigenständig aufrufen, um komplexe Aufgaben abzuschließen. -- **Strukturierte Streaming-Ereignisse**: Über `accept: text/event-stream` oder `application/x-ndjson` können Token für Token Ereignisse wie `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` usw. abgerufen werden, damit sie im Frontend nach ihrem jeweiligen Typ separat gerendert werden können. +- **Multimodale Benutzereingaben**: Über das strukturierte Feld `message` können Text-, Bild- und Dateiblöcke direkt übergeben werden, ohne sie zuvor indirekt über `references` anzuhängen. +- **Agent-basierte Tool-Aufrufe**: Eine Reihe integrierter Tools für Websuche, Abrufen von Webseiten, Lesen von Dateien usw. sowie die Möglichkeit, vom Benutzer autorisierte MCP-Server (Google Drive, Notion, Slack, GitHub usw.) einzubinden. Das Modell kann Tools innerhalb einer Anfrage eigenständig über mehrere Runden aufrufen, um komplexe Aufgaben abzuschließen. +- **Strukturierte Streaming-Ereignisse**: Über `accept: text/event-stream` oder `application/x-ndjson` können Ereignisse wie `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card` und `artifact` tokenweise abgerufen werden, damit sie im Frontend je nach Typ separat gerendert werden können. - **Unterbrechbar / fortsetzbar**: Wenn das Modell zusätzliche Informationen vom Benutzer benötigt, sendet es ein `ask_user_question`-Ereignis und pausiert. Beim nächsten Aufruf kann die Antwort über `tool_results` zurückgegeben werden, um fortzufahren. -- **Neue CRUD-Aktionen**: Über das Feld `action` können auf demselben Endpoint `retrieve` / `retrieve_batch` / `update` / `delete` ausgeführt werden, ohne eine zusätzliche API zur Sitzungsverwaltung zu benötigen. -- **Fortlaufend aktualisierte Modellliste**: Standardmäßig sind aktuelle Modelle wie GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 usw. angebunden. +- **Neue CRUD-Aktionen**: Über das Feld `action` können auf demselben Endpoint `retrieve` / `retrieve_batch` / `update` / `delete` ausgeführt werden, ohne dass eine zusätzliche API zur Sitzungsverwaltung erforderlich ist. +- **Kontinuierlich aktualisierte Modellliste**: Standardmäßig sind aktuelle Modelle wie GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4 und Kimi K3 integriert. -Gleichzeitig ist sie auf Request-Body-Ebene **vollständig abwärtskompatibel mit v1**: Wenn nur `model` + `question` (+ optional `stateful` / `id` / `references` / `preset`) übergeben werden, erhalten Sie eine zu v1 gleichwertige `{answer, id}`-JSON-Antwort. Daher müssen Sie beim Umstieg von `/aichat/conversations` den Client nicht neu schreiben, sondern lediglich den Pfad zu `/aichat2/conversations` ändern. +Gleichzeitig ist sie auf Anfragekörper-Ebene **vollständig abwärtskompatibel mit v1**: Wenn nur `model` + `question` (+ optional `stateful` / `id` / `references` / `preset`) übergeben werden, erhalten Sie eine zu v1 gleichwertige JSON-Antwort `{answer, id}`. Daher muss der Client bei der Migration von `/aichat/conversations` nicht neu geschrieben werden; es genügt, den Pfad zu `/aichat2/conversations` zu ändern. -> Falls Sie derzeit `/aichat/conversations` verwenden, bleibt die alte Schnittstelle weiterhin verfügbar und Sie können in Ihrem eigenen Tempo migrieren. +> Wenn Sie derzeit `/aichat/conversations` verwenden, bleibt die alte Schnittstelle weiterhin verfügbar, und Sie können in Ihrem eigenen Tempo migrieren. ## Antragsprozess -Um die AI Chat v2 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 ihn als Reserve aufzubewahren. +Um die AI Chat v2 API zu verwenden, holen Sie sich zunächst in der [Ace Data Cloud-Konsole](https://platform.acedata.cloud/console/applications) Ihren API-Token und bewahren Sie ihn 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. +Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Anschließend kehren Sie automatisch zu dieser Seite zurück. -**Ein API-Token kann alle Dienste der Plattform aufrufen; es ist nicht erforderlich, für jeden Dienst einen separaten Antrag zu stellen.** Beim ersten Antrag erhalten Sie ein kostenloses Guthaben, mit dem Sie den Dienst kostenlos testen können; bei unzureichendem Guthaben können Sie das allgemeine Guthaben in der [Konsole](https://platform.acedata.cloud/console/coin) aufladen. +**Ein API-Token kann alle Dienste der Plattform aufrufen; Sie müssen ihn nicht für jeden Dienst separat beantragen.** Bei der ersten Beantragung erhalten Sie ein kostenloses Guthaben, um den Dienst kostenlos zu testen; bei unzureichendem Guthaben können Sie in der [Konsole](https://platform.acedata.cloud/console/coin) allgemeines Guthaben aufladen. > 📘 Vollständige Dokumentation: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Grundlegende Verwendung -Die einfachste Verwendung ist vollständig mit v1 identisch: Übergeben Sie `model` + `question` und erhalten Sie `{answer, id}`. +Die einfachste Verwendung ist vollständig identisch mit v1: Übergeben Sie `model` + `question` und erhalten Sie `{answer, id}`. CURL-Beispiel: @@ -45,7 +45,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Rückgabewert: +Rückgabeergebnis: ```json { @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Die verfügbaren `model`-Werte können direkt im Dropdown-Menü des Try-Bereichs auf der rechten Seite angezeigt werden. Häufig verwendete Kategorien umfassen: +Die verfügbaren Werte für `model` können direkt im Dropdown-Menü des Try-Bereichs auf der rechten Seite eingesehen werden. Häufig verwendete Kategorien umfassen: - OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` usw. - Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` usw. @@ -86,11 +86,11 @@ Die verfügbaren `model`-Werte können direkt im Dropdown-Menü des Try-Bereichs - Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` usw. - Zhipu: `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` usw. -Die konkreten Abrechnungsregeln finden Sie auf der Service-Seite in der Pricing-Karte. +Die konkreten Abrechnungsregeln finden Sie auf der Dienstseite in der Pricing-Karte. -## Mehr-Runden-Dialog +## Mehrturn-Dialoge -Wie bei v1 aktiviert die Übergabe von `stateful: true` die Speicherung der Sitzung. Die API gibt eine `id` zurück; bei nachfolgenden Anfragen genügt es, die `id` erneut mitzusenden, um den Dialog fortzusetzen, ohne dass Sie den Nachrichtenverlauf selbst verwalten müssen. +Wie bei v1 aktiviert die Übergabe von `stateful: true` das Speichern der Sitzung. Die API gibt eine `id` zurück; bei nachfolgenden Anfragen genügt es, diese `id` erneut mitzusenden, um den Dialog fortzusetzen, ohne dass Sie den Nachrichtenverlauf selbst verwalten müssen. Erste Anfrage: @@ -136,13 +136,13 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful` ist standardmäßig `true`; das Weglassen ist gleichwertig mit der expliziten Übergabe von `true`. Wenn Sie nicht möchten, dass der Server diese Gesprächsrunde speichert, können Sie explizit `stateful: false` setzen. +> `stateful` ist standardmäßig `true`; das Weglassen ist gleichbedeutend mit der expliziten Übergabe von `true`. Wenn du nicht möchtest, dass der Server diese Gesprächsrunde speichert, kannst du explizit `stateful: false` setzen. -## Streaming-Antwort +## Streaming-Antworten v2 unterstützt zwei Streaming-Formate, die über den `accept`-Header ausgewählt werden: -| Szenario | `accept` | Datenformat | +| Szenario | `accept` | Datenform | | --------------------- | ---------------------- | ------------------------------------------ | | Web-Frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, letzte Zeile `data: [DONE]\n\n` | | Server / CLI / Node-Streaming-Parsing | `application/x-ndjson` | Ein JSON-Objekt pro Zeile | @@ -195,7 +195,7 @@ Jede NDJSON-Zeile ist ein strukturiertes Ereignis; am häufigsten ist `text_delt ### SSE-Beispiel -Die Verwendung von `EventSource` im Browser unterstützt keine benutzerdefinierten Request-Bodys; es wird empfohlen, `fetch` + manuelles Parsen durch Aufteilen bei `\n\n` zu verwenden: +Die Verwendung von `EventSource` im Browser unterstützt keine benutzerdefinierten Request-Bodies; empfohlen wird `fetch` + manuelles Parsen in Scheiben nach `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -232,28 +232,28 @@ while (true) { } ``` -### Typen von Streaming-Ereignissen +### Streaming-Ereignistypen | `type` | Bedeutung | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Inkrementelles Textfragment der Assistentenantwort. `content` ist der neu hinzugefügte Inhalt; zur Kompatibilität mit v1 enthält dasselbe Ereignis außerdem `delta_answer` (gleich `content`) und `id`. | +| `text_delta` | Inkrementelles Textfragment der Assistentenantwort. `content` enthält den neuen Inhalt; zur Kompatibilität mit v1 enthält dasselbe Ereignis auch `delta_answer` (gleich `content`) und `id`. | | `thinking` | Denkprozess des Modells (tritt nur auf, wenn das ausgewählte Modell Reasoning offenlegt). | -| `tool_use` | Das Modell entscheidet sich, ein Tool aufzurufen; das Ereignis enthält `tool_id`, `tool_name`, `input`. | -| `tool_result` | Ausführungsergebnis des Tools, über `tool_id` mit dem vorherigen `tool_use` gekoppelt; `is_error` kennzeichnet, ob es fehlgeschlagen ist. | -| `card` | Strukturierte vom Tool erzeugte Karte (z. B. Bild, Link-Vorschau), geeignet zum direkten Rendern. | +| `tool_use` | Das Modell entscheidet, ein Tool aufzurufen; das Ereignis enthält `tool_id`, `tool_name`, `input`. | +| `tool_result` | Tool-Ausführungsergebnis, über `tool_id` mit dem vorherigen `tool_use` gekoppelt; `is_error` kennzeichnet, ob es fehlgeschlagen ist. | +| `card` | Vom Tool erzeugte strukturierte Karte (z. B. Bild, Link-Vorschau), geeignet zum direkten Rendern. | | `citation` | Quell-URL zur Ergänzung von Zitaten für das entsprechende Textfragment. | -| `ask_user_question` | Wird ausgegeben, wenn das Modell zusätzliche Informationen vom Benutzer benötigt; das Gespräch wechselt in den Status `awaiting_user_input`, siehe unten [Pausierte Gespräche fortsetzen](#Pausierte Gespräche fortsetzen). | -| `artifact` | Eigenständiges vom Modell generiertes Ergebnis (z. B. Codeblock, Dokument), das gespeichert oder heruntergeladen werden kann. | +| `ask_user_question` | Wird ausgegeben, wenn das Modell zusätzliche Informationen vom Benutzer benötigt; das Gespräch wechselt in den Status `awaiting_user_input`, siehe unten [Pausierte Gespräche fortsetzen](#恢复暂停的对话). | +| `artifact` | Eigenständiges vom Modell erzeugtes Ergebnis (z. B. Codeblock, Dokument), das gespeichert oder heruntergeladen werden kann. | | `system_message` | Systemhinweis (kein Benutzer- oder Assistenteninhalt), nur für UI-Hinweise. | -| `compact` | Ereignis, bei dem der interne Kontext komprimiert wurde; keine spezielle Behandlung erforderlich. | +| `compact` | Ereignis, bei dem der interne Kontext komprimiert wurde; keine besondere Behandlung erforderlich. | | `error` | In dieser Runde ist ein Fehler aufgetreten; `message` beschreibt den Fehlerinhalt. | -| `done` | Die Streaming-Antwort ist beendet und enthält `usage` (einschließlich `prompt_tokens` / `completion_tokens` / `total_tokens`) sowie `terminal_reason`. | +| `done` | Streaming-Antwort beendet; enthält `usage` (einschließlich `prompt_tokens` / `completion_tokens` / `total_tokens`) und `terminal_reason`. | -Für Clients, die nur an der endgültigen Antwort interessiert sind, entspricht das Zusammenfügen aller `content`-Werte von `text_delta` dem `answer` im Modus `application/json`. +Für Clients, die sich nur für die endgültige Antwort interessieren, ist das Zusammenfügen aller `content`-Werte von `text_delta` gleichbedeutend mit `answer` im Modus `application/json`. -## Multimodale Eingabe +## Multimodale Eingaben -Wenn die Benutzereingabe Bilder oder Dateien enthält, übergeben Sie `message` (ein Array) anstelle von `question`. Jedes Array-Element ist ein Inhaltsblock: +Wenn die Benutzereingabe Bilder oder Dateien enthält, übergib `message` (ein Array) anstelle von `question`. Jedes Array-Element ist ein Inhaltsblock: ```json { @@ -275,23 +275,23 @@ Unterstützte Blocktypen: ### Beziehung zu v1 `references` Zur Kompatibilität mit alten Clients erkennt v2 weiterhin das Feld `references: ["https://...", ...]`: -- Wenn das URL-Suffix `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif` ist, wird es automatisch in einen `image_url`-Block umgewandelt; -- andere Erweiterungen werden in einen `file_url`-Block umgewandelt; -- wenn gleichzeitig noch `question` bereitgestellt wird, wird es als `text`-Block vorangestellt. +- URL-Suffix ist `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatisch in einen `image_url`-Block umwandeln; +- Andere Erweiterungen in einen `file_url`-Block umwandeln; +- Wenn gleichzeitig auch `question` bereitgestellt wird, diese als `text`-Block voranstellen. -Wenn Sie daher nur von v1 migrieren möchten und den Request-Body nicht ändern wollen, ersetzen Sie einfach den Pfad durch `/aichat2/conversations`; die ursprüngliche Verwendung von `references` funktioniert weiterhin wie gewohnt. +Wenn du daher nur von v1 migrieren möchtest und den Request-Body nicht ändern willst, ersetze einfach den Pfad durch `/aichat2/conversations`; die ursprüngliche Verwendung von `references` funktioniert weiterhin wie gewohnt. -Wenn Sie eine präzisere Steuerung benötigen (z. B. mehrere Bilder zwischen Texten platzieren möchten oder die Reihenfolge wichtig ist), verwenden Sie direkt das `message`-Array. +Wenn eine feinere Steuerung erforderlich ist (zum Beispiel, um mehrere Bilder zwischen Text zu platzieren, oder wenn die Reihenfolge wichtig ist), verwende direkt das `message`-Array. ## Tool-Aufrufe und MCP -Die zentrale Erweiterung von v2 besteht darin, dass das Modell Tools eigenständig aufrufen kann, um mehrstufige Aufgaben zu erledigen, **dies ist standardmäßig aktiviert**, ohne dass der Client zusätzliche Konfigurationen in der Anfrage vornehmen muss. Häufige Szenarien: +Die zentrale Erweiterung von v2 besteht darin, dass das Modell selbstständig Tools aufrufen kann, um mehrstufige Aufgaben zu erledigen. **Dies ist standardmäßig aktiviert**, und der Client muss keine zusätzliche Konfiguration im Request vornehmen. Häufige Szenarien: -- Der Nutzer fragt „Hilf mir, nachzusehen, welche neuen Ausstellungen es kürzlich in Shanghai gibt“ → Das Modell ruft die integrierte Websuche auf → Es bereitet die Ergebnisse zu einer Antwort auf. -- Der Nutzer fragt „Lies dieses PDF und schreibe dann eine Zusammenfassung“ → Das Modell ruft file_read auf → Es schreibt eine Zusammenfassung. -- Der Nutzer hat in [Connections](https://platform.acedata.cloud/connections) Google Drive / GitHub / Notion usw. autorisiert → Das Modell kann die entsprechenden MCP-Tools zum Lesen und Schreiben ihrer Daten aufrufen. +- Der Benutzer fragt „Hilf mir, nach neuen Ausstellungen in Shanghai in letzter Zeit zu suchen“ → Das Modell ruft die integrierte Websuche auf → Es bereitet die Ergebnisse zu einer Antwort auf. +- Der Benutzer fragt „Lies dieses PDF und schreibe dann eine Zusammenfassung“ → Das Modell ruft file_read auf → Es schreibt eine Zusammenfassung. +- Der Benutzer hat Google Drive / GitHub / Notion usw. bereits in [Connections](https://platform.acedata.cloud/connections) autorisiert → Das Modell kann die entsprechenden MCP-Tools aufrufen, um deren Daten zu lesen und zu schreiben. -Im NDJSON-/SSE-Stream werden Tool-Aufrufe durch die beiden Ereignistypen `tool_use` und `tool_result` dargestellt, zum Beispiel: +In NDJSON-/SSE-Streams werden Tool-Aufrufe durch die zwei Ereignistypen `tool_use` und `tool_result` dargestellt, zum Beispiel: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,19 +301,19 @@ Im NDJSON-/SSE-Stream werden Tool-Aufrufe durch die beiden Ereignistypen `tool_u ... ``` -Wenn Sie die Details von Tool-Aufrufen nicht im Frontend anzeigen möchten, ignorieren Sie einfach die Ereignistypen `tool_use` / `tool_result` / `card` / `citation`; die endgültige Ausgabe des Modells wird weiterhin über `text_delta` gestreamt. +Wenn du die Details von Tool-Aufrufen nicht im Frontend anzeigen möchtest, ignoriere einfach die Ereignistypen `tool_use` / `tool_result` / `card` / `citation`; die endgültige Ausgabe des Modells wird weiterhin über `text_delta` gestreamt. -`max_turns` kann die maximale Anzahl der Runden begrenzen, in denen das Modell innerhalb dieser Anfrage selbstständig Tools aufrufen darf; das Standardlimit wird von der Plattform festgelegt. Wenn Sie es niedrig setzen (z. B. `max_turns: 1`), können Sie eine einmalige Antwort erzwingen und jegliche Tool-Aufrufe verhindern. +`max_turns` kann die maximale Anzahl von selbstständigen Tool-Aufrufrunden des Modells in diesem Request begrenzen; der Bereich liegt bei 1–500, bei Auslassung ist der Standardwert 500. Wenn du ihn klein setzt (zum Beispiel `max_turns: 1`), kannst du eine einzelne Antwort erzwingen und jegliche Tool-Aufrufe verbieten. ## Asynchrone Ausführung und unbeaufsichtigte Autorisierung -Wenn Ihr Aufruf von einem Alarm-Webhook, CI/CD, Überwachungssystem oder einer anderen Hintergrundaufgabe stammt, können Sie `async: true` setzen, damit die Schnittstelle sofort eine Aufgaben-ID zurückgibt und im Hintergrund weiterarbeitet: +Wenn dein Aufruf von einem Alarm-Webhook, CI/CD, Überwachungssystem oder einer anderen Hintergrundaufgabe stammt, kannst du `async: true` setzen, damit die Schnittstelle sofort eine Aufgaben-ID zurückgibt und die Ausführung im Hintergrund fortsetzt: ```json { "model": "gpt-5.5", "async": true, - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Mein Dienst hat Alarm ausgelöst, benachrichtige die WeChat-Gruppe „AceDataCloud团队“ über persönliches WeChat …" } ``` @@ -328,9 +328,9 @@ Rückgabebeispiel: } ``` -Danach können Sie mit `action: retrieve` + `id` das Sitzungsergebnis abfragen; Sie können auch `callback_url` bereitstellen, woraufhin die Plattform nach Abschluss der Aufgabe `{ status, answer, usage, error }` per POST an Ihre Callback-Adresse sendet. `callback_url` muss `http` / `https` verwenden und darf weder direkt `localhost` noch eine private IP-Literaladresse enthalten. +Danach kannst du mit `action: retrieve` + `id` das Gesprächsergebnis abfragen; alternativ kannst du `callback_url` angeben, und nach Abschluss der Aufgabe wird die Plattform `{ status, answer, usage, error }` per POST an deine Callback-Adresse senden. `callback_url` muss `http` / `https` verwenden und darf nicht direkt mit `localhost` oder einer privaten IP-Literaladresse angegeben werden. -Bei Hintergrundaufgaben kann normalerweise niemand zur Bestätigung klicken. Wenn Sie möchten, dass bestimmte Skills oder MCP Server im unbeaufsichtigten Modus Aktionen wie Senden, Veröffentlichen oder Schreiben ausführen, übergeben Sie bitte explizit eine Vorautorisierungsliste im Request-Body: +Bei Hintergrundaufgaben kann normalerweise niemand zur Bestätigung klicken. Wenn du möchtest, dass bestimmte Skills oder MCP-Server im unbeaufsichtigten Modus Aktionen wie Senden, Veröffentlichen oder Schreiben ausführen, übergib im Request-Body explizit eine Liste mit Vorabautorisierungen: ```json { @@ -338,13 +338,13 @@ Bei Hintergrundaufgaben kann normalerweise niemand zur Bestätigung klicken. Wen "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Mein Dienst hat Alarm ausgelöst, benachrichtige die WeChat-Gruppe „AceDataCloud团队“ über persönliches WeChat …" } ``` -Die Werte in `allowed_skills` sind die Slugs bereits verbundener Skills; die Werte in `allowed_mcp_servers` sind die Slugs bereits verbundener MCP Server. Skills / MCP Server, die nicht in die Vorautorisierung aufgenommen wurden, können im unbeaufsichtigten Modus weiterhin nur eine Vorschau anzeigen, dry-run ausführen oder die Ausführung von Schreibvorgängen ablehnen. +Die Werte in `allowed_skills` sind die Slugs der verbundenen Skills; die Werte in `allowed_mcp_servers` sind die Slugs der verbundenen MCP-Server. Skills / MCP-Server, die nicht in der Vorabautorisierung aufgeführt sind, können im unbeaufsichtigten Modus weiterhin nur Vorschauen anzeigen, dry-run ausführen oder Schreibvorgänge ablehnen. -Wenn eine feinere Steuerung erforderlich ist, können Sie auch das gleichwertige Objekt `unattended_policy` verwenden: +Wenn eine feinere Steuerung erforderlich ist, kannst du auch das gleichwertige Objekt `unattended_policy` verwenden: ```json { @@ -356,26 +356,26 @@ Wenn eine feinere Steuerung erforderlich ist, können Sie auch das gleichwertige } ``` -Die Vorautorisierung besteht aus diesen beiden Listen selbst: Eine leere Liste autorisiert keinerlei Fähigkeiten, ohne dass ein zusätzliches Schalterfeld erforderlich ist. +Die Vorabautorisierung besteht aus diesen beiden Listen selbst: Eine leere Liste autorisiert keine Fähigkeiten, es ist kein zusätzliches Schalterfeld erforderlich. -Hinweis: Die Vorautorisierung bedeutet nur, dass „diese Fähigkeiten bei dieser Anfrage im unbeaufsichtigten Modus die manuelle Bestätigung überspringen dürfen“. Der jeweilige Skill muss weiterhin `--unattended-confirm` oder den entsprechenden Sicherheitsmechanismus unterstützen; andernfalls bleibt er bei dry-run und führt Schreibvorgänge nicht direkt aus. +Hinweis: Die Vorabautorisierung bedeutet nur: „Dieser Request erlaubt diesen Fähigkeiten, im unbeaufsichtigten Modus die manuelle Bestätigung zu überspringen.“ Der konkrete Skill muss weiterhin `--unattended-confirm` oder den entsprechenden Sicherheitsmechanismus unterstützen; andernfalls bleibt er bei dry-run und führt Schreibvorgänge nicht direkt aus. -## Angehaltene Unterhaltungen fortsetzen +## Pausierte Gespräche fortsetzen -Einige Tools veranlassen das Modell dazu, „dem Nutzer eine Rückfrage zu stellen“. Das Modell sendet dann ein `ask_user_question`-Ereignis, und die Unterhaltung wird im Status `awaiting_user_input` eingefroren: +Einige Tools veranlassen das Modell dazu, „dem Benutzer eine Rückfrage zu stellen“. Das Modell sendet dann ein `ask_user_question`-Ereignis, und das Gespräch wird im Status `awaiting_user_input` eingefroren: ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "你希望生成的报告是中文还是英文？", - "options": ["中文", "英文"], + "question": "Soll der generierte Bericht auf Chinesisch oder Englisch sein?", + "options": ["Chinesisch", "Englisch"], "id": "f2f4b3e8-..." } ``` -Rendern Sie dieses Ereignis im Frontend als Karte, damit der Nutzer eine Antwort auswählen kann, und starten Sie dann mit derselben `id` die nächste Anfrage, indem Sie die Antwort über `tool_results` zurückschreiben: +Rendere dieses Ereignis im Frontend als Karte, damit der Benutzer eine Antwort auswählen kann, und starte dann mit derselben `id` den nächsten Request, wobei die Antwort über `tool_results` zurückgefüllt wird: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -`tool_use_id` im Request-Body **muss** vollständig mit der `tool_id` zum Zeitpunkt der Unterbrechung übereinstimmen; bei Abweichung wird 400 zurückgegeben. Wenn in der Anfrage gleichzeitig `tool_results` vorhanden ist, werden `question` / `message` / `references` alle ignoriert. +`tool_use_id` im Request-Body **muss** vollständig mit `tool_id` zum Zeitpunkt der Pausierung übereinstimmen; bei Abweichung wird 400 zurückgegeben. Wenn gleichzeitig `tool_results` im Request vorhanden ist, werden `question` / `message` / `references` alle ignoriert. -Wenn der Nutzer beschließt, diese Frage aufzugeben, übergeben Sie einfach ein neues `question` / `message`; die Plattform markiert den angehaltenen Tool-Aufruf automatisch als „vom Nutzer übersprungen“. +Wenn der Benutzer beschließt, diese Frage aufzugeben, übergib einfach eine neue `question` / `message`; die Plattform markiert den pausierten Tool-Aufruf automatisch als „vom Benutzer übersprungen“. -## Sitzungsverwaltung (CRUD) +## Gesprächsverwaltung (CRUD) -v2 bietet über das Feld `action` auf demselben Endpoint eine leichtgewichtige Sitzungsverwaltung, ohne dass eine zusätzliche API erforderlich ist. +v2 bietet über das Feld `action` auf demselben Endpoint eine leichtgewichtige Gesprächsverwaltung, ohne dass eine zusätzliche API erforderlich ist. +### `action: retrieve` —— Eine Unterhaltung abrufen -### `action: retrieve` —— Eine Sitzung abrufen ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Gibt das vollständige Sitzungsdokument zurück (einschließlich `messages`-Verlauf, `model`, `title`, `tools_used` usw.). +Gibt das vollständige Unterhaltungsdokument zurück (einschließlich des `messages`-Verlaufs, `model`, `title`, `tools_used` usw.). -### `action: retrieve_batch` —— Sitzungzusammenfassungen auflisten +### `action: retrieve_batch` —— Unterhaltungszusammenfassungen auflisten ```json { @@ -428,7 +428,7 @@ Gibt das vollständige Sitzungsdokument zurück (einschließlich `messages`-Verl } ``` -Gibt `{ items: [...], total }` zurück. **Zusammenfassungen enthalten keine `messages`** und eignen sich für Seitenleistenlisten; wenn ein Benutzer eine Sitzung öffnet, rufen Sie anschließend mit `action: retrieve` deren vollständige Nachrichten separat ab. +Gibt `{ items: [...], total }` zurück. **Zusammenfassungen enthalten keine `messages`** und eignen sich für Seitenleistenlisten; wenn ein Benutzer eine Unterhaltung öffnet, rufen Sie anschließend mit `action: retrieve` separat ihre vollständigen Nachrichten ab. Optionale Filterparameter: `user_id`, `application_id`, `model_group`, `model`. @@ -442,9 +442,9 @@ Optionale Filterparameter: `user_id`, `application_id`, `model_group`, `model`. } ``` -`messages` kann ebenfalls übergeben werden, aber der Server führt eine strenge Schema-Validierung durch (es muss die zusammengefasste `ToolUseContent`-Form sein); bei Abweichungen wird 400 zurückgegeben. Im Allgemeinen wird empfohlen, dies nur zum Ändern von `title` zu verwenden. +`messages` kann ebenfalls übergeben werden, aber der Server führt eine strenge Schema-Validierung durch (muss die zusammengefasste `ToolUseContent`-Form haben); bei Nichtübereinstimmung wird 400 zurückgegeben. Im Allgemeinen wird empfohlen, dies nur zum Ändern von `title` zu verwenden. -### `action: delete` —— Eine Sitzung löschen +### `action: delete` —— Eine Unterhaltung löschen ```json { @@ -453,17 +453,17 @@ Optionale Filterparameter: `user_id`, `application_id`, `model_group`, `model`. } ``` -Gibt `{ id, success: true }` zurück. Nach dem Löschen ist keine Wiederherstellung möglich; bitte bestätigen Sie dies vor dem Aufruf. +Gibt `{ id, success: true }` zurück. Nach dem Löschen kann die Unterhaltung nicht wiederhergestellt werden; bestätigen Sie dies bitte vor dem Aufruf. ## Reibungslose Migration von v1 Wenn Sie bereits [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) verwenden, erfordert die Migration zu v2 nahezu keine Codeänderungen: 1. Ändern Sie die URL von `https://api.acedata.cloud/aichat/conversations` zu `https://api.acedata.cloud/aichat2/conversations`. -2. Wenn Sie zuvor v1-Modellnamen verwendet haben (wie `gpt-3.5`, `gpt-4-browsing` usw.), wird beim Wechsel zu v2 empfohlen, auf aktuelle Modelle zu aktualisieren (wie `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` usw.). -3. Die Felder des NDJSON-Streams bleiben abwärtskompatibel: Jedes `text_delta`-Ereignis enthält weiterhin `delta_answer` und `id`, daher müssen Clients, die ursprünglich `delta_answer` zeilenweise parsen, nicht geändert werden. +2. Wenn Sie zuvor v1-Modellnamen verwendet haben (z. B. `gpt-3.5`, `gpt-4-browsing` usw.), wird beim Wechsel zu v2 empfohlen, auf moderne Modelle zu aktualisieren (z. B. `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` usw.). +3. Die Felder des NDJSON-Streams bleiben abwärtskompatibel: Jedes `text_delta`-Ereignis enthält weiterhin `delta_answer` und `id`, daher müssen Clients, die ursprünglich zeilenweise `delta_answer` analysieren, nicht geändert werden. -Nach der Migration können Sie die neuen Fähigkeiten von v2 nach Bedarf aktivieren (multimodale `message`, SSE, Tool-Aufrufe, `action`-CRUD) und schrittweise vorgehen. +Nach der Migration können Sie bei Bedarf die neuen Fähigkeiten von v2 aktivieren (multimodales `message`, SSE, Tool-Aufrufe, `action`-CRUD) und schrittweise vorgehen. ## Fehlerbehandlung @@ -481,14 +481,14 @@ Fehlerantworten haben ein einheitliches Format: Häufige Fehler: -- `400 bad_request`: Pflichtfelder fehlen, `tool_use_id` stimmt nicht überein, `messages`-Schema ist ungültig usw. +- `400 bad_request`: Fehlende Pflichtfelder, nicht übereinstimmende `tool_use_id`, ungültiges `messages`-Schema usw. - `401 invalid_token`: Der `authorization`-Header ist nicht korrekt. -- `404 not_found`: Die Sitzung, die der `id` bei `action: retrieve / update / delete` entspricht, existiert nicht. -- `429 too_many_requests`: Das Ratenlimit wurde ausgelöst. -- `500 chat_error`: Der vorgelagerte LLM hat einen Fehler gemeldet oder `completion_tokens=0` in dieser Runde (wird als nicht verbraucht behandelt und nicht berechnet). +- `404 not_found`: Die Unterhaltung, die der `id` bei `action: retrieve / update / delete` entspricht, existiert nicht. +- `429 too_many_requests`: Die Ratenbegrenzung wurde ausgelöst. +- `500 chat_error`: Ein Fehler des vorgelagerten LLM oder `completion_tokens=0` in dieser Runde (wird als nicht verbraucht behandelt und nicht berechnet). -In Streaming-Antworten werden Fehler als Ereignis `{"type":"error","message":"..."}` ausgegeben, unmittelbar danach endet der Stream. +In der Streaming-Antwort werden Fehler als Ereignis `{"type":"error","message":"..."}` gesendet, unmittelbar danach endet der Stream. ## Fazit -Die AI Chat v2 API bleibt mit v1 abwärtskompatibel und erweitert Gespräche von „Einzelrunden- / Mehrfachrunden-Fragen und Antworten“ zu „agentenbasierten beobachtbaren Gesprächen“: multimodale Eingaben, Tool-Aufrufe, pausierbar / fortsetzbar, strukturierte Streaming-Ereignisse, integriertes CRUD. Für neue Integrationen wird empfohlen, direkt v2 zu verwenden; bestehende v1-Integrationen können schrittweise reibungslos migriert werden. Bei Fragen kontaktieren Sie jederzeit unser technisches Support-Team. +Die AI Chat v2 API ist abwärtskompatibel mit v1 und erweitert Gespräche von „einzelnen / mehreren Frage-Antwort-Runden“ zu „agentenbasierten, beobachtbaren Gesprächen“: multimodale Eingaben, Tool-Aufrufe, pausierbar / fortsetzbar, strukturierte Streaming-Ereignisse, integriertes CRUD. Für neue Integrationen wird empfohlen, direkt v2 zu verwenden; bestehende v1-Integrationen können schrittweise reibungslos migriert werden. Bei Fragen kontaktieren Sie bitte jederzeit unser technisches Support-Team. diff --git a/de/guides/platform/hermes_managed.mdx b/de/guides/platform/hermes_managed.mdx index 282556106..5830ca470 100644 --- a/de/guides/platform/hermes_managed.mdx +++ b/de/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Private Deployment" +title: "Hermes-Bereitstellung" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud bietet einen Zugang zur privaten Bereitstellung von Hermes Agent. Dieser Zugang ist ein kontrollierter Dienst, die Verfügbarkeit und die wählbaren Ressourcen richten sich nach dem, was aktuell in der Konsole angezeigt wird. +Für jede Application wird eine unabhängige Hermes-Containerinstanz erstellt. Standardmäßig wird ein Basis-Image mit einer festen Release-Version verwendet, wobei die nativen Funktionen erhalten bleiben; die Plattform bietet Kauf, Verlängerung, persistenten Speicher und Bereitstellungsverwaltung. -## Verwendungsschritte +## Erstellen und Kaufen -1. Finden Sie in der Plattform **Hermes Agent Private Deployment**. -2. Wählen Sie gemäß den Seitenhinweisen die verfügbaren Konfigurationen aus und erstellen Sie den Dienst. -3. Warten Sie, bis die Plattform den Status "bereit" anzeigt. -4. Greifen Sie mit dem auf der Seite bereitgestellten Zugang und den Anmeldeinformationen auf die Instanz zu. -5. Senden Sie zuerst `Reply only OK`, bevor Sie mit der eigentlichen Aufgabe beginnen. +1. Öffnen Sie [Hermes-Bereitstellung](https://platform.acedata.cloud/services/hermes) und erstellen Sie eine Application. +2. Wählen Sie auf der Kaufseite ein Laufzeitpaket aus und schließen Sie die Zahlung ab. +3. Kehren Sie zur Konfigurationsseite zurück, wählen Sie ein Plattform-Chatmodell aus der Dropdown-Liste aus und sehen Sie sich den aktuellen Modellpreis an. Die Plattform erstellt für diese Instanz unabhängige API-Zugangsdaten; Sie können auch die Plattformanbindung deaktivieren und die Konfiguration selbst in der nativen Konsole vornehmen. +4. Wählen Sie automatisch generierte Zugangsdaten oder legen Sie Ihr eigenes starkes Passwort/Token fest und starten Sie nach der Bestätigung die Bereitstellung. Zugangsdaten und Modell-API-Zugangsdaten sind voneinander unabhängig. +5. Nachdem die Instanz bereit ist, erhalten Sie auf der Verwaltungsseite die Zugriffsadresse und die Anmeldedaten. +6. Melden Sie sich bei der nativen Konsole an und konfigurieren Sie Ihre eigenen Modellanbieter, Schlüssel und Kanäle. -Modelle, Anmeldeinformationen, Speicher- und Löschverhalten richten sich nach der Erstellungsseite und dem Bestätigungs-Popup; verwenden Sie die YAML aus dem lokalen Hermes-Tutorial nicht direkt als Bereitstellungsvertrag für die Plattform. Exportieren Sie die Daten, die Sie behalten möchten, bevor Sie löschen. +Die Bereitstellungsgebühr wird nach der Paketlaufzeit berechnet; die konkreten USD-Preise und Laufzeiten richten sich nach der Kaufseite. Modellaufrufkosten werden separat berechnet; der Kauf einer Bereitstellungslaufzeit beinhaltet keine Modellguthaben. Wenn die Plattformanbindung aktiviert ist, stellen die dedizierten API-Zugangsdaten nur die Chat-Schnittstelle bereit, die dem ausgewählten Modell entspricht, und Aufrufe werden zusätzlich von Ihrem Plattformguthaben abgerechnet. Jede Application wird separat gekauft, verlängert und verwaltet. -Wenn der Zugang zur Erstellung in der Konsole nicht angezeigt wird, bedeutet dies, dass der aktuelle Account diesen Dienst noch nicht freigeschaltet hat. Sie können stattdessen [Hermes Interaktionsassistent](https://platform.acedata.cloud/documents/hermes-wizard-integration) oder [manuelle Konfiguration](https://platform.acedata.cloud/documents/hermes-manual-integration) verwenden. +## Passwörter, Zugangsdaten und nachfolgende Konfiguration + +Die Zugangsdaten werden vor dem ersten Start festgelegt. Die automatische Generierung verwendet zufällige Zugangsdaten, benutzerdefinierte Passwörter müssen mindestens 16 Zeichen lang sein, OpenClaw-Token mindestens 32 Zeichen. Entwürfe speichern keine Passwörter; nach einem Seitenwechsel müssen diese möglicherweise erneut eingegeben werden. Nach der Bereitstellung können nur der Eigentümer und Administratoren der Application die Zugangsdaten einsehen. + +Die Modell-API-Zugangsdaten jeder Instanz werden nicht gemeinsam genutzt, ihre Gültigkeit wird mit der Verlängerung der Bereitstellung verlängert und sie werden beim Löschen der Instanz widerrufen. Nach der Initialisierung der Bereitstellung ändern Sie Modelle und Kanäle bitte in der nativen Konsole; wenn Sie Modelle anderer Dienste auswählen, passen Sie bitte zuerst in der Plattform-Zugangsdatenverwaltung die Berechtigung für die entsprechende Schnittstelle an oder verwenden Sie die entsprechenden Zugangsdaten. Eine normale erneute Bereitstellung überschreibt die nativen Einstellungen nicht. Bereitstellungsumgebungen ohne Veröffentlichungsvalidierung lehnen neue Bereitstellungen vorübergehend ab; bitte kontaktieren Sie den Support. + +## Versionen und Daten + +Die Konfigurationsseite zeigt die aktuell veröffentlichte Image-Version an. Neue Instanzen verwenden die aktuell veröffentlichte Version des Dienstes; vorhandene Instanzen werden nicht automatisch durch Katalogaktualisierungen ersetzt. Eine erneute Bereitstellung wendet die aktuelle Dienstversion an; sichern Sie bitte zuerst Ihre Daten und bestätigen Sie die Upgrade-Anforderungen der verwendeten Version. + +Jede Instanz stellt standardmäßig 1 CPU, ein Speicherlimit von 2 GiB und 10 GiB persistenten Speicher bereit. Neustarts bewahren die Instanzdaten. Das aktive Löschen einer Bereitstellung oder die Rücknahme bei Ablauf löscht den Speicher; exportieren Sie bitte benötigte Daten im Voraus. + +## Verlängerung und Ablauf + +Verlängern Sie auf der Kaufseite der aktuellen Application; die Gültigkeitsdauer wird gemäß den bestehenden Laufzeitregeln der Plattform verlängert. Nach Ablauf wird der Zugangseinstieg pausiert, eine Verlängerung innerhalb der Kulanzfrist stellt den Zugriff wieder her; nach Überschreiten der Kulanzfrist werden Instanz und Daten zurückgenommen. Maßgeblich sind die Ablaufzeit, der Abrechnungsstatus und die Löschhinweise auf der Verwaltungsseite. + +## Anmeldung an der Verwaltungsoberfläche + +Kopieren Sie auf der Bereitstellungsverwaltungsseite die Dashboard-Adresse, den Benutzernamen `admin` und das Passwort, und öffnen Sie diese zur Anmeldung. Die Anmeldeinformationen werden nur dem Eigentümer dieser Application und Plattformadministratoren bereitgestellt. Modelle, Skills und Kanäle werden in der nativen Hermes-Oberfläche konfiguriert. + +## Häufig gestellte Fragen + +- **Warum kann die neue Instanz noch nicht antworten?** Der Abschluss der Bereitstellung bedeutet, dass der Container bereit ist; Sie müssen Modelle und Zugangsdaten in der nativen Oberfläche konfigurieren, bevor Sie sie verwenden können. +- **Sind zusätzliche Plugins oder Modell-Fallbacks vorinstalliert?** Standardmäßig werden keine hinzugefügt; konfigurieren Sie diese bei Bedarf in der nativen Oberfläche. +- **Wie werden vorhandene Instanzen aktualisiert?** Die ursprüngliche Application und Bestellung bleiben erhalten, bei einer erneuten Bereitstellung wird die aktuelle Dienstversion verwendet; sichern Sie vor dem Upgrade zuerst Daten und prüfen Sie die Versionskompatibilität. +- **Was ist bei einem Startfehler zu tun?** Prüfen Sie zuerst die Bereitstellungsprotokolle und Ereignisse und konfigurieren Sie Modelle erst, nachdem die Instanz bereit ist. Legen Sie Instanzpasswörter und Schlüssel nicht in öffentlichen Kommentaren oder Screenshots offen. diff --git a/de/guides/platform/wework_bot.mdx b/de/guides/platform/wework_bot.mdx deleted file mode 100644 index 5c1aca479..000000000 --- a/de/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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 9f355fb27..77985ba67 100644 --- a/docs.json +++ b/docs.json @@ -461,7 +461,6 @@ "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", @@ -1204,7 +1203,6 @@ "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", @@ -1932,7 +1930,6 @@ "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", @@ -2638,7 +2635,6 @@ "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", @@ -3344,7 +3340,6 @@ "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", @@ -4050,7 +4045,6 @@ "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", @@ -4756,7 +4750,6 @@ "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", @@ -5462,7 +5455,6 @@ "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", @@ -6168,7 +6160,6 @@ "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", @@ -6874,7 +6865,6 @@ "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", @@ -7580,7 +7570,6 @@ "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", @@ -8286,7 +8275,6 @@ "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", @@ -8992,7 +8980,6 @@ "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", @@ -9698,7 +9685,6 @@ "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", @@ -10404,7 +10390,6 @@ "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/aichat/aichat2_conversations.mdx b/el/guides/aichat/aichat2_conversations.mdx index 1049f7c97..22e8993d6 100644 --- a/el/guides/aichat/aichat2_conversations.mdx +++ b/el/guides/aichat/aichat2_conversations.mdx @@ -3,34 +3,34 @@ title: "Οδηγίες ενσωμάτωσης AI Chat v2 API" description: "AI Dialogue API guide - Ace Data Cloud" --- -Το AI Chat v2 API (`/aichat2/conversations`) είναι η νέας γενιάς διεπαφή συνομιλίας και η πλήρως αναβαθμισμένη έκδοση του [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Με βάση την απλότητα και τη διαχειριζόμενη πολυγυρική συνομιλία του v1, επεκτείνει: +Το AI Chat v2 API (`/aichat2/conversations`) είναι η νέα γενιά διεπαφής συνομιλίας και μια πλήρως αναβαθμισμένη έκδοση του [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Με βάση την απλότητα και τη διαχειριζόμενη συνομιλία πολλών γύρων του v1, επεκτείνει: -- **Πολυτροπική είσοδος χρήστη**: Μέσω του δομημένου πεδίου `message` μπορείτε να στείλετε απευθείας μπλοκ κειμένου + εικόνων + αρχείων, χωρίς να χρειάζεται πρώτα να τα επισυνάψετε έμμεσα με `references`. -- **Κλήση εργαλείων τύπου Agent**: Περιλαμβάνει ένα ενσωματωμένο σύνολο εργαλείων για διαδικτυακή αναζήτηση, ανάκτηση ιστοσελίδων, ανάγνωση αρχείων κ.λπ., και μπορεί να προσαρτήσει διακομιστές MCP που έχουν εξουσιοδοτηθεί από τον χρήστη (Google Drive, Notion, Slack, GitHub κ.λπ.). Το μοντέλο μπορεί να καλεί αυτόνομα εργαλεία σε πολλούς γύρους μέσα σε ένα αίτημα, ώστε να ολοκληρώνει σύνθετες εργασίες. -- **Δομημένα συμβάντα ροής**: Μέσω `accept: text/event-stream` ή `application/x-ndjson` μπορείτε να λάβετε συμβάντα όπως `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` κ.λπ. ανά token, διευκολύνοντας την ξεχωριστή απόδοσή τους στο frontend ανά αντίστοιχο τύπο. -- **Διακόψιμο / επαναλήψιμο**: Όταν το μοντέλο χρειάζεται από τον χρήστη συμπληρωματικές πληροφορίες, εκπέμπει ένα συμβάν `ask_user_question` και παύει. Στην επόμενη κλήση, αρκεί να συμπληρώσετε την απάντηση μέσω `tool_results` για να συνεχίσει. -- **Νέες ενέργειες CRUD**: Στο ίδιο endpoint, ολοκληρώστε `retrieve` / `retrieve_batch` / `update` / `delete` μέσω του πεδίου `action`, χωρίς να χρειάζεται επιπλέον API διαχείρισης συνομιλιών. -- **Λίστα μοντέλων που ενημερώνεται συνεχώς**: Από προεπιλογή ενσωματώνονται σύγχρονα μοντέλα όπως GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 κ.λπ. +- **Πολυτροπική είσοδο χρήστη**: Μέσω του δομημένου πεδίου `message`, στέλνετε απευθείας τμήματα κειμένου + εικόνων + αρχείων, χωρίς να χρειάζεται πρώτα έμμεση επισύναψη μέσω `references`. +- **Κλήσεις εργαλείων τύπου Agent**: Περιλαμβάνει ενσωματωμένα εργαλεία όπως αναζήτηση στο διαδίκτυο, ανάκτηση ιστοσελίδων και ανάγνωση αρχείων, ενώ μπορεί επίσης να προσαρτά διακομιστές MCP εξουσιοδοτημένους από τον χρήστη (Google Drive, Notion, Slack, GitHub κ.λπ.). Το μοντέλο μπορεί να καλεί αυτόνομα εργαλεία σε πολλαπλούς γύρους μέσα σε ένα αίτημα για να ολοκληρώσει σύνθετες εργασίες. +- **Δομημένα συμβάντα ροής**: Μέσω `accept: text/event-stream` ή `application/x-ndjson`, μπορείτε να λάβετε συμβάντα όπως `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` ανά token, διευκολύνοντας την ανεξάρτητη απόδοση ανά αντίστοιχο τύπο στο frontend. +- **Διακοπτόμενο / επαναλήψιμο**: Όταν το μοντέλο χρειάζεται πρόσθετες πληροφορίες από τον χρήστη, θα εκδώσει συμβάν `ask_user_question` και θα τεθεί σε παύση. Στην επόμενη κλήση, απλώς συμπληρώστε την απάντηση μέσω `tool_results` για να συνεχίσετε. +- **Νέες ενέργειες CRUD**: Στο ίδιο endpoint, χρησιμοποιήστε το πεδίο `action` για να ολοκληρώσετε `retrieve` / `retrieve_batch` / `update` / `delete`, χωρίς να χρειάζεται επιπλέον API διαχείρισης συνεδριών. +- **Συνεχώς ενημερωμένη λίστα μοντέλων**: Από προεπιλογή υποστηρίζει σύγχρονα μοντέλα όπως GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 κ.λπ. -Παράλληλα, στο επίπεδο του σώματος αιτήματος είναι **πλήρως συμβατό προς τα πίσω με το v1**: αρκεί να στείλετε `model` + `question` (+ προαιρετικά `stateful` / `id` / `references` / `preset`) για να λάβετε απόκριση JSON `{answer, id}` ισοδύναμη με το v1. Επομένως, για μετεγκατάσταση από το `/aichat/conversations`, δεν χρειάζεται να ξαναγράψετε τον client· αρκεί να αλλάξετε τη διαδρομή σε `/aichat2/conversations`. +Ταυτόχρονα, σε επίπεδο σώματος αιτήματος είναι **πλήρως συμβατό προς τα πίσω με το v1**: αρκεί να στείλετε `model` + `question` (+ προαιρετικά `stateful` / `id` / `references` / `preset`) για να λάβετε JSON απόκριση `{answer, id}` ισοδύναμη με το v1. Επομένως, δεν χρειάζεται να ξαναγράψετε τον client κατά τη μετάβαση από το `/aichat/conversations`, απλώς αλλάξτε τη διαδρομή σε `/aichat2/conversations`. -> Εάν χρησιμοποιείτε αυτήν τη στιγμή το `/aichat/conversations`, η παλιά διεπαφή θα συνεχίσει να παρέχεται και μπορείτε να μετεγκατασταθείτε με τον δικό σας ρυθμό. +> Εάν χρησιμοποιείτε αυτήν τη στιγμή το `/aichat/conversations`, η παλιά διεπαφή θα συνεχίσει να παρέχεται και μπορείτε να μεταβείτε με τον δικό σας ρυθμό. ## Διαδικασία αίτησης -Για να χρησιμοποιήσετε το AI Chat v2 API, μεταβείτε πρώτα στην [κονσόλα Ace Data Cloud](https://platform.acedata.cloud/console/applications) για να αποκτήσετε το API Token σας και κρατήστε το ως εφεδρικό. +Για να χρησιμοποιήσετε το AI Chat v2 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). > 📘 Πλήρης τεκμηρίωση: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Βασική χρήση -Η απλούστερη χρήση είναι ακριβώς ίδια με το v1: στείλτε `model` + `question` και λάβετε `{answer, id}`. +Η απλούστερη χρήση είναι ακριβώς η ίδια με το v1: στείλτε `model` + `question` και λάβετε `{answer, id}`. Παράδειγμα CURL: @@ -76,21 +76,21 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Οι διαθέσιμες τιμές για το `model` μπορούν να προβληθούν απευθείας στην αναπτυσσόμενη λίστα του πλαισίου Try στα δεξιά. Οι συνήθεις κατηγορίες περιλαμβάνουν: +Οι διαθέσιμες τιμές `model` μπορούν να προβληθούν απευθείας από την αναπτυσσόμενη λίστα του πίνακα Try στα δεξιά, και οι συνήθεις κατηγορίες περιλαμβάνουν: -- OpenAI: `gpt-5.4-mini`、`gpt-5.4-nano`、`gpt-5.2-pro`、`gpt-5.1-all`、`gpt-5-all`、`gpt-4.1`、`gpt-4o`、`gpt-4o-image`、`o3`、`o4-mini` κ.λπ. -- Anthropic: `claude-opus-4-8`、`claude-opus-4-7`、`claude-opus-4-6`、`claude-opus-4-5-20251101`、`claude-sonnet-4-6`、`claude-sonnet-4-5-20250929`、`claude-haiku-4-5-20251001` κ.λπ. -- Google: `gemini-3.1-pro-preview`、`gemini-3.1-pro-preview`、`gemini-3.1-flash-image`、`gemini-3.1-pro-preview`、`gemini-2.5-flash-lite` κ.λπ. +- OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` κ.λπ. +- Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` κ.λπ. +- Google: `gemini-3.1-pro-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-image`, `gemini-3.1-pro-preview`, `gemini-2.5-flash-lite` κ.λπ. - xAI: `grok-4` κ.λπ. -- DeepSeek: `deepseek-v4-pro`、`deepseek-v4.1-flash`、`deepseek-v4-flash`、`deepseek-v3.2-exp`、`deepseek-r1-0528` κ.λπ. -- Moonshot: `kimi-k3`、`kimi-k2.6`、`kimi-k2.5` κ.λπ. -- Zhipu: `glm-5.3`、`glm-5.2`、`glm-5.1`、`glm-5`、`glm-5-turbo`、`glm-4.7`、`glm-4.5v` κ.λπ. +- DeepSeek: `deepseek-v4-pro`, `deepseek-v4.1-flash`, `deepseek-v4-flash`, `deepseek-v3.2-exp`, `deepseek-r1-0528` κ.λπ. +- Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` κ.λπ. +- Zhipu: `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` κ.λπ. -Για τους συγκεκριμένους κανόνες χρέωσης, ανατρέξτε στην κάρτα Pricing της σελίδας υπηρεσίας. +Για τους συγκεκριμένους κανόνες χρέωσης, ανατρέξτε στην κάρτα Pricing στη σελίδα της υπηρεσίας. -## Πολυγυρική συνομιλία +## Συνομιλία πολλών γύρων -Όπως και στο v1, στείλτε `stateful: true` για να ενεργοποιήσετε την αποθήκευση συνομιλίας. Το API θα επιστρέψει ένα `id`· στα επόμενα αιτήματα, επιστρέψτε το `id` για να συνεχίσετε τη συνομιλία, χωρίς να χρειάζεται να διαχειρίζεστε μόνοι σας το ιστορικό messages. +Όπως και στο v1, στείλτε `stateful: true` για να ενεργοποιήσετε την αποθήκευση συνεδρίας. Το API θα επιστρέψει ένα `id`· στα επόμενα αιτήματα, απλώς συμπεριλάβετε ξανά το `id` για να συνεχίσετε τη συνομιλία, χωρίς να χρειάζεται να διατηρείτε μόνοι σας το ιστορικό των messages. Πρώτο αίτημα: @@ -115,7 +115,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -Δεύτερο αίτημα, συμπεριλάβετε το ίδιο `id`: +Δεύτερο αίτημα, με το ίδιο `id`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -136,17 +136,17 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> Το `stateful` είναι από προεπιλογή `true`· η παράλειψή του είναι ισοδύναμη με τη ρητή μετάδοση του `true`. Εάν δεν θέλετε ο διακομιστής να αποθηκεύσει αυτόν τον γύρο συνομιλίας, μπορείτε να ορίσετε ρητά `stateful: false`. +> Το `stateful` είναι `true` από προεπιλογή, και η παράλειψή του είναι ισοδύναμη με τη ρητή μεταβίβαση του `true`. Εάν δεν θέλετε ο διακομιστής να αποθηκεύσει αυτόν τον γύρο συνομιλίας, μπορείτε να ορίσετε ρητά `stateful: false`. ## Ροϊκή απόκριση -Η v2 υποστηρίζει δύο μορφές ροής, οι οποίες επιλέγονται σύμφωνα με την κεφαλίδα `accept`: +Το v2 υποστηρίζει δύο μορφές ροής, επιλεγμένες σύμφωνα με την κεφαλίδα `accept`: | Σενάριο | `accept` | Μορφή δεδομένων | | --------------------- | ---------------------- | ------------------------------------------ | -| Web frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, η τελευταία γραμμή είναι `data: [DONE]\n\n` | -| Διακομιστής / CLI / ανάλυση ροής Node | `application/x-ndjson` | Ένα αντικείμενο JSON ανά γραμμή | -| Δεν απαιτείται ροή | `application/json`（προεπιλογή） | Εφάπαξ επιστροφή `{answer, id}` | +| Web frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, με τελευταία γραμμή `data: [DONE]\n\n` | +| Διακομιστής / CLI / Ανάλυση ροής Node | `application/x-ndjson` | Ένα αντικείμενο JSON ανά γραμμή | +| Δεν απαιτείται ροή | `application/json`（προεπιλογή） | Επιστρέφει εφάπαξ `{answer, id}` | ### Παράδειγμα NDJSON @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -Κάθε γραμμή NDJSON είναι ένα δομημένο συμβάν, με το πιο συνηθισμένο να είναι το `text_delta`: +Κάθε γραμμή NDJSON είναι ένα δομημένο συμβάν, με συνηθέστερο το `text_delta`: ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +195,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: ### Παράδειγμα SSE -Η χρήση `EventSource` στο πρόγραμμα περιήγησης δεν υποστηρίζει προσαρμοσμένο σώμα αιτήματος· συνιστάται η χρήση `fetch` + χειροκίνητη ανάλυση σε τμήματα με βάση το `\n\n`: +Η χρήση του `EventSource` στην πλευρά του προγράμματος περιήγησης δεν υποστηρίζει προσαρμοσμένο σώμα αιτήματος· συνιστάται η χρήση `fetch` + χειροκίνητη ανάλυση με διαχωρισμό κατά `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +236,24 @@ while (true) { | `type` | Σημασία | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Αυξητικό τμήμα κειμένου της απάντησης του βοηθού. Το `content` είναι το νέο περιεχόμενο· για συμβατότητα με v1, το ίδιο συμβάν περιλαμβάνει επίσης το `delta_answer` (ίσο με `content`) και το `id`. | +| `text_delta` | Αυξητικό τμήμα κειμένου της απάντησης του βοηθού. Το `content` είναι το νέο περιεχόμενο· για συμβατότητα με v1, το ίδιο συμβάν φέρει επίσης `delta_answer` (ίσο με `content`) και `id`. | | `thinking` | Η διαδικασία σκέψης του μοντέλου (εμφανίζεται μόνο όταν το επιλεγμένο μοντέλο εκθέτει reasoning). | -| `tool_use` | Το μοντέλο αποφασίζει να καλέσει ένα εργαλείο· το συμβάν περιλαμβάνει `tool_id`, `tool_name`, `input`. | -| `tool_result` | Το αποτέλεσμα εκτέλεσης του εργαλείου, αντιστοιχίζεται με το προηγούμενο `tool_use` μέσω του `tool_id`, και το `is_error` υποδεικνύει εάν απέτυχε. | -| `card` | Δομημένη κάρτα που παράγεται από το εργαλείο (όπως εικόνες, προεπισκοπήσεις συνδέσμων), κατάλληλη για άμεση απόδοση. | -| `citation` | URL πηγής που χρησιμοποιείται για τη συμπλήρωση παραπομπών για το αντίστοιχο τμήμα κειμένου. | -| `ask_user_question` | Εκδίδεται όταν το μοντέλο χρειάζεται ο χρήστης να συμπληρώσει πληροφορίες· η συνομιλία εισέρχεται στην κατάσταση `awaiting_user_input`, δείτε παρακάτω [Επαναφορά συνομιλίας σε παύση](#恢复暂停的对话). | -| `artifact` | Ανεξάρτητο παραγόμενο αποτέλεσμα του μοντέλου (όπως μπλοκ κώδικα, έγγραφα), το οποίο μπορεί να αποθηκευτεί ή να ληφθεί. | -| `system_message` | Μήνυμα συστήματος (όχι περιεχόμενο χρήστη ή βοηθού), χρησιμοποιείται μόνο για ειδοποιήσεις UI. | -| `compact` | Συμβάν όπου το εσωτερικό πλαίσιο έχει συμπιεστεί, χωρίς να απαιτείται ειδικός χειρισμός. | -| `error` | Παρουσιάστηκε σφάλμα σε αυτόν τον γύρο· το `message` περιγράφει το περιεχόμενο του σφάλματος. | -| `done` | Η ροϊκή απόκριση ολοκληρώνεται, περιλαμβάνοντας `usage` (με `prompt_tokens` / `completion_tokens` / `total_tokens`) και `terminal_reason`. | - -Για πελάτες που ενδιαφέρονται μόνο για την τελική απάντηση, η συνένωση των `content` όλων των `text_delta` είναι ισοδύναμη με το `answer` στη λειτουργία `application/json`. +| `tool_use` | Το μοντέλο αποφασίζει να καλέσει ένα εργαλείο, και το συμβάν φέρει `tool_id`, `tool_name`, `input`. | +| `tool_result` | Αποτέλεσμα εκτέλεσης εργαλείου, αντιστοιχίζεται με το προηγούμενο `tool_use` μέσω `tool_id`, ενώ το `is_error` υποδεικνύει αν απέτυχε. | +| `card` | Δομημένη κάρτα που παράγεται από εργαλείο (όπως εικόνα, προεπισκόπηση συνδέσμου), κατάλληλη για άμεση απόδοση. | +| `citation` | URL πηγής που χρησιμοποιείται για τη συμπλήρωση παραπομπής του αντίστοιχου τμήματος κειμένου. | +| `ask_user_question` | Εκδίδεται όταν το μοντέλο χρειάζεται ο χρήστης να συμπληρώσει πληροφορίες· η συνομιλία εισέρχεται στην κατάσταση `awaiting_user_input`, δείτε παρακάτω [Συνέχιση συνομιλίας σε παύση](#συνέχιση-συνομιλίας-σε-παύση). | +| `artifact` | Ανεξάρτητο παραγόμενο προϊόν του μοντέλου (όπως μπλοκ κώδικα, έγγραφο), το οποίο μπορεί να αποθηκευτεί ή να ληφθεί. | +| `system_message` | Πληροφορία συστήματος (όχι περιεχόμενο χρήστη ή βοηθού), μόνο για ειδοποιήσεις UI. | +| `compact` | Συμβάν όπου το εσωτερικό πλαίσιο συμπιέστηκε, χωρίς να απαιτείται ειδικός χειρισμός. | +| `error` | Προέκυψε σφάλμα σε αυτόν τον γύρο, το `message` περιγράφει το περιεχόμενο του σφάλματος. | +| `done` | Η ροϊκή απόκριση ολοκληρώθηκε, φέρει `usage` (συμπεριλαμβανομένων `prompt_tokens` / `completion_tokens` / `total_tokens`) και `terminal_reason`. | + +Για πελάτες που ενδιαφέρονται μόνο για την τελική απάντηση, η συνένωση του `content` όλων των `text_delta` είναι ισοδύναμη με το `answer` στη λειτουργία `application/json`. ## Πολυτροπική είσοδος -Εάν η είσοδος χρήστη περιλαμβάνει εικόνες ή αρχεία, μεταδώστε `message` (πίνακα) αντί για `question`. Κάθε στοιχείο του πίνακα είναι ένα μπλοκ περιεχομένου: +Εάν η είσοδος του χρήστη περιλαμβάνει εικόνες ή αρχεία, μεταβιβάστε `message` (πίνακα) αντί για `question`. Κάθε στοιχείο του πίνακα είναι ένα μπλοκ περιεχομένου: ```json { @@ -272,26 +272,26 @@ while (true) { - `image_url` — Εικόνα, απαιτείται το `image_url.url`. - `file_url` — Αρχείο (PDF, CSV, TXT κ.λπ.), απαιτείται το `file_url.url`. -### Σχέση με το `references` της v1 +### Σχέση με το `references` του v1 -Για συμβατότητα με παλαιότερους πελάτες, η v2 εξακολουθεί να αναγνωρίζει το πεδίο `references: ["https://...", ...]`: -- Το επίθημα URL είναι `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, μετατρέπεται αυτόματα σε μπλοκ `image_url`· -- Άλλες επεκτάσεις μετατρέπονται σε μπλοκ `file_url`· -- Εάν παρέχεται ταυτόχρονα και `question`, τότε τοποθετείται μπροστά ως μπλοκ `text`. +Για συμβατότητα με παλαιούς πελάτες, το v2 εξακολουθεί να αναγνωρίζει το πεδίο `references: ["https://...", ...]`: +- Εάν το επίθημα URL είναι `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, μετατρέπεται αυτόματα σε μπλοκ `image_url`； +- Άλλες επεκτάσεις μετατρέπονται σε μπλοκ `file_url`； +- Εάν παρέχεται ταυτόχρονα και `question`, τότε τοποθετείται μπροστά ως μπλοκ `text`。 -Επομένως, αν θέλετε μόνο να μεταβείτε από το v1 χωρίς να αλλάξετε το σώμα του αιτήματος, αρκεί να αλλάξετε τη διαδρομή σε `/aichat2/conversations`, και η αρχική χρήση του `references` συνεχίζει να λειτουργεί κανονικά. +Επομένως, εάν θέλετε μόνο να μεταβείτε από το v1 χωρίς να αλλάξετε το σώμα του αιτήματος, αρκεί να αλλάξετε τη διαδρομή σε `/aichat2/conversations`，και η αρχική χρήση του `references` συνεχίζει να λειτουργεί κανονικά。 -Αν χρειάζεστε πιο λεπτομερή έλεγχο (για παράδειγμα να τοποθετήσετε πολλές εικόνες ανάμεσα σε κείμενο, ή αν η σειρά είναι σημαντική), χρησιμοποιήστε απευθείας τον πίνακα `message`. +Για πιο λεπτομερή έλεγχο (για παράδειγμα, για να τοποθετήσετε πολλές εικόνες ανάμεσα σε κείμενα ή όταν η σειρά είναι σημαντική), χρησιμοποιήστε απευθείας τον πίνακα `message`。 -## Κλήση εργαλείων και MCP +## Κλήσεις εργαλείων και MCP -Η βασική ενίσχυση του v2 είναι ότι το μοντέλο μπορεί να καλεί αυτόνομα εργαλεία για την ολοκλήρωση εργασιών πολλαπλών βημάτων, **αυτό είναι ενεργοποιημένο από προεπιλογή**, και δεν απαιτείται καμία πρόσθετη ρύθμιση από τον πελάτη στο αίτημα. Συνηθισμένα σενάρια: +Η βασική ενίσχυση του v2 είναι ότι το μοντέλο μπορεί να καλεί αυτόνομα εργαλεία για να ολοκληρώνει εργασίες πολλαπλών βημάτων，**αυτό είναι ενεργοποιημένο από προεπιλογή**，και δεν απαιτείται καμία επιπλέον διαμόρφωση από τον πελάτη στο αίτημα。Συνηθισμένα σενάρια： -- Ο χρήστης ρωτά «Βοήθησέ με να ψάξω τι νέες εκθέσεις υπάρχουν πρόσφατα στη Σαγκάη» → το μοντέλο καλεί το ενσωματωμένο web search → οργανώνει τα αποτελέσματα σε απάντηση. -- Ο χρήστης ρωτά «Διάβασε αυτό το PDF και μετά γράψε μια περίληψη» → το μοντέλο καλεί το file_read → γράφει περίληψη. -- Ο χρήστης έχει ήδη εξουσιοδοτήσει Google Drive / GitHub / Notion κ.λπ. στο [Connections](https://platform.acedata.cloud/connections) → το μοντέλο μπορεί να καλέσει τα αντίστοιχα εργαλεία MCP για ανάγνωση και εγγραφή των δεδομένων του. +- Ο χρήστης ρωτά «Βοήθησέ με να ψάξω ποιες νέες εκθέσεις υπάρχουν πρόσφατα στη Σαγκάη» → το μοντέλο καλεί το ενσωματωμένο web search → οργανώνει τα αποτελέσματα σε απάντηση。 +- Ο χρήστης ρωτά «Διάβασε αυτό το PDF και μετά γράψε μια περίληψη» → το μοντέλο καλεί file_read → γράφει περίληψη。 +- Ο χρήστης έχει ήδη εξουσιοδοτήσει Google Drive / GitHub / Notion κ.λπ. στο [Connections](https://platform.acedata.cloud/connections) → το μοντέλο μπορεί να καλεί τα αντίστοιχα εργαλεία MCP για ανάγνωση και εγγραφή των δεδομένων του。 -Στη ροή NDJSON / SSE, οι κλήσεις εργαλείων παρουσιάζονται μέσω δύο τύπων συμβάντων, `tool_use` και `tool_result`, για παράδειγμα: +Στη ροή NDJSON / SSE，οι κλήσεις εργαλείων παρουσιάζονται μέσω δύο τύπων συμβάντων，`tool_use` και `tool_result`，για παράδειγμα： ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,23 +301,23 @@ while (true) { ... ``` -Αν δεν θέλετε να εμφανίζετε τις λεπτομέρειες των κλήσεων εργαλείων στο frontend, αρκεί να αγνοήσετε τα συμβάντα `tool_use` / `tool_result` / `card` / `citation`, και η τελική έξοδος του μοντέλου συνεχίζει να ρέει μέσω `text_delta`. +Εάν δεν θέλετε να εμφανίζετε στο frontend τις λεπτομέρειες των κλήσεων εργαλείων，αρκεί να αγνοήσετε αυτούς τους τύπους συμβάντων：`tool_use` / `tool_result` / `card` / `citation`，και η τελική έξοδος του μοντέλου θα εξακολουθήσει να μεταδίδεται μέσω `text_delta`。 -Το `max_turns` μπορεί να περιορίσει πόσους γύρους μπορεί το μοντέλο να καλέσει μόνο του εργαλεία σε αυτό το αίτημα· το προεπιλεγμένο ανώτατο όριο καθορίζεται από την πλατφόρμα. Αν το ορίσετε χαμηλά (για παράδειγμα `max_turns: 1`), μπορείτε να επιβάλετε μία μόνο απάντηση και να μην επιτρέψετε καμία κλήση εργαλείου. +Το `max_turns` μπορεί να περιορίσει τον μέγιστο αριθμό γύρων στους οποίους το μοντέλο μπορεί να καλεί εργαλεία μόνο του σε αυτό το αίτημα，με εύρος 1–500 και προεπιλεγμένη τιμή 500 όταν παραλείπεται。Αν το ορίσετε μικρό（για παράδειγμα `max_turns: 1`），μπορείτε να επιβάλετε μία μόνο απάντηση，χωρίς να επιτρέπεται καμία κλήση εργαλείου。 -## Ασύγχρονη εκτέλεση και εξουσιοδότηση χωρίς επίβλεψη +## Ασύγχρονη εκτέλεση και μη επιτηρούμενη εξουσιοδότηση -Αν η κλήση σας προέρχεται από Webhook ειδοποιήσεων, CI/CD, σύστημα παρακολούθησης ή άλλες εργασίες παρασκηνίου, μπορείτε να ορίσετε `async: true` ώστε το API να επιστρέψει αμέσως ένα ID εργασίας και να συνεχίσει η εκτέλεση στο παρασκήνιο: +Εάν οι κλήσεις σας προέρχονται από Webhook ειδοποιήσεων、CI/CD、συστήματα παρακολούθησης ή άλλες εργασίες παρασκηνίου，μπορείτε να ορίσετε `async: true` ώστε η διεπαφή να επιστρέφει αμέσως το ID εργασίας και να συνεχίσει η εκτέλεση στο παρασκήνιο： ```json { "model": "gpt-5.5", "async": true, - "question": "Η υπηρεσία μου έστειλε ειδοποίηση συναγερμού, ειδοποίησε την ομάδα WeChat «AceDataCloud团队» με προσωπικό WeChat……" + "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" } ``` -Παράδειγμα επιστροφής: +Παράδειγμα επιστροφής： ```json { @@ -328,9 +328,9 @@ while (true) { } ``` -Στη συνέχεια μπορείτε να χρησιμοποιήσετε `action: retrieve` + `id` για να αναζητήσετε το αποτέλεσμα της συνομιλίας· μπορείτε επίσης να παρέχετε `callback_url`, και αφού ολοκληρωθεί η εργασία, η πλατφόρμα θα κάνει POST το `{ status, answer, usage, error }` στη διεύθυνση callback σας. Το `callback_url` πρέπει να χρησιμοποιεί `http` / `https`, και δεν μπορεί να συμπληρωθεί απευθείας με `localhost` ή ιδιωτική κυριολεκτική διεύθυνση IP. +Στη συνέχεια μπορείτε να χρησιμοποιήσετε `action: retrieve` + `id` για να αναζητήσετε το αποτέλεσμα της συνομιλίας；μπορείτε επίσης να παρέχετε `callback_url`，και όταν ολοκληρωθεί η εργασία η πλατφόρμα θα κάνει POST το `{ status, answer, usage, error }` στη διεύθυνση callback σας。Το `callback_url` πρέπει να χρησιμοποιεί `http` / `https`，και δεν μπορείτε να εισαγάγετε απευθείας `localhost` ή κυριολεκτική διεύθυνση ιδιωτικής IP。 -Συνήθως δεν υπάρχει κανείς για να κάνει κλικ στην επιβεβαίωση στις εργασίες παρασκηνίου. Αν θέλετε ορισμένα Skill ή MCP Server να εκτελούν ενέργειες όπως αποστολή, δημοσίευση ή εγγραφή σε λειτουργία χωρίς επίβλεψη, παραδώστε ρητά μια λίστα προεξουσιοδότησης στο σώμα του αιτήματος: +Συνήθως δεν υπάρχει κανείς για να κάνει κλικ στην επιβεβαίωση στις εργασίες παρασκηνίου。Εάν θέλετε ορισμένα Skill ή MCP Server να εκτελούν ενέργειες όπως αποστολή、δημοσίευση、εγγραφή κ.λπ. σε μη επιτηρούμενη λειτουργία，παρακαλούμε περάστε ρητά τη λίστα προεξουσιοδότησης στο σώμα του αιτήματος： ```json { @@ -338,13 +338,13 @@ while (true) { "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "Η υπηρεσία μου έστειλε ειδοποίηση συναγερμού, ειδοποίησε την ομάδα WeChat «AceDataCloud团队» με προσωπικό WeChat……" + "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" } ``` -Οι τιμές στο `allowed_skills` είναι τα slug των συνδεδεμένων Skill· οι τιμές στο `allowed_mcp_servers` είναι τα slug των συνδεδεμένων MCP Server. Τα Skill / MCP Server που δεν περιλαμβάνονται στην προεξουσιοδότηση, σε λειτουργία χωρίς επίβλεψη, μπορούν ακόμη μόνο να κάνουν προεπισκόπηση, dry-run ή να αρνηθούν την εκτέλεση ενεργειών εγγραφής. +Οι τιμές στο `allowed_skills` είναι τα slug των συνδεδεμένων Skill；οι τιμές στο `allowed_mcp_servers` είναι τα slug των συνδεδεμένων MCP Server。Τα Skill / MCP Server που δεν περιλαμβάνονται στην προεξουσιοδότηση μπορούν ακόμη μόνο να κάνουν προεπισκόπηση、dry-run ή να αρνηθούν την εκτέλεση ενεργειών εγγραφής σε μη επιτηρούμενη λειτουργία。 -Αν χρειάζεστε λεπτομερέστερο έλεγχο, μπορείτε επίσης να χρησιμοποιήσετε το ισοδύναμο αντικείμενο `unattended_policy`: +Εάν χρειάζεστε πιο λεπτομερή έλεγχο，μπορείτε επίσης να χρησιμοποιήσετε το ισοδύναμο αντικείμενο `unattended_policy`： ```json { @@ -356,26 +356,26 @@ while (true) { } ``` -Η προεξουσιοδότηση είναι αυτές οι δύο λίστες καθαυτές: κενές λίστες σημαίνουν ότι δεν εξουσιοδοτείται καμία δυνατότητα, χωρίς να απαιτείται πρόσθετο πεδίο διακόπτη. +Η προεξουσιοδότηση είναι τα ίδια αυτά τα δύο πεδία λιστών：μια κενή λίστα σημαίνει ότι δεν εξουσιοδοτείται καμία δυνατότητα，και δεν απαιτείται πρόσθετο πεδίο διακόπτη。 -Σημείωση: η προεξουσιοδότηση σημαίνει μόνο ότι «αυτό το αίτημα επιτρέπει σε αυτές τις δυνατότητες να παρακάμψουν την ανθρώπινη επιβεβαίωση σε λειτουργία χωρίς επίβλεψη». Το συγκεκριμένο Skill πρέπει ακόμη να υποστηρίζει `--unattended-confirm` ή τον αντίστοιχο μηχανισμό ασφαλείας· διαφορετικά, θα συνεχίσει το dry-run και δεν θα εκτελέσει απευθείας ενέργειες εγγραφής. +Σημείωση：η προεξουσιοδότηση σημαίνει μόνο ότι «αυτό το αίτημα επιτρέπει σε αυτές τις δυνατότητες να παραλείπουν την ανθρώπινη επιβεβαίωση σε μη επιτηρούμενη λειτουργία」。Το συγκεκριμένο Skill πρέπει ακόμη να υποστηρίζει `--unattended-confirm` ή τον αντίστοιχο μηχανισμό ασφαλείας；διαφορετικά，θα συνεχίσει σε dry-run και δεν θα εκτελέσει απευθείας ενέργειες εγγραφής。 -## Επανάληψη συνομιλιών σε παύση +## Συνέχιση συνομιλίας σε παύση -Ορισμένα εργαλεία κάνουν το μοντέλο να «ρωτά τον χρήστη», και το μοντέλο τότε εκπέμπει ένα συμβάν `ask_user_question`, ενώ η συνομιλία παγώνει στην κατάσταση `awaiting_user_input`: +Ορισμένα εργαλεία κάνουν το μοντέλο να «ρωτήσει τον χρήστη」，και τότε το μοντέλο θα εκδώσει ένα συμβάν `ask_user_question`，με τη συνομιλία να παγώνει στην κατάσταση `awaiting_user_input`： ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "Θέλετε η αναφορά που θα δημιουργηθεί να είναι στα κινέζικα ή στα αγγλικά;", - "options": ["Κινέζικα", "Αγγλικά"], + "question": "你希望生成的报告是中文还是英文？", + "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` -Αποδώστε αυτό το συμβάν ως κάρτα στο frontend ώστε ο χρήστης να επιλέξει απάντηση, και έπειτα ξεκινήστε το επόμενο αίτημα με το ίδιο `id`, συμπληρώνοντας ξανά την απάντηση μέσω `tool_results`: +Αποδώστε αυτό το συμβάν στο frontend ως κάρτα ώστε ο χρήστης να επιλέξει απάντηση，και στη συνέχεια ξεκινήστε το επόμενο αίτημα χρησιμοποιώντας το ίδιο `id`，συμπληρώνοντας την απάντηση μέσω `tool_results`： ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Το `tool_use_id` στο σώμα του αιτήματος **πρέπει** να είναι ακριβώς το ίδιο με το `tool_id` κατά την παύση· διαφορετικά θα επιστραφεί 400. Όταν στο αίτημα υπάρχει ταυτόχρονα `tool_results`, τα `question` / `message` / `references` αγνοούνται όλα. +Το `tool_use_id` στο σώμα του αιτήματος **πρέπει** να είναι ακριβώς ίδιο με το `tool_id` κατά την παύση；διαφορετικά θα επιστραφεί 400。Όταν στο αίτημα υπάρχει ταυτόχρονα `tool_results`，τα `question` / `message` / `references` θα αγνοηθούν όλα。 -Αν ο χρήστης αποφασίσει να εγκαταλείψει αυτή την ερώτηση, αρκεί να περάσει απευθείας ένα νέο `question` / `message`, και η πλατφόρμα θα επισημάνει αυτόματα την κλήση εργαλείου σε παύση ως «παραλείφθηκε από τον χρήστη». +Εάν ο χρήστης αποφασίσει να εγκαταλείψει αυτή την ερώτηση，αρκεί να περάσετε απευθείας ένα νέο `question` / `message`，και η πλατφόρμα θα επισημάνει αυτόματα την κλήση εργαλείου που βρίσκεται σε παύση ως «παραλείφθηκε από τον χρήστη」。 -## Διαχείριση συνομιλιών (CRUD) - -Το v2 παρέχει ελαφριά διαχείριση συνομιλιών στο ίδιο endpoint μέσω του πεδίου `action`, χωρίς να χρειάζεται να ανοίξετε επιπλέον API. +## Διαχείριση συνομιλιών（CRUD） +Το v2 παρέχει ελαφριά διαχείριση συνομιλιών μέσω του πεδίου `action` στο ίδιο endpoint，χωρίς να χρειάζεται ξεχωριστό API。 ### `action: retrieve` —— Ανάκτηση μιας συνομιλίας + ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Επιστρέφει το πλήρες έγγραφο συνομιλίας (συμπεριλαμβανομένου του ιστορικού `messages`, του `model`, του `title`, του `tools_used` κ.λπ.). +Επιστρέφει το πλήρες έγγραφο της συνομιλίας (συμπεριλαμβανομένων του ιστορικού `messages`, του `model`, του `title`, του `tools_used` κ.λπ.). -### `action: retrieve_batch` —— Παράθεση περιλήψεων συνομιλιών +### `action: retrieve_batch` —— Λίστα περιλήψεων συνομιλιών ```json { @@ -428,7 +428,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -Επιστρέφει `{ items: [...], total }`. **Οι περιλήψεις δεν περιλαμβάνουν `messages`**, επομένως είναι κατάλληλες για λίστες πλευρικής γραμμής· εάν ο χρήστης ανοίξει μια συνομιλία, χρησιμοποιήστε στη συνέχεια το `action: retrieve` για να ανακτήσετε ξεχωριστά τα πλήρη μηνύματά της. +Επιστρέφει `{ items: [...], total }`. **Οι περιλήψεις δεν περιλαμβάνουν `messages`**, και είναι κατάλληλες για λίστες πλευρικής γραμμής· αν ο χρήστης ανοίξει μια συνομιλία, χρησιμοποιήστε στη συνέχεια το `action: retrieve` για να ανακτήσετε ξεχωριστά τα πλήρη μηνύματά της. Προαιρετικές παράμετροι φιλτραρίσματος: `user_id`, `application_id`, `model_group`, `model`. @@ -438,11 +438,11 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "title": "Σχέδιο ταξιδιού στη Χανγκζού" + "title": "Ταξιδιωτικό πλάνο για το Χανγκζού" } ``` -Μπορεί επίσης να περάσει το `messages`, αλλά ο διακομιστής θα εκτελέσει αυστηρό έλεγχο schema (πρέπει να είναι στη συμπτυγμένη μορφή `ToolUseContent`) και θα επιστρέψει 400 εάν δεν συμμορφώνεται. Γενικά συνιστάται να χρησιμοποιείται μόνο για την αλλαγή του `title`. +Μπορεί επίσης να μεταβιβαστεί το `messages`, αλλά ο διακομιστής θα εκτελέσει αυστηρό έλεγχο schema (πρέπει να είναι η συμπτυγμένη μορφή `ToolUseContent`)· αν δεν συμμορφώνεται, θα επιστραφεί 400. Γενικά, συνιστάται να χρησιμοποιείται μόνο για την αλλαγή του `title`. ### `action: delete` —— Διαγραφή μιας συνομιλίας @@ -453,21 +453,21 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -Επιστρέφει `{ id, success: true }`. Μετά τη διαγραφή δεν είναι δυνατή η ανάκτηση, επομένως επιβεβαιώστε πριν καλέσετε. +Επιστρέφει `{ id, success: true }`. Μετά τη διαγραφή δεν είναι δυνατή η ανάκτηση, παρακαλούμε επιβεβαιώστε πριν την κλήση. ## Ομαλή μετεγκατάσταση από το v1 -Εάν χρησιμοποιείτε ήδη το [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), η μετεγκατάσταση στο v2 σχεδόν δεν απαιτεί αλλαγές στον κώδικα: +Αν χρησιμοποιείτε ήδη το [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), η μετεγκατάσταση στο v2 σχεδόν δεν απαιτεί αλλαγές στον κώδικα: 1. Αλλάξτε το URL από `https://api.acedata.cloud/aichat/conversations` σε `https://api.acedata.cloud/aichat2/conversations`. -2. Εάν προηγουμένως περνούσατε ονόματα μοντέλων v1 (όπως `gpt-3.5`, `gpt-4-browsing` κ.λπ.), συνιστάται κατά τη μετάβαση στο v2 να αναβαθμίσετε σε σύγχρονα μοντέλα (όπως `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` κ.λπ.). -3. Τα πεδία της ροής NDJSON παραμένουν συμβατά προς τα πίσω: κάθε συμβάν `text_delta` εξακολουθεί να περιέχει `delta_answer` και `id`, επομένως οι υπάρχοντες πελάτες που αναλύουν γραμμή προς γραμμή το `delta_answer` δεν χρειάζονται αλλαγές. +2. Αν προηγουμένως μεταβιβάζατε ονόματα μοντέλων v1 (όπως `gpt-3.5`, `gpt-4-browsing` κ.λπ.), κατά τη μετάβαση στο v2 συνιστάται να αναβαθμίσετε σε σύγχρονα μοντέλα (όπως `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` κ.λπ.). +3. Τα πεδία της ροής NDJSON παραμένουν συμβατά προς τα πίσω: κάθε συμβάν `text_delta` εξακολουθεί να περιέχει `delta_answer` και `id`, επομένως οι υπάρχοντες πελάτες που αναλύουν ανά γραμμή το `delta_answer` δεν χρειάζονται αλλαγές. -Μετά τη μετεγκατάσταση, μπορείτε να ενεργοποιήσετε κατά περίπτωση τις νέες δυνατότητες του v2 (πολυτροπικό `message`, SSE, κλήσεις εργαλείων, `action` CRUD), προχωρώντας με τον δικό σας ρυθμό. +Μετά τη μετεγκατάσταση, μπορείτε να ενεργοποιήσετε ανάλογα με τις ανάγκες τις νέες δυνατότητες του v2 (πολυτροπικό `message`, SSE, κλήση εργαλείων, `action` CRUD), και να προχωρήσετε με τον δικό σας ρυθμό. ## Χειρισμός σφαλμάτων -Οι αποκρίσεις σφαλμάτων έχουν ενιαία μορφή: +Οι αποκρίσεις σφάλματος έχουν ενιαία μορφή: ```json { @@ -481,14 +481,14 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ Συνηθισμένα σφάλματα: -- `400 bad_request`: Λείπουν υποχρεωτικά πεδία, το `tool_use_id` δεν ταιριάζει, το schema του `messages` είναι μη έγκυρο κ.λπ. +- `400 bad_request`: Λείπουν υποχρεωτικά πεδία, το `tool_use_id` δεν ταιριάζει, το schema του `messages` δεν είναι έγκυρο κ.λπ. - `401 invalid_token`: Η κεφαλίδα `authorization` δεν είναι σωστή. - `404 not_found`: Κατά το `action: retrieve / update / delete`, η συνομιλία που αντιστοιχεί στο `id` δεν υπάρχει. - `429 too_many_requests`: Ενεργοποιήθηκε ο περιορισμός ρυθμού. -- `500 chat_error`: Σφάλμα από το ανάντη LLM ή `completion_tokens=0` σε αυτόν τον γύρο (θεωρείται ότι δεν καταναλώθηκε και δεν θα υπάρξει χρέωση). +- `500 chat_error`: Σφάλμα από το ανάντη LLM ή `completion_tokens=0` σε αυτόν τον γύρο (αντιμετωπίζεται ως μη καταναλωμένο και δεν θα υπάρξει χρέωση). -Στη ροϊκή απόκριση, τα σφάλματα εκπέμπονται ως συμβάντα `{"type":"error","message":"..."}` και αμέσως μετά η ροή τερματίζεται. +Στη ροϊκή απόκριση, τα σφάλματα αποστέλλονται ως συμβάντα `{"type":"error","message":"..."}`, και η ροή θα τερματιστεί αμέσως μετά. ## Συμπέρασμα -Το AI Chat v2 API, διατηρώντας τη συμβατότητα προς τα πίσω με το v1, αναβαθμίζει τις συνομιλίες από «ερωτήσεις και απαντήσεις μίας / πολλαπλών γύρων» σε «παρατηρήσιμες συνομιλίες με Agent»: πολυτροπική είσοδος, κλήσεις εργαλείων, δυνατότητα παύσης / συνέχισης, ροϊκά δομημένα συμβάντα, ενσωματωμένο CRUD. Συνιστάται οι νέες ενσωματώσεις να χρησιμοποιούν απευθείας το v2· οι υπάρχουσες ενσωματώσεις v1 μπορούν να μετεγκατασταθούν ομαλά σταδιακά. Εάν έχετε οποιεσδήποτε ερωτήσεις, επικοινωνήστε ανά πάσα στιγμή με την ομάδα τεχνικής υποστήριξής μας. +Το AI Chat v2 API, διατηρώντας τη συμβατότητα προς τα πίσω με το v1, αναβαθμίζει τη συνομιλία από «ερωταπαντήσεις ενός γύρου / πολλών γύρων» σε «παρατηρήσιμες συνομιλίες με Agent»: πολυτροπική είσοδος, κλήση εργαλείων, δυνατότητα παύσης / συνέχισης, ροϊκά δομημένα συμβάντα, ενσωματωμένο CRUD. Συνιστάται οι νέες ενσωματώσεις να χρησιμοποιούν απευθείας το v2· οι υπάρχουσες ενσωματώσεις v1 μπορούν να μετεγκατασταθούν ομαλά σταδιακά. Αν έχετε οποιεσδήποτε ερωτήσεις, παρακαλούμε επικοινωνήστε με την ομάδα τεχνικής υποστήριξής μας ανά πάσα στιγμή. diff --git a/el/guides/platform/hermes_managed.mdx b/el/guides/platform/hermes_managed.mdx index b0328ac49..90be6b565 100644 --- a/el/guides/platform/hermes_managed.mdx +++ b/el/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Ιδιωτική Ανάπτυξη" +title: "Ανάπτυξη Hermes" description: "Platform API guide - Ace Data Cloud" --- -Η Ace Data Cloud παρέχει είσοδο για την ιδιωτική ανάπτυξη του Hermes Agent. Αυτή η είσοδος είναι μια ελεγχόμενη υπηρεσία, η διαθεσιμότητα και οι διαθέσιμοι πόροι ισχύουν σύμφωνα με την τρέχουσα εμφάνιση της κονσόλας. +Δημιουργήστε ανεξάρτητη παρουσία container Hermes για κάθε Application. Από προεπιλογή χρησιμοποιείται μια βασική εικόνα σταθερρής έκδοσης, διατηρώντας τις εγγενείς λειτουργίες· η πλατφόρμα παρέχει αγορά, ανανέωση, μόνιμη αποθήκευση και διαχείριση ανάπτυξης. -## Βήματα Χρήσης +## Δημιουργία και αγορά -1. Βρείτε την **Ιδιωτική Ανάπτυξη Hermes Agent** στην πλατφόρμα. -2. Επιλέξτε τις διαθέσιμες ρυθμίσεις σύμφωνα με τις οδηγίες της σελίδας και δημιουργήστε την υπηρεσία. -3. Περιμένετε να εμφανιστεί η κατάσταση ετοιμότητας στην πλατφόρμα. -4. Χρησιμοποιήστε την είσοδο και τα διαπιστευτήρια που παρέχονται από τη σελίδα για να αποκτήσετε πρόσβαση στην περίπτωση. -5. Στείλτε πρώτα `Reply only OK`, και μετά ξεκινήστε την πραγματική εργασία. +1. Ανοίξτε το [Hermes 部署](https://platform.acedata.cloud/services/hermes) και δημιουργήστε ένα Application. +2. Επιλέξτε ένα πακέτο διάρκειας στη σελίδα αγοράς και ολοκληρώστε την πληρωμή. +3. Επιστρέψτε στη σελίδα διαμόρφωσης, όπου μπορείτε να επιλέξετε ένα μοντέλο συνομιλίας της πλατφόρμας από την αναπτυσσόμενη λίστα και να δείτε την τρέχουσα τιμή του μοντέλου. Η πλατφόρμα θα δημιουργήσει ανεξάρτητα διαπιστευτήρια API για αυτή την παρουσία· μπορείτε επίσης να απενεργοποιήσετε την πρόσβαση πλατφόρμας και να διαμορφώσετε μόνοι σας στο εγγενές κονσόλα. +4. Επιλέξτε αυτόματη δημιουργία διαπιστευτηρίων πρόσβασης ή ορίστε δικό σας ισχυρό κωδικό πρόσβασης/Token και, μετά την επιβεβαίωση, ξεκινήστε την ανάπτυξη. Τα διαπιστευτήρια πρόσβασης και τα διαπιστευτήρια API του μοντέλου είναι ανεξάρτητα μεταξύ τους. +5. Αφού η παρουσία είναι έτοιμη, λάβετε τη διεύθυνση πρόσβασης και τα διαπιστευτήρια σύνδεσης από τη σελίδα διαχείρισης. +6. Συνδεθείτε στην εγγενή κονσόλα και διαμορφώστε τους δικούς σας παρόχους μοντέλων, κλειδιά και κανάλια. -Το μοντέλο, τα διαπιστευτήρια, η αποθήκευση και οι ενέργειες διαγραφής ισχύουν σύμφωνα με τη σελίδα δημιουργίας και το παράθυρο επιβεβαίωσης; μην χρησιμοποιείτε το YAML από το τοπικό εγχειρίδιο Hermes απευθείας ως σύμβαση ανάπτυξης της πλατφόρμας. Εξάγετε πρώτα τα δεδομένα που χρειάζεται να διατηρηθούν πριν τη διαγραφή. +Το κόστος ανάπτυξης χρεώνεται σύμφωνα με τη διάρκεια του πακέτου· οι συγκεκριμένες τιμές σε δολάρια ΗΠΑ και η διάρκεια υπόκεινται στη σελίδα αγοράς. Τα έξοδα κλήσεων μοντέλου χρεώνονται ξεχωριστά· η αγορά χρόνου ανάπτυξης δεν παρέχει δωρεάν μονάδες μοντέλου. Όταν είναι ενεργοποιημένη η πρόσβαση πλατφόρμας, τα αποκλειστικά διαπιστευτήρια API ανοίγουν μόνο τη διεπαφή συνομιλίας που αντιστοιχεί στο επιλεγμένο μοντέλο και οι κλήσεις χρεώνονται επιπλέον από το υπόλοιπο της πλατφόρμας σας. Κάθε Application αγοράζεται, ανανεώνεται και διαχειρίζεται ξεχωριστά. -Εάν η κονσόλα δεν εμφανίζει την είσοδο δημιουργίας, αυτό σημαίνει ότι ο τρέχων λογαριασμός δεν έχει ακόμη ενεργοποιήσει αυτή την υπηρεσία, μπορείτε να χρησιμοποιήσετε τον [Οδηγό Αλληλεπίδρασης Hermes](https://platform.acedata.cloud/documents/hermes-wizard-integration) ή [Χειροκίνητη Ρύθμιση](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Κωδικοί πρόσβασης, διαπιστευτήρια και επακόλουθη διαμόρφωση + +Τα διαπιστευτήρια πρόσβασης ορίζονται πριν από την πρώτη εκκίνηση. Η αυτόματη δημιουργία χρησιμοποιεί τυχαία διαπιστευτήρια, ο προσαρμοσμένος κωδικός πρόσβασης πρέπει να έχει τουλάχιστον 16 χαρακτήρες και το OpenClaw Token τουλάχιστον 32 χαρακτήρες. Τα πρόχειρα δεν αποθηκεύουν κωδικούς πρόσβασης· μετά την αλλαγή σελίδας μπορεί να χρειαστεί να τους εισαγάγετε ξανά. Μετά την ανάπτυξη, μόνο ο ιδιοκτήτης και οι διαχειριστές του Application μπορούν να δουν τα διαπιστευτήρια πρόσβασης. + +Τα διαπιστευτήρια API μοντέλου κάθε παρουσίας δεν επαναχρησιμοποιούνται μεταξύ τους, η ισχύς τους παρατείνεται με την ανανέωση της ανάπτυξης και ανακαλούνται όταν διαγράφεται η παρουσία. Μετά την αρχικοποίηση της ανάπτυξης, τροποποιήστε τα μοντέλα και τα κανάλια στην εγγενή κονσόλα· εάν επιλέξετε μοντέλο άλλης υπηρεσίας, προσαρμόστε πρώτα την εξουσιοδότηση της αντίστοιχης διεπαφής στη διαχείριση διαπιστευτηρίων της πλατφόρμας ή χρησιμοποιήστε τα αντίστοιχα διαπιστευτήρια. Η συνήθης επαναφορά ανάπτυξης δεν θα αντικαταστήσει τις εγγενείς ρυθμίσεις. Περιβάλλοντα ανάπτυξης που δεν έχουν επαληθευτεί για δημοσίευση θα απορρίπτουν προσωρινά νέες αναπτύξεις· επικοινωνήστε με την υποστήριξη. + +## Εκδόσεις και δεδομένα + +Η σελίδα διαμόρφωσης εμφανίζει την τρέχουσα δημοσιευμένη έκδοση εικόνας. Οι νέες παρουσίες χρησιμοποιούν την τρέχουσα δημοσιευμένη έκδοση της υπηρεσίας· οι υπάρχουσες παρουσίες δεν αντικαθίστανται αυτόματα με ενημερώσεις του καταλόγου. Η επαναφορά ανάπτυξης θα εφαρμόσει την τρέχουσα έκδοση της υπηρεσίας· δημιουργήστε πρώτα αντίγραφο ασφαλείας και επιβεβαιώστε τις απαιτήσεις αναβάθμισης της έκδοσης που χρησιμοποιείτε. + +Κάθε παρουσία παρέχει από προεπιλογή 1 CPU, όριο μνήμης 2 GiB και 10 GiB μόνιμης αποθήκευσης. Η επανεκκίνηση διατηρεί τα δεδομένα της παρουσίας. Η ενεργή διαγραφή της ανάπτυξης ή η ανάκτηση μετά τη λήξη θα διαγράψει την αποθήκευση· εξαγάγετε εκ των προτέρων τα δεδομένα που χρειάζεται να διατηρήσετε. + +## Ανανέωση και λήξη + +Ανανεώστε στη σελίδα αγοράς του τρέχοντος Application και η περίοδος ισχύος θα παραταθεί σύμφωνα με τους υφιστάμενους κανόνες διάρκειας της πλατφόρμας. Μετά τη λήξη, η είσοδος πρόσβασης αναστέλλεται· η ανανέωση εντός της περιόδου χάριτος αποκαθιστά την πρόσβαση. Μετά την περίοδο χάριτος, η παρουσία και τα δεδομένα θα ανακτηθούν. Υπερισχύουν η ώρα λήξης, η κατάσταση χρέωσης και οι ειδοποιήσεις διαγραφής στη σελίδα διαχείρισης. + +## Σύνδεση στη διεπαφή διαχείρισης + +Στη σελίδα διαχείρισης ανάπτυξης, αντιγράψτε τη διεύθυνση Dashboard, το όνομα χρήστη `admin` και τον κωδικό πρόσβασης, ανοίξτε τη διεύθυνση και συνδεθείτε. Οι πληροφορίες σύνδεσης παρέχονται μόνο στον ιδιοκτήτη αυτού του Application και στους διαχειριστές της πλατφόρμας. Τα μοντέλα, οι δεξιότητες και τα κανάλια διαμορφώνονται στην εγγενή διεπαφή Hermes. + +## Συχνές ερωτήσεις + +- **Γιατί η νέα παρουσία δεν μπορεί ακόμη να απαντήσει;** Η ολοκλήρωση της ανάπτυξης σημαίνει ότι το container είναι έτοιμο· πρέπει να διαμορφώσετε το μοντέλο και τα διαπιστευτήρια στην εγγενή διεπαφή πριν αρχίσετε να τη χρησιμοποιείτε. +- **Προεγκαθίστανται πρόσθετα plugins ή model fallback;** Δεν προστίθενται από προεπιλογή· διαμορφώστε τα στην εγγενή διεπαφή ανάλογα με τις ανάγκες. +- **Πώς ενημερώνεται μια υπάρχουσα παρουσία;** Το αρχικό Application και η παραγγελία διατηρούνται και χρησιμοποιείται η τρέχουσα έκδοση της υπηρεσίας κατά την επαναφορά ανάπτυξης· πριν από την αναβάθμιση, δημιουργήστε αντίγραφο ασφαλείας των δεδομένων και ελέγξτε τη συμβατότητα της έκδοσης. +- **Τι να κάνω αν αποτύχει η εκκίνηση;** Ελέγξτε πρώτα τα αρχεία καταγραφής και τα συμβάντα ανάπτυξης και διαμορφώστε το μοντέλο αφού επιβεβαιώσετε ότι η παρουσία είναι έτοιμη. Μην εκθέτετε τον κωδικό πρόσβασης και τα κλειδιά της παρουσίας σε δημόσια σχόλια ή στιγμιότυπα οθόνης. diff --git a/el/guides/platform/wework_bot.mdx b/el/guides/platform/wework_bot.mdx deleted file mode 100644 index 95d61407f..000000000 --- a/el/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/en/guides/aichat/aichat2_conversations.mdx index 89e6ddf6d..110c41952 100644 --- a/en/guides/aichat/aichat2_conversations.mdx +++ b/en/guides/aichat/aichat2_conversations.mdx @@ -3,34 +3,34 @@ title: "AI Chat v2 API Integration Guide" description: "AI Dialogue integration guide - Ace Data Cloud" --- -The AI Chat v2 API (`/aichat2/conversations`) is a new-generation conversation interface and a comprehensive upgraded version of the [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Building on v1's simplicity and hosted multi-turn conversations, it expands with: +The AI Chat v2 API (`/aichat2/conversations`) is a next-generation conversation interface and a comprehensive upgrade of the [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Building on v1's simplicity and managed multi-turn conversations, it expands with: -- **Multimodal user input**: Directly send text + image + file blocks through the structured `message` field, without needing to attach them indirectly through `references` first. -- **Agent-based tool calling**: Includes a built-in set of tools such as web search, webpage fetching, and file reading, and can mount user-authorized MCP servers (Google Drive, Notion, Slack, GitHub, etc.). The model can autonomously call tools across multiple rounds within a single request to complete complex tasks. -- **Structured streaming events**: Through `accept: text/event-stream` or `application/x-ndjson`, you can receive token-by-token events such as `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, and `artifact`, making it convenient to render them separately by type on the frontend. -- **Interruptible / resumable**: When the model needs the user to provide additional information, it emits an `ask_user_question` event and pauses. In the next call, you can fill in the answer through `tool_results` to continue. -- **New CRUD actions**: Complete `retrieve` / `retrieve_batch` / `update` / `delete` through the `action` field on the same endpoint, without requiring an additional conversation management API. -- **Continuously updated model list**: By default, it supports contemporary models such as GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, and Kimi K3. +- **Multimodal user input**: Directly send text + image + file blocks through the structured `message` field, without needing to attach them indirectly using `references` first. +- **Agent-based tool calling**: Includes a built-in set of tools such as web search, webpage fetching, file reading, and more. It can also mount user-authorized MCP servers (Google Drive, Notion, Slack, GitHub, etc.), allowing the model to autonomously call tools multiple times within a single request to complete complex tasks. +- **Structured streaming events**: By using `accept: text/event-stream` or `application/x-ndjson`, you can receive token-by-token events such as `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, and `artifact`, making it convenient to render them separately by corresponding type on the frontend. +- **Interruptible / resumable**: When the model needs the user to provide additional information, it emits an `ask_user_question` event and pauses. In the next call, you can continue by filling back the answer through `tool_results`. +- **New CRUD actions**: Complete `retrieve` / `retrieve_batch` / `update` / `delete` on the same endpoint through the `action` field, without needing additional conversation management APIs. +- **Continuously updated model list**: By default, it supports contemporary models such as GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3, and more. -At the request body level, it is **fully backward compatible with v1**: simply pass `model` + `question` (+ optional `stateful` / `id` / `references` / `preset`) to get a `{answer, id}` JSON response equivalent to v1. Therefore, when migrating from `/aichat/conversations`, there is no need to rewrite the client; simply change the path to `/aichat2/conversations`. +At the request body level, it is also **fully backward compatible with v1**: simply pass `model` + `question` (+ optional `stateful` / `id` / `references` / `preset`) to receive a `{answer, id}` JSON response equivalent to v1. Therefore, migrating from `/aichat/conversations` does not require rewriting the client; you only need to change the path to `/aichat2/conversations`. > If you are currently using `/aichat/conversations`, the old interface will remain available, and you can migrate at your own pace. ## Application Process -To use the AI Chat v2 API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token and keep it for later use. +To use the AI Chat v2 API, first go to the [Ace Data Cloud console](https://platform.acedata.cloud/console/applications) to obtain your API Token and keep it for later use. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -If you are 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 and 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; there is no need to apply separately for each service.** Your first application comes with free credits for a free trial; when credits are insufficient, you can top up 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 top up your general balance in the [console](https://platform.acedata.cloud/console/coin). -> 📘 Complete documentation: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) +> 📘 Full documentation: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Basic Usage -The simplest usage is exactly the same as v1: pass `model` + `question`, and receive `{answer, id}`. +The simplest usage is exactly the same as v1: pass `model` + `question` and receive `{answer, id}`. CURL example: @@ -45,7 +45,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Return result: +Response: ```json { @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Available values for `model` can be viewed directly in the dropdown of the Try panel on the right. Common categories include: +Available `model` values can be viewed directly in the dropdown list of the Try panel on the right. Common categories include: - OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini`, etc. - Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`, etc. @@ -90,7 +90,7 @@ For specific billing rules, refer to the Pricing card on the service page. ## Multi-turn Conversations -As with v1, pass `stateful: true` to enable conversation storage. The API will return an `id`; simply include the `id` in subsequent requests to continue the conversation, without needing to maintain the messages history yourself. +Just like v1, pass `stateful: true` to enable conversation storage, and the API will return an `id`; in subsequent requests, simply include the `id` to continue the conversation, without needing to maintain the messages history yourself. First request: @@ -106,7 +106,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Return: +Response: ```json { @@ -125,28 +125,28 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ "model": "gpt-5.4", "stateful": true, "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "question": "What number did I just ask you to remember?" + "question": "我刚才让你记住的数字是多少？" }' ``` ```json { - "answer": "The number you asked me to remember is 42.", + "answer": "你让我记住的数字是 42。", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` -> `stateful` defaults to `true`; omitting it is equivalent to explicitly passing `true`. If you do not want the server to save this conversation turn, you can explicitly set `stateful: false`. +> `stateful` defaults to `true`; omitting it is equivalent to explicitly passing `true`. If you do not want the server to save this round of conversation, you can explicitly set `stateful: false`. ## Streaming Responses v2 supports two streaming formats, selected according to the `accept` header: -| Scenario | `accept` | Data Format | +| Scenario | `accept` | Data format | | --------------------- | ---------------------- | ------------------------------------------ | | Web frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, with the final line `data: [DONE]\n\n` | -| Server / CLI / Node streaming parsing | `application/x-ndjson` | One JSON object per line | -| Streaming not required | `application/json` (default) | Returns `{answer, id}` in a single response | +| Server-side / CLI / Node streaming parsing | `application/x-ndjson` | One JSON object per line | +| Streaming not needed | `application/json` (default) | Returns `{answer, id}` in one response | ### NDJSON Example @@ -165,7 +165,7 @@ headers = { payload = { "model": "gpt-5.4", "stateful": True, - "question": "Introduce Hangzhou in three sentences.", + "question": "用三句话介绍杭州。", } with requests.post(url, json=payload, headers=headers, stream=True) as resp: @@ -175,7 +175,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: continue event = json.loads(line) if event.get("type") == "text_delta": - # Compatible with v1: incremental fragments are also provided through the delta_answer field + # 与 v1 兼容：增量片段同时通过 delta_answer 字段提供 answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": @@ -183,19 +183,19 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -Each line of NDJSON is a structured event; the most common one is `text_delta`: +Each line of NDJSON is a structured event, with the most common being `text_delta`: ```json -{"type":"text_delta","content":"Hang","delta_answer":"Hang","id":"f2f4b3e8-..."} -{"type":"text_delta","content":"zhou","delta_answer":"zhou","id":"f2f4b3e8-..."} -{"type":"text_delta","content":" is","delta_answer":" is","id":"f2f4b3e8-..."} +{"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} +{"type":"text_delta","content":"州","delta_answer":"州","id":"f2f4b3e8-..."} +{"type":"text_delta","content":"是","delta_answer":"是","id":"f2f4b3e8-..."} ... {"type":"done","conversation_id":"f2f4b3e8-...","usage":{"prompt_tokens":21,"completion_tokens":58,"total_tokens":79},"terminal_reason":"natural_stop"} ``` ### SSE Example -Using `EventSource` in the browser does not support custom request bodies. It is recommended to use `fetch` + manually parse by splitting on `\n\n`: +Using `EventSource` in the browser does not support custom request bodies; it is recommended to use `fetch` + manually parse by splitting on `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -208,7 +208,7 @@ const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { body: JSON.stringify({ model: "gpt-5.4", stateful: true, - question: "Introduce Hangzhou in three sentences.", + question: "用三句话介绍杭州。", }), }); @@ -236,31 +236,31 @@ while (true) { | `type` | Meaning | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | An incremental text fragment of the assistant's answer. `content` is the newly added content; for v1 compatibility, the same event also carries `delta_answer` (equal to `content`) and `id`. | -| `thinking` | The model's reasoning process (appears only when the selected model exposes reasoning). | -| `tool_use` | The model decides to call a tool; the event carries `tool_id`, `tool_name`, and `input`. | +| `text_delta` | An incremental text fragment of the assistant's response. `content` contains the newly added content; for v1 compatibility, the same event also includes `delta_answer` (equal to `content`) and `id`. | +| `thinking` | The model's reasoning process (only appears when the selected model exposes reasoning). | +| `tool_use` | The model decides to call a tool; the event includes `tool_id`, `tool_name`, and `input`. | | `tool_result` | The tool execution result, paired with the preceding `tool_use` through `tool_id`; `is_error` indicates whether it failed. | | `card` | A structured card produced by a tool (such as an image or link preview), suitable for direct rendering. | -| `citation` | The source URL used to supplement citations for the corresponding text fragment. | -| `ask_user_question` | Sent when the model needs the user to provide additional information; the conversation enters the `awaiting_user_input` state. See [Resuming Paused Conversations](#resuming-paused-conversations) below for details. | +| `citation` | The source URL used to supplement the citation for the corresponding text fragment. | +| `ask_user_question` | Emitted when the model needs the user to provide additional information; the conversation enters the `awaiting_user_input` state. See [Resume Paused Conversations](#恢复暂停的对话) below for details. | | `artifact` | An independent artifact generated by the model (such as a code block or document), which can be saved or downloaded. | -| `system_message` | System prompt information (not user or assistant content), used only for UI notifications. | +| `system_message` | A system prompt message (not user or assistant content), used only for UI notifications. | | `compact` | An event indicating that the internal context has been compressed; no special handling is required. | -| `error` | An error occurred during this turn; `message` describes the error content. | -| `done` | The streaming response has ended, carrying `usage` (including `prompt_tokens` / `completion_tokens` / `total_tokens`) and `terminal_reason`. | +| `error` | An error occurred during this round; `message` describes the error. | +| `done` | The streaming response has ended; includes `usage` (containing `prompt_tokens` / `completion_tokens` / `total_tokens`) and `terminal_reason`. | -For clients that only care about the final answer, concatenating the `content` of all `text_delta` events is equivalent to the `answer` in `application/json` mode. +For clients concerned only with the final answer, concatenating the `content` of all `text_delta` events is equivalent to the `answer` in `application/json` mode. ## Multimodal Input -If user input contains images or files, pass `message` (an array) instead of `question`. Each array element is a content block: +If the user input contains images or files, pass `message` (an array) instead of `question`. Each array element is a content block: ```json { "model": "gpt-5.4", "stateful": true, "message": [ - { "type": "text", "text": "How many cats are in this image?" }, + { "type": "text", "text": "这张图片里有几只猫？" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } } ] } @@ -269,29 +269,29 @@ If user input contains images or files, pass `message` (an array) instead of `qu Supported block types: - `text` — Plain text; the `text` field is required. -- `image_url` — Image; `image_url.url` is required. -- `file_url` — File (PDF, CSV, TXT, etc.); `file_url.url` is required. +- `image_url` — An image; `image_url.url` is required. +- `file_url` — A file (PDF, CSV, TXT, etc.); `file_url.url` is required. ### Relationship with v1 `references` -For compatibility with older clients, v2 still recognizes the `references: ["https://...", ...]` field: -- If the URL suffix is `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatically convert it into an `image_url` block; -- Convert other extensions into a `file_url` block; -- If `question` is also provided at the same time, then prepend it as a `text` block. +For compatibility with legacy clients, v2 still recognizes the `references: ["https://...", ...]` field: +- If the URL suffix is `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, it is automatically converted into an `image_url` block; +- Other extensions are converted into a `file_url` block; +- If `question` is also provided, it is placed first as a `text` block. -Therefore, if you only want to migrate from v1 and do not want to modify the request body, just change the path to `/aichat2/conversations`; the original `references` usage will continue to work as usual. +Therefore, if you only want to migrate from v1 and do not want to modify the request body, simply change the path to `/aichat2/conversations`, and the original `references` usage will continue to work as usual. If more fine-grained control is needed (for example, placing multiple images between text, or when the order is important), directly use the `message` array. ## Tool Calls and MCP -The core enhancement of v2 is that the model can autonomously call tools to complete multi-step tasks. **This is enabled by default**, and the client does not need to make any additional configuration in the request. Common scenarios: +The core enhancement of v2 is that the model can independently call tools to complete multi-step tasks. **This is enabled by default**, and does not require the client to make any additional configuration in the request. Common scenarios: -- The user asks, “Help me search for what new exhibitions there are recently in Shanghai” → The model calls the built-in web search → Organizes the results into an answer. +- The user asks, “Help me search for recent new exhibitions in Shanghai” → The model calls built-in web search → Organizes the results into an answer. - The user asks, “Read this PDF and then write a summary” → The model calls file_read → Writes a summary. - The user has authorized Google Drive / GitHub / Notion, etc. in [Connections](https://platform.acedata.cloud/connections) → The model can call the corresponding MCP tools to read and write their data. -In the NDJSON / SSE stream, tool calls are presented through two types of events, `tool_use` and `tool_result`, for example: +In the NDJSON / SSE stream, tool calls are represented through two types of events: `tool_use` and `tool_result`, for example: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,13 +301,13 @@ In the NDJSON / SSE stream, tool calls are presented through two types of events ... ``` -If you do not want to display tool call details on the frontend, simply ignore event types such as `tool_use` / `tool_result` / `card` / `citation`; the model’s final output will still stream through `text_delta`. +If you do not want to display tool call details on the frontend, simply ignore event types such as `tool_use` / `tool_result` / `card` / `citation`; the model's final output will still stream through `text_delta`. -`max_turns` can limit the maximum number of rounds in which the model can call tools by itself in this request; the default upper limit is determined by the platform. Setting it low (for example, `max_turns: 1`) can force a single response and disallow any tool calls. +`max_turns` can limit the maximum number of rounds in which the model can call tools by itself within this request. The range is 1–500, and the default is 500 when omitted. Setting it low (for example, `max_turns: 1`) can force a single response and disallow any tool calls. ## Asynchronous Execution and Unattended Authorization -If your calls come from alert Webhooks, CI/CD, monitoring systems, or other background tasks, you can set `async: true` to make the API immediately return a task ID and continue execution in the background: +If your call comes from an alert Webhook, CI/CD, monitoring system, or another background task, you can set `async: true` to have the API immediately return a task ID while execution continues in the background: ```json { @@ -317,7 +317,7 @@ If your calls come from alert Webhooks, CI/CD, monitoring systems, or other back } ``` -Response example: +Example response: ```json { @@ -328,9 +328,9 @@ Response example: } ``` -Afterward, you can use `action: retrieve` + `id` to query the conversation result; you can also provide `callback_url`, and after the task is completed, the platform will POST `{ status, answer, usage, error }` to your callback address. `callback_url` must use `http` / `https` and cannot directly specify `localhost` or a private IP literal address. +Afterward, you can use `action: retrieve` + `id` to query the conversation result; you can also provide `callback_url`, and after the task is completed, the platform will POST `{ status, answer, usage, error }` to your callback address. `callback_url` must use `http` / `https`, and cannot directly specify `localhost` or a private IP literal address. -Usually, there is no one available to click confirmation for background tasks. If you want certain Skills or MCP Servers to perform actions such as sending, publishing, or writing in unattended mode, explicitly pass a pre-authorization list in the request body: +There is usually no one available to click confirmation for background tasks. If you want certain Skills or MCP Servers to perform actions such as sending, publishing, or writing in unattended mode, explicitly pass a preauthorization list in the request body: ```json { @@ -342,9 +342,9 @@ Usually, there is no one available to click confirmation for background tasks. I } ``` -The values in `allowed_skills` are the slugs of connected Skills; the values in `allowed_mcp_servers` are the slugs of connected MCP Servers. Skills / MCP Servers not included in the pre-authorization list can still only preview, dry-run, or refuse to perform write operations in unattended mode. +The values in `allowed_skills` are the slugs of connected Skills; the values in `allowed_mcp_servers` are the slugs of connected MCP Servers. Skills / MCP Servers not included in the preauthorization list can still only preview, dry-run, or refuse to perform write operations in unattended mode. -If more fine-grained control is needed, you can also use the equivalent `unattended_policy` object: +If more detailed control is needed, you can also use the equivalent `unattended_policy` object: ```json { @@ -356,13 +356,13 @@ If more fine-grained control is needed, you can also use the equivalent `unatten } ``` -Pre-authorization is these two lists themselves: an empty list means no capabilities are authorized, and no additional switch field is needed. +Preauthorization consists of these two lists themselves: an empty list means no capabilities are authorized, without requiring any additional switch field. -Note: Pre-authorization only means “this request allows these capabilities to skip manual confirmation in unattended mode.” The specific Skill must still support `--unattended-confirm` or the corresponding security mechanism; otherwise, it will continue to dry-run and will not directly perform write operations. +Note: Preauthorization only means that “these capabilities are allowed to skip manual confirmation in unattended mode for this request.” The specific Skill must still support `--unattended-confirm` or the corresponding security mechanism; otherwise, it will continue to dry-run and will not directly perform write operations. ## Resuming Paused Conversations -Some tools cause the model to “ask the user a follow-up question.” At this time, the model sends an `ask_user_question` event, and the conversation is frozen in the `awaiting_user_input` state: +Some tools cause the model to “ask the user a follow-up question.” At this point, the model emits an `ask_user_question` event, and the conversation is frozen in the `awaiting_user_input` state: ```json { @@ -375,7 +375,7 @@ Some tools cause the model to “ask the user a follow-up question.” At this t } ``` -Render this event as a card on the frontend for the user to select an answer, then initiate the next request using the same `id` and fill the answer back through `tool_results`: +Render this event as a card on the frontend for the user to select an answer, then initiate the next request using the same `id`, and fill the answer back through `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -The `tool_use_id` in the request body **must** be exactly the same as the `tool_id` when paused; otherwise, it will return 400. When `tool_results` exists in the request at the same time, `question` / `message` / `references` will all be ignored. +The `tool_use_id` in the request body **must** be exactly the same as the `tool_id` when paused; otherwise, 400 will be returned. When `tool_results` exists in the request, `question` / `message` / `references` will all be ignored. -If the user decides to abandon this question, simply pass a new `question` / `message`; the platform will automatically mark the paused tool call as “skipped by user.” +If the user decides to abandon this question, simply pass a new `question` / `message`, and the platform will automatically mark the paused tool call as “skipped by user.” ## Conversation Management (CRUD) -v2 provides lightweight conversation management through the `action` field on the same endpoint, without the need to open another API. +v2 provides lightweight conversation management on the same endpoint through the `action` field, without requiring a separate API. +### `action: retrieve` —— Retrieve a conversation -### `action: retrieve` —— Retrieve a Conversation ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -428,7 +428,7 @@ Returns the complete conversation document (including `messages` history, `model } ``` -Returns `{ items: [...], total }`. **Summaries do not include `messages`**, making them suitable for sidebar lists; if the user opens a conversation, then use `action: retrieve` to fetch its complete messages separately. +Returns `{ items: [...], total }`. **Summaries do not contain `messages`**, making them suitable for sidebar lists; if the user opens a conversation, then use `action: retrieve` to retrieve its complete messages separately. Optional filter parameters: `user_id`, `application_id`, `model_group`, `model`. @@ -442,7 +442,7 @@ Optional filter parameters: `user_id`, `application_id`, `model_group`, `model`. } ``` -`messages` can also be passed, but the server performs strict schema validation (it must be in the folded `ToolUseContent` form), and returns 400 if it does not comply. Generally, it is only recommended for changing the `title`. +`messages` can also be passed, but the server will perform strict schema validation (it must be in the folded `ToolUseContent` form), and a 400 will be returned if it does not comply. Generally, it is only recommended to use this to change the `title`. ### `action: delete` —— Delete a conversation @@ -453,21 +453,21 @@ Optional filter parameters: `user_id`, `application_id`, `model_group`, `model`. } ``` -Returns `{ id, success: true }`. Deleted conversations cannot be recovered, so please confirm before calling. +Returns `{ id, success: true }`. It cannot be recovered after deletion; please confirm before calling. ## Smooth migration from v1 -If you are already using [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), migrating to v2 requires almost no code changes: +If you are already using [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), almost no code changes are required to migrate to v2: 1. Change the URL from `https://api.acedata.cloud/aichat/conversations` to `https://api.acedata.cloud/aichat2/conversations`. -2. If you previously used v1 model names (such as `gpt-3.5`, `gpt-4-browsing`, etc.), it is recommended to upgrade to current models when switching to v2 (such as `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview`, etc.). -3. NDJSON stream fields remain backward compatible: each `text_delta` event still includes `delta_answer` and `id`, so clients that originally parse `delta_answer` line by line do not need to be changed. +2. If you previously passed v1 model names (such as `gpt-3.5`, `gpt-4-browsing`, etc.), it is recommended to upgrade to contemporary models when switching to v2 (such as `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview`, etc.). +3. The fields of the NDJSON stream remain backward compatible: each `text_delta` event still carries `delta_answer` and `id`, so clients that originally parse `delta_answer` line by line do not need to be changed. -After migration, you can enable the new v2 capabilities as needed (multimodal `message`, SSE, tool calling, `action` CRUD) and proceed at your own pace. +After migration, you can enable v2's new capabilities as needed (multimodal `message`, SSE, tool calling, `action` CRUD) and proceed at your own pace. ## Error handling -Error responses follow a unified format: +Error responses are standardized as: ```json { @@ -483,12 +483,12 @@ Common errors: - `400 bad_request`: Missing required fields, mismatched `tool_use_id`, invalid `messages` schema, etc. - `401 invalid_token`: The `authorization` header is incorrect. -- `404 not_found`: The conversation corresponding to the `id` does not exist when using `action: retrieve / update / delete`. +- `404 not_found`: The conversation corresponding to `id` does not exist when using `action: retrieve / update / delete`. - `429 too_many_requests`: The rate limit has been triggered. -- `500 chat_error`: An upstream LLM error occurred, or `completion_tokens=0` for this turn (treated as not consumed and will not be charged). +- `500 chat_error`: The upstream LLM reports an error or `completion_tokens=0` for the current turn (treated as unconsumed and will not be charged). -In streaming responses, errors are emitted as `{"type":"error","message":"..."}` events, followed immediately by the end of the stream. +In streaming responses, errors are emitted as `{"type":"error","message":"..."}` events, and the stream ends immediately afterward. ## Conclusion -While remaining backward compatible with v1, the AI Chat v2 API upgrades conversations from “single-turn / multi-turn Q&A” to “observable agent-based conversations”: multimodal input, tool calling, pausable / resumable interactions, structured streaming events, and built-in CRUD. New integrations are recommended to use v2 directly; existing v1 integrations can migrate smoothly in stages. If you have any questions, please feel free to contact our technical support team. +While remaining backward compatible with v1, the AI Chat v2 API upgrades conversations from “single-turn / multi-turn Q&A” to “agentic observable conversations”: multimodal input, tool calling, pausable / resumable operations, structured streaming events, and built-in CRUD. It is recommended that new integrations use v2 directly; existing v1 integrations can migrate smoothly in phases. If you have any questions, please feel free to contact our technical support team. diff --git a/en/guides/platform/hermes_managed.mdx b/en/guides/platform/hermes_managed.mdx index ee4415c4b..5432de65e 100644 --- a/en/guides/platform/hermes_managed.mdx +++ b/en/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Private Deployment" +title: "Hermes Deployment" description: "Platform integration guide - Ace Data Cloud" --- -Ace Data Cloud provides an entry for Hermes Agent private deployment. This entry is a controlled service, and its availability and selectable resources are subject to what is currently displayed on the console. +Create an independent Hermes container instance for each Application. By default, use a base image with a fixed release version and retain native features; the platform provides purchase, renewal, persistent storage, and deployment management. -## Steps to Use +## Creation and Purchase -1. Find **Hermes Agent Private Deployment** on the platform. -2. Follow the page prompts to select available configurations and create the service. -3. Wait for the platform to display the ready status. -4. Use the entry and credentials provided on the page to access the instance. -5. First send `Reply only OK`, then start the real task. +1. Open [Hermes Deployment](https://platform.acedata.cloud/services/hermes) and create an Application. +2. Select a duration plan on the purchase page and complete the payment. +3. Return to the configuration page, where you can select a platform chat model from the dropdown list and view the current model price. The platform will create independent API credentials for this instance; you can also disable platform access and configure it yourself in the native console. +4. Choose to automatically generate access credentials, or set your own strong password/Token, then confirm to begin deployment. Access credentials and model API credentials are independent of each other. +5. After the instance is ready, obtain the access address and login credentials from the management page. +6. Log in to the native console and configure your own model providers, keys, and channels. -The model, credentials, storage, and deletion behavior are subject to the creation page and confirmation pop-up; do not directly treat the YAML from the local Hermes tutorial as the platform deployment contract. Export any data that needs to be retained before deletion. +Deployment fees are charged according to the plan duration. The specific USD price and duration are subject to the purchase page. Model invocation fees are charged separately; purchasing deployment duration does not include model credits. When platform access is enabled, the dedicated API credentials only expose the chat interface corresponding to the selected model, and usage is charged separately from your platform balance. Each Application is purchased, renewed, and managed separately. -If the console does not display the creation entry, it indicates that the current account does not have this service enabled; you can alternatively use the [Hermes Interactive Wizard](https://platform.acedata.cloud/documents/hermes-wizard-integration) or [Manual Configuration](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Passwords, Credentials, and Subsequent Configuration + +Access credentials are set before the first startup. The automatic generation method uses random credentials, custom passwords must be at least 16 characters, and OpenClaw Tokens must be at least 32 characters. Drafts do not save passwords; you may need to re-enter them after switching pages. After deployment, only the Application owner and administrators can view the access credentials. + +The model API credentials for each instance are not reused, their validity is extended with deployment renewal, and they are revoked when the instance is deleted. After deployment initialization, please modify models and channels in the native console; if you switch to models from other services, first adjust the corresponding interface authorization in platform credential management, or use the corresponding credentials. Normal redeployment will not overwrite native settings. Deployment environments that have not passed release validation will temporarily reject new deployments; please contact support. + +## Versions and Data + +The configuration page displays the currently released image version. New instances use the service's currently released version; existing instances will not be automatically replaced when the catalog is updated. Redeployment will apply the current service version; please back up first and confirm the upgrade requirements of the version in use. + +Each instance provides 1 CPU, a 2 GiB memory limit, and 10 GiB of persistent storage by default. Instance data is retained after restarts. Actively deleting a deployment or expiration reclamation will delete storage; please export any data that needs to be retained in advance. + +## Renewal and Expiration + +Renew on the purchase page of the current Application, and the validity period will be extended according to the platform's existing duration rules. After expiration, the access entry is suspended, and renewing during the grace period restores access; after the grace period, the instance and data will be reclaimed. Refer to the expiration time, billing status, and deletion notices on the management page. + +## Logging In to the Management Interface + +Copy the Dashboard address, username `admin`, and password from the deployment management page, then open it and log in. Login information is provided only to the owner of that Application and platform administrators. Models, skills, and channels are configured in the Hermes native interface. + +## Frequently Asked Questions + +- **Why can the new instance not respond yet?** Deployment completion means the container is ready; you need to configure models and credentials in the native interface before you can start using it. +- **Are additional plugins or model fallbacks preinstalled?** They are not added by default; configure them in the native interface as needed. +- **How do existing instances get updated?** The original Application and order are retained, and the current service version is used during redeployment; back up data and check version compatibility before upgrading. +- **What should I do if startup fails?** First check deployment logs and events, and configure the model only after confirming that the instance is ready. Do not expose instance passwords and keys in public comments or screenshots. diff --git a/en/guides/platform/wework_bot.mdx b/en/guides/platform/wework_bot.mdx deleted file mode 100644 index a3ee7412f..000000000 --- a/en/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/es/guides/aichat/aichat2_conversations.mdx index 9cb889f1d..02ceac702 100644 --- a/es/guides/aichat/aichat2_conversations.mdx +++ b/es/guides/aichat/aichat2_conversations.mdx @@ -1,36 +1,36 @@ --- -title: "Instrucciones de integración de AI Chat v2 API" +title: "Guía de integración de AI Chat v2 API" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API (`/aichat2/conversations`) es la nueva generación de interfaz de conversación, y es una versión completamente mejorada de [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Sobre la base de la simplicidad y las conversaciones multivuelta alojadas de v1, amplía: +AI Chat v2 API (`/aichat2/conversations`) es la interfaz de conversación de nueva generación, y es una versión completamente mejorada de [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Sobre la base de la simplicidad y la gestión de conversaciones multivuelta de v1, amplía: -- **Entrada de usuario multimodal**: mediante el campo estructurado `message`, envía directamente bloques de texto + imágenes + archivos, sin necesidad de adjuntarlos indirectamente primero mediante `references`. -- **Llamada de herramientas con agentes**: integra un conjunto de herramientas como búsqueda en internet, extracción de páginas web, lectura de archivos, etc., y puede montar servidores MCP autorizados por el usuario (Google Drive, Notion, Slack, GitHub, etc.); el modelo puede llamar autónomamente a herramientas varias veces en una sola solicitud para completar tareas complejas. -- **Eventos de streaming estructurados**: mediante `accept: text/event-stream` o `application/x-ndjson`, se pueden obtener eventos como `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact`, etc., token por token, lo que facilita renderizarlos por separado en el frontend según el tipo correspondiente. -- **Interrumpible / reanudable**: cuando el modelo necesita que el usuario complemente información, emitirá un evento `ask_user_question` y se pausará; en la siguiente llamada, basta con rellenar la respuesta mediante `tool_results` para continuar. -- **Nuevas acciones CRUD**: en el mismo endpoint, completa `retrieve` / `retrieve_batch` / `update` / `delete` mediante el campo `action`, sin necesidad de una API adicional de gestión de conversaciones. -- **Lista de modelos en actualización continua**: por defecto integra modelos contemporáneos como GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3, etc. +- **Entradas de usuario multimodales**: a través del campo estructurado `message` se pueden enviar directamente bloques de texto + imágenes + archivos, sin necesidad de adjuntarlos indirectamente primero mediante `references`. +- **Llamadas a herramientas tipo Agent**: incorpora un conjunto de herramientas como búsqueda en internet, extracción de páginas web, lectura de archivos, etc., y permite montar servidores MCP autorizados por el usuario (Google Drive, Notion, Slack, GitHub, etc.); el modelo puede llamar autónomamente a herramientas múltiples veces en una sola solicitud para completar tareas complejas. +- **Eventos de streaming estructurados**: mediante `accept: text/event-stream` o `application/x-ndjson` se pueden obtener eventos como `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact`, etc., token por token, lo que facilita renderizarlos por separado según el tipo correspondiente en el frontend. +- **Interrumpible / reanudable**: cuando el modelo necesita que el usuario complemente información, emitirá un evento `ask_user_question` y se pausará; en la siguiente llamada, basta con completar la respuesta mediante `tool_results` para continuar. +- **Nuevas acciones CRUD**: mediante el campo `action` en el mismo endpoint se pueden completar `retrieve` / `retrieve_batch` / `update` / `delete`, sin necesidad de una API adicional de gestión de conversaciones. +- **Lista de modelos en actualización continua**: incorpora por defecto modelos contemporáneos como GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3, entre otros. -Al mismo tiempo, a nivel de cuerpo de solicitud es **totalmente compatible hacia atrás con v1**: pasando únicamente `model` + `question` (+ opcionalmente `stateful` / `id` / `references` / `preset`) se puede obtener una respuesta JSON `{answer, id}` equivalente a v1; por lo tanto, para migrar desde `/aichat/conversations` no es necesario reescribir el cliente, solo hay que cambiar la ruta a `/aichat2/conversations`. +Al mismo tiempo, es **completamente compatible hacia atrás con v1** a nivel del cuerpo de la solicitud: al enviar solo `model` + `question` (+ `stateful` / `id` / `references` / `preset` opcionales), se puede obtener una respuesta JSON `{answer, id}` equivalente a la de v1, por lo que no es necesario reescribir el cliente al migrar desde `/aichat/conversations`; solo hay que cambiar la ruta a `/aichat2/conversations`. -> Si actualmente utilizas `/aichat/conversations`, la antigua interfaz seguirá prestando servicio y puedes migrar a tu propio ritmo. +> Si actualmente estás usando `/aichat/conversations`, la antigua interfaz seguirá prestando servicio; puedes migrar a tu propio ritmo. ## Proceso de solicitud -Para utilizar AI Chat v2 API, primero obtén tu API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdalo como respaldo. +Para usar AI Chat v2 API, primero obtén tu API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdalo como respaldo. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Si aún no has iniciado sesión ni 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 completarlo, volverás automáticamente a la página actual. +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 completarlo, regresarás automáticamente a la página actual. -**Un solo API Token permite llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye crédito gratuito, lo que permite probarlo sin coste; cuando el crédito sea insuficiente, puedes recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin). +**Un solo API Token puede llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye créditos gratuitos para una experiencia sin costo; cuando los créditos sean insuficientes, puedes recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin). > 📘 Documentación completa: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Uso básico -El uso más sencillo es exactamente igual que v1: pasa `model` + `question` y obtén `{answer, id}`. +El uso más sencillo es exactamente igual que v1: envía `model` + `question` y obtén `{answer, id}`. Ejemplo de CURL: @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Los valores disponibles para `model` pueden verse directamente en el menú desplegable del panel Try de la derecha; las categorías comunes incluyen: +Los valores disponibles de `model` pueden verse directamente en el menú desplegable del panel Try a la derecha; las categorías comunes incluyen: - OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini`, etc. - Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`, etc. @@ -88,9 +88,9 @@ Los valores disponibles para `model` pueden verse directamente en el menú despl Para las reglas de facturación específicas, consulta la tarjeta Pricing de la página del servicio. -## Conversación multivuelta +## Conversaciones multivuelta -Al igual que en v1, pasa `stateful: true` para activar el guardado de la conversación; la API devolverá un `id`; en solicitudes posteriores, basta con incluir de nuevo el `id` para continuar la conversación, sin necesidad de mantener tú mismo el historial de messages. +Al igual que en v1, envía `stateful: true` para habilitar el guardado de la conversación; la API devolverá un `id`; en las solicitudes posteriores, basta con devolver el `id` para continuar la conversación, sin necesidad de mantener tú mismo el historial de messages. Primera solicitud: @@ -136,7 +136,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful` es `true` de forma predeterminada; omitirlo es equivalente a pasar explícitamente `true`. Si no deseas que el servidor guarde esta ronda de conversación, puedes establecer explícitamente `stateful: false`. +> `stateful` es `true` de forma predeterminada; omitirlo equivale a pasar explícitamente `true`. Si no quieres que el servidor guarde esta ronda de conversación, puedes establecer explícitamente `stateful: false`. ## Respuesta en streaming @@ -144,7 +144,7 @@ v2 admite dos formatos de streaming, seleccionados según la cabecera `accept`: | Escenario | `accept` | Forma de los datos | | --------------------- | ---------------------- | ------------------------------------------ | -| Frontend web / EventSource | `text/event-stream` | `data: {json}\n\n`, la última línea es `data: [DONE]\n\n` | +| Frontend web / EventSource | `text/event-stream` | `data: {json}\n\n`, con la última línea `data: [DONE]\n\n` | | Servidor / CLI / análisis de streaming de Node | `application/x-ndjson` | Un objeto JSON por línea | | No se necesita streaming | `application/json`（predeterminado） | Devuelve `{answer, id}` de una sola vez | @@ -195,7 +195,7 @@ Cada línea de NDJSON es un evento estructurado; el más común es `text_delta`: ### Ejemplo de SSE -El uso de `EventSource` en el navegador no admite cuerpos de solicitud personalizados; se recomienda usar `fetch` + análisis manual por segmentos de `\n\n`: +`EventSource` en el navegador no admite cuerpos de solicitud personalizados; se recomienda usar `fetch` + análisis manual por fragmentos de `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +236,24 @@ while (true) { | `type` | Significado | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Fragmento de texto incremental de la respuesta del asistente. `content` es el contenido nuevo; para ser compatible con v1, el mismo evento también incluye `delta_answer` (igual a `content`) e `id`. | +| `text_delta` | Fragmento de texto incremental de la respuesta del asistente. `content` es el contenido nuevo; para compatibilidad con v1, el mismo evento también incluye `delta_answer` (igual a `content`) e `id`. | | `thinking` | El proceso de razonamiento del modelo (solo aparece cuando el modelo seleccionado expone reasoning). | | `tool_use` | El modelo decide llamar a una herramienta; el evento incluye `tool_id`, `tool_name`, `input`. | -| `tool_result` | Resultado de la ejecución de la herramienta; se empareja con el `tool_use` anterior mediante `tool_id`, y `is_error` indica si falló. | -| `card` | Tarjeta estructurada producida por una herramienta (como una imagen o una vista previa de enlace), apta para renderizarse directamente. | -| `citation` | Se utiliza para complementar la URL de la fuente citada del fragmento de texto correspondiente. | -| `ask_user_question` | Se emite cuando el modelo necesita que el usuario proporcione información adicional; la conversación entra en el estado `awaiting_user_input`. Consulta a continuación [reanudar una conversación pausada](#恢复暂停的对话). | -| `artifact` | Producto independiente generado por el modelo (como un bloque de código o documento), que puede guardarse o descargarse. | -| `system_message` | Información de aviso del sistema (no contenido del usuario ni del asistente), solo para avisos de UI. | -| `compact` | Evento en el que se comprime el contexto interno; no requiere un tratamiento especial. | +| `tool_result` | Resultado de la ejecución de la herramienta, emparejado con el `tool_use` anterior mediante `tool_id`; `is_error` indica si falló. | +| `card` | Tarjeta estructurada producida por una herramienta (como imágenes o vistas previas de enlaces), adecuada para renderizar directamente. | +| `citation` | URL de la fuente utilizada para complementar las citas del fragmento de texto correspondiente. | +| `ask_user_question` | Se emite cuando el modelo necesita que el usuario proporcione información adicional; la conversación entra en el estado `awaiting_user_input`; consulta [reanudar una conversación pausada](#恢复暂停的对话) a continuación. | +| `artifact` | Producto independiente generado por el modelo (como bloques de código o documentos), que puede guardarse o descargarse. | +| `system_message` | Mensaje de aviso del sistema (no contenido del usuario ni del asistente), utilizado únicamente para avisos de UI. | +| `compact` | Evento en el que se comprimió el contexto interno; no requiere un manejo especial. | | `error` | Se produjo un error en esta ronda; `message` describe el contenido del error. | | `done` | Finaliza la respuesta en streaming; incluye `usage` (con `prompt_tokens` / `completion_tokens` / `total_tokens`) y `terminal_reason`. | -Para los clientes que solo se preocupan por la respuesta final, concatenar el `content` de todos los `text_delta` equivale a `answer` en el modo `application/json`. +Para los clientes a los que solo les importa la respuesta final, concatenar el `content` de todos los `text_delta` equivale al `answer` en el modo `application/json`. ## Entrada multimodal -Si la entrada del usuario incluye imágenes o archivos, pasa `message` (un array) en lugar de `question`. Cada elemento del array es un bloque de contenido: +Si la entrada del usuario contiene imágenes o archivos, pasa `message` (un arreglo) en lugar de `question`. Cada elemento del arreglo es un bloque de contenido: ```json { @@ -266,7 +266,7 @@ Si la entrada del usuario incluye imágenes o archivos, pasa `message` (un array } ``` -Tipos de bloques compatibles: +Tipos de bloque admitidos: - `text` — Texto normal; el campo `text` es obligatorio. - `image_url` — Imagen; `image_url.url` es obligatorio. @@ -274,24 +274,24 @@ Tipos de bloques compatibles: ### Relación con `references` de v1 -Para ser compatible con clientes antiguos, v2 sigue reconociendo el campo `references: ["https://...", ...]`: +Para compatibilidad con clientes antiguos, v2 todavía reconoce el campo `references: ["https://...", ...]`: - Si el sufijo de la URL es `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, se convierte automáticamente en un bloque `image_url`; -- Otras extensiones se convierten en un bloque `file_url`; +- Otros sufijos se convierten en un bloque `file_url`; - Si también se proporciona `question`, se antepone como un bloque `text`. Por lo tanto, si solo quieres migrar desde v1 y no quieres modificar el cuerpo de la solicitud, basta con cambiar la ruta a `/aichat2/conversations`, y el uso original de `references` seguirá funcionando normalmente. -Si necesitas un control más preciso (por ejemplo, colocar varias imágenes entre textos, o si el orden es muy importante), usa directamente el array `message`. +Si se necesita un control más preciso (por ejemplo, colocar varias imágenes entre textos, o si el orden es muy importante), usa directamente el arreglo `message`. ## Llamadas a herramientas y MCP -La mejora principal de v2 es que el modelo puede llamar autónomamente a herramientas para completar tareas de varios pasos, **esto está habilitado de forma predeterminada**, y no requiere que el cliente haga ninguna configuración adicional en la solicitud. Escenarios comunes: +La mejora principal de v2 es que el modelo puede llamar herramientas de forma autónoma para completar tareas de varios pasos, **esto está habilitado de forma predeterminada**, y no requiere que el cliente realice ninguna configuración adicional en la solicitud. Escenarios comunes: -- El usuario pregunta «Ayúdame a buscar qué nuevas exposiciones hay recientemente en Shanghái» → el modelo llama a la búsqueda web integrada → organiza los resultados en una respuesta. -- El usuario pregunta «Lee este PDF y luego escribe un resumen» → el modelo llama a file_read → escribe un resumen. -- El usuario ya ha autorizado Google Drive / GitHub / Notion, etc. en [Connections](https://platform.acedata.cloud/connections) → el modelo puede llamar a las herramientas MCP correspondientes para leer y escribir sus datos. +- El usuario pregunta «ayúdame a buscar qué exposiciones nuevas hay recientemente en Shanghái» → el modelo llama a la búsqueda web integrada → organiza los resultados en una respuesta. +- El usuario pregunta «lee este PDF y luego escribe un resumen» → el modelo llama a file_read → escribe el resumen. +- El usuario ya ha autorizado Google Drive / GitHub / Notion, etc. en [Connections](https://platform.acedata.cloud/connections) → el modelo puede llamar las herramientas MCP correspondientes para leer y escribir sus datos. -En el flujo NDJSON / SSE, las llamadas a herramientas se presentan mediante dos tipos de eventos: `tool_use` y `tool_result`, por ejemplo: +En flujos NDJSON / SSE, las llamadas a herramientas se presentan mediante dos tipos de eventos, `tool_use` y `tool_result`, por ejemplo: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -303,17 +303,17 @@ En el flujo NDJSON / SSE, las llamadas a herramientas se presentan mediante dos Si no quieres mostrar los detalles de las llamadas a herramientas en el frontend, basta con ignorar estos tipos de eventos: `tool_use` / `tool_result` / `card` / `citation`; la salida final del modelo seguirá fluyendo a través de `text_delta`. -`max_turns` puede limitar el máximo de rondas en que el modelo puede llamarse a sí mismo mediante herramientas en esta solicitud; el límite predeterminado lo determina la plataforma. Establecerlo bajo (por ejemplo, `max_turns: 1`) puede forzar una respuesta única y no permitir ninguna llamada a herramientas. +`max_turns` puede limitar cuántas rondas de autollamadas a herramientas puede realizar el modelo como máximo en esta solicitud, con un rango de 1–500 y un valor predeterminado de 500 si se omite. Establecerlo bajo (por ejemplo, `max_turns: 1`) puede forzar una respuesta única y no permitir ninguna llamada a herramientas. ## Ejecución asíncrona y autorización sin supervisión -Si tu llamada proviene de un Webhook de alertas, CI/CD, sistema de monitorización u otras tareas de backend, puedes establecer `async: true` para que la interfaz devuelva inmediatamente un ID de tarea y continúe ejecutándose en segundo plano: +Si tu llamada proviene de un Webhook de alerta, CI/CD, un sistema de monitoreo u otras tareas de backend, puedes establecer `async: true` para que la interfaz devuelva inmediatamente el ID de la tarea y continúe ejecutándose en segundo plano: ```json { "model": "gpt-5.5", "async": true, - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Mi servicio ha generado una alerta, notifica al grupo de WeChat «AceDataCloud团队» usando WeChat personal……" } ``` @@ -328,9 +328,9 @@ Ejemplo de respuesta: } ``` -Después, puedes usar `action: retrieve` + `id` para consultar el resultado de la conversación; también puedes proporcionar `callback_url`, y cuando la tarea se complete, la plataforma hará POST de `{ status, answer, usage, error }` a tu dirección de callback. `callback_url` debe usar `http` / `https`, y no puede indicar directamente `localhost` ni una dirección literal de IP privada. +Posteriormente, puedes usar `action: retrieve` + `id` para consultar el resultado de la conversación; también puedes proporcionar `callback_url`, y después de que la tarea se complete, la plataforma hará POST de `{ status, answer, usage, error }` a tu dirección de callback. `callback_url` debe usar `http` / `https`, y no se puede indicar directamente `localhost` ni una dirección IP privada literal. -Normalmente no hay nadie que pueda hacer clic para confirmar las tareas en segundo plano. Si deseas que ciertos Skill o MCP Server ejecuten acciones como enviar, publicar o escribir en modo sin supervisión, pasa explícitamente una lista de preautorización en el cuerpo de la solicitud: +Normalmente no hay nadie que pueda hacer clic para confirmar las tareas de backend. Si deseas que ciertos Skill o MCP Server realicen acciones como enviar, publicar o escribir en modo sin supervisión, pasa explícitamente una lista de preautorización en el cuerpo de la solicitud: ```json { @@ -338,13 +338,13 @@ Normalmente no hay nadie que pueda hacer clic para confirmar las tareas en segun "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Mi servicio ha generado una alerta, notifica al grupo de WeChat «AceDataCloud团队» usando WeChat personal……" } ``` -Los valores en `allowed_skills` son los slug de los Skill conectados; los valores en `allowed_mcp_servers` son los slug de los MCP Server conectados. Los Skill / MCP Server que no estén incluidos en la preautorización en modo sin supervisión solo podrán seguir previsualizando, hacer dry-run o rechazar operaciones de escritura. +Los valores en `allowed_skills` son los slug de los Skill conectados; los valores en `allowed_mcp_servers` son los slug de los MCP Server conectados. Los Skill / MCP Server que no estén incluidos en la preautorización, en modo sin supervisión, solo podrán seguir realizando vista previa, dry-run o rechazar operaciones de escritura. -Si necesitas un control más granular, también puedes usar el objeto equivalente `unattended_policy`: +Si se necesita un control más detallado, también se puede usar el objeto equivalente `unattended_policy`: ```json { @@ -358,24 +358,24 @@ Si necesitas un control más granular, también puedes usar el objeto equivalent La preautorización son estas dos listas en sí mismas: una lista vacía significa que no se autoriza ninguna capacidad, sin necesidad de campos de activación adicionales. -Nota: la preautorización solo significa «esta solicitud permite que estas capacidades omitan la confirmación humana en modo sin supervisión». El Skill concreto debe seguir admitiendo `--unattended-confirm` o el mecanismo de seguridad correspondiente; de lo contrario, seguirá haciendo dry-run y no ejecutará directamente operaciones de escritura. +Nota: la preautorización solo significa «esta solicitud permite que estas capacidades omitan la confirmación humana en modo sin supervisión». El Skill específico aún debe admitir `--unattended-confirm` o el mecanismo de seguridad correspondiente; de lo contrario, seguirá en dry-run y no ejecutará directamente operaciones de escritura. ## Reanudar conversaciones pausadas -Algunas herramientas hacen que el modelo «vuelva a preguntar al usuario»; en ese momento, el modelo emitirá un evento `ask_user_question`, y la conversación quedará congelada en el estado `awaiting_user_input`: +Algunas herramientas hacen que el modelo «haga una pregunta al usuario», momento en el que el modelo emitirá un evento `ask_user_question`, y la conversación se congela en el estado `awaiting_user_input`: ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "你希望生成的报告是中文还是英文？", + "question": "¿Deseas que el informe generado esté en chino o en inglés?", "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` -En el frontend, renderiza este evento como una tarjeta para que el usuario elija una respuesta y, a continuación, inicia la siguiente solicitud con el mismo `id`, rellenando la respuesta mediante `tool_results`: +Renderiza este evento como una tarjeta en el frontend para que el usuario elija una respuesta, y luego inicia la siguiente solicitud con el mismo `id`, completando la respuesta mediante `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -El `tool_use_id` en el cuerpo de la solicitud **debe** ser exactamente igual al `tool_id` del momento de la pausa; si no coincide, devolverá 400. Cuando `tool_results` existe simultáneamente en la solicitud, `question` / `message` / `references` se ignorarán todos. +El `tool_use_id` en el cuerpo de la solicitud **debe** ser exactamente igual al `tool_id` al momento de la pausa; si no coincide, se devolverá 400. Cuando existen simultáneamente `tool_results` en la solicitud, `question` / `message` / `references` se ignorarán. -Si el usuario decide abandonar esta pregunta, basta con pasar un nuevo `question` / `message`, y la plataforma marcará automáticamente la llamada a herramienta pausada como «omitida por el usuario». +Si el usuario decide abandonar esta pregunta, basta con pasar un nuevo `question` / `message`; la plataforma marcará automáticamente la llamada a herramienta pausada como «omitida por el usuario». ## Gestión de conversaciones (CRUD) -v2 proporciona una gestión ligera de conversaciones mediante el campo `action` en el mismo endpoint, sin necesidad de abrir otra API. +v2 proporciona una gestión ligera de conversaciones en el mismo endpoint mediante el campo `action`, sin necesidad de abrir otra API. +### `action: retrieve` —— Recuperar una conversación -### `action: retrieve` —— Obtener una conversación ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -417,7 +417,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ Devuelve el documento completo de la conversación (incluye el historial de `messages`, `model`, `title`, `tools_used`, etc.). -### `action: retrieve_batch` —— Listar resúmenes de conversaciones +### `action: retrieve_batch` —— Enumerar resúmenes de conversaciones ```json { @@ -428,7 +428,7 @@ Devuelve el documento completo de la conversación (incluye el historial de `mes } ``` -Devuelve `{ items: [...], total }`. **Los resúmenes no incluyen `messages`**, son adecuados para listas de barra lateral; si el usuario abre una conversación, use después `action: retrieve` para obtener por separado sus mensajes completos. +Devuelve `{ items: [...], total }`. **El resumen no incluye `messages`**, es adecuado para crear una lista en la barra lateral; si el usuario abre una conversación, usa después `action: retrieve` para recuperar por separado sus mensajes completos. Parámetros de filtrado opcionales: `user_id`, `application_id`, `model_group`, `model`. @@ -438,11 +438,11 @@ Parámetros de filtrado opcionales: `user_id`, `application_id`, `model_group`, { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "title": "Plan de viaje a Hangzhou" + "title": "杭州旅行计划" } ``` -También se puede pasar `messages`, pero el servidor realizará una validación estricta del schema (debe tener la forma de `ToolUseContent` contraída); si no cumple, devolverá 400. Por lo general, solo se recomienda usarlo para cambiar `title`. +También se puede enviar `messages`, pero el servidor realizará una validación estricta del schema (debe tener la forma `ToolUseContent` plegada); si no cumple, devolverá 400. Por lo general, solo se recomienda usarlo para cambiar `title`. ### `action: delete` —— Eliminar una conversación @@ -453,17 +453,17 @@ También se puede pasar `messages`, pero el servidor realizará una validación } ``` -Devuelve `{ id, success: true }`. No se puede recuperar después de eliminarla; confirme antes de realizar la llamada. +Devuelve `{ id, success: true }`. No se puede recuperar después de eliminarla, confirma antes de realizar la llamada. ## Migración fluida desde v1 -Si ya está utilizando [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), migrar a v2 casi no requiere cambios de código: +Si ya estás utilizando [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), migrar a v2 casi no requiere cambios de código: -1. Cambie la URL de `https://api.acedata.cloud/aichat/conversations` a `https://api.acedata.cloud/aichat2/conversations`. -2. Si antes enviaba nombres de modelos v1 (como `gpt-3.5`, `gpt-4-browsing`, etc.), al cambiar a v2 se recomienda actualizar a modelos contemporáneos (como `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview`, etc.). -3. Los campos del flujo NDJSON mantienen compatibilidad con versiones anteriores: cada evento `text_delta` sigue incluyendo `delta_answer` e `id`, por lo que los clientes existentes que analizan `delta_answer` línea por línea no requieren cambios. +1. Cambia la URL de `https://api.acedata.cloud/aichat/conversations` a `https://api.acedata.cloud/aichat2/conversations`. +2. Si antes enviabas nombres de modelos v1 (como `gpt-3.5`, `gpt-4-browsing`, etc.), al cambiar a v2 se recomienda actualizar a modelos contemporáneos (como `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview`, etc.). +3. Los campos del flujo NDJSON mantienen la compatibilidad hacia atrás: cada evento `text_delta` sigue incluyendo `delta_answer` e `id`, por lo tanto, los clientes que originalmente analizan `delta_answer` línea por línea no requieren cambios. -Después de la migración, puede habilitar según sea necesario las nuevas capacidades de v2 (`message` multimodal, SSE, llamadas a herramientas, CRUD mediante `action`), y avanzar al ritmo que prefiera. +Después de la migración, puedes habilitar según sea necesario las nuevas capacidades de v2 (`message` multimodal, SSE, llamadas a herramientas, CRUD de `action`) y avanzar según el ritmo previsto. ## Manejo de errores @@ -482,13 +482,13 @@ La respuesta de error se unifica como: Errores comunes: - `400 bad_request`: faltan campos obligatorios, `tool_use_id` no coincide, el schema de `messages` no es válido, etc. -- `401 invalid_token`: el encabezado `authorization` es incorrecto. -- `404 not_found`: la conversación correspondiente al `id` no existe al usar `action: retrieve / update / delete`. +- `401 invalid_token`: el encabezado `authorization` no es correcto. +- `404 not_found`: al realizar `action: retrieve / update / delete`, no existe la conversación correspondiente al `id`. - `429 too_many_requests`: se activó el límite de velocidad. -- `500 chat_error`: error del LLM ascendente o `completion_tokens=0` en esta ronda (se trata como no consumido y no se cobra). +- `500 chat_error`: error del LLM ascendente o `completion_tokens=0` en esta ronda (se procesa como no consumido y no se cobrará). -En la respuesta de flujo, los errores se emiten como eventos `{"type":"error","message":"..."}`, tras lo cual el flujo finalizará inmediatamente. +En la respuesta de streaming, el error se emite como un evento `{"type":"error","message":"..."}`, e inmediatamente después el flujo finalizará. ## Conclusión -AI Chat v2 API, manteniendo la compatibilidad con v1, actualiza las conversaciones de «preguntas y respuestas de una sola ronda / múltiples rondas» a «conversaciones observables orientadas a agentes»: entrada multimodal, llamadas a herramientas, pausa / reanudación, eventos estructurados en flujo y CRUD integrado. Se recomienda usar directamente v2 para nuevas integraciones; las integraciones existentes de v1 pueden migrarse fluidamente por etapas. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico. +La API AI Chat v2, al mantener la compatibilidad hacia atrás con v1, actualiza las conversaciones de «preguntas y respuestas de una sola ronda / múltiples rondas» a «conversaciones observables orientadas a Agent»: entradas multimodales, llamadas a herramientas, pausables / reanudables, eventos estructurados en streaming y CRUD integrado. Se recomienda usar directamente v2 para nuevas integraciones; las integraciones existentes de v1 pueden migrarse gradualmente sin problemas. Si tienes alguna pregunta, no dudes en contactar en cualquier momento con nuestro equipo de soporte técnico. diff --git a/es/guides/platform/hermes_managed.mdx b/es/guides/platform/hermes_managed.mdx index 11a709cb5..bfef55486 100644 --- a/es/guides/platform/hermes_managed.mdx +++ b/es/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Implementación Privada de Hermes Agent" +title: "Despliegue de Hermes" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud proporciona un acceso a la implementación privada de Hermes Agent. Este acceso es un servicio controlado, y la disponibilidad y los recursos opcionales se rigen por lo que actualmente muestra la consola. +Crea una instancia de contenedor Hermes independiente para cada Application. De forma predeterminada, se utiliza una imagen base de una versión de lanzamiento fija, conservando las funciones nativas; la plataforma proporciona compra, renovación, almacenamiento persistente y gestión de despliegue. -## Pasos a seguir +## Creación y compra -1. Encuentra **Implementación Privada de Hermes Agent** en la plataforma. -2. Selecciona la configuración disponible y crea el servicio según las indicaciones de la página. -3. Espera a que la plataforma muestre el estado de listo. -4. Accede a la instancia utilizando el acceso y las credenciales proporcionadas en la página. -5. Envía primero `Reply only OK`, y luego comienza la tarea real. +1. Abre [Despliegue de Hermes](https://platform.acedata.cloud/services/hermes) y crea una Application. +2. En la página de compra, selecciona un plan de duración y completa el pago. +3. Regresa a la página de configuración, donde puedes seleccionar un modelo de chat de la plataforma desde la lista desplegable y consultar el precio actual del modelo. La plataforma creará credenciales de API independientes para esta instancia; también puedes desactivar el acceso de la plataforma y configurarlo tú mismo en la consola nativa. +4. Elige generar automáticamente las credenciales de acceso o establece tu propia contraseña/Token seguro, y comienza el despliegue tras confirmar. Las credenciales de acceso y las credenciales de API del modelo son independientes entre sí. +5. Cuando la instancia esté lista, obtén la dirección de acceso y las credenciales de inicio de sesión desde la página de administración. +6. Inicia sesión en la consola nativa y configura tus propios proveedores de modelos, claves y canales. -El modelo, las credenciales, el almacenamiento y el comportamiento de eliminación se rigen por la página de creación y el cuadro de confirmación; no utilices directamente el YAML del tutorial local de Hermes como contrato de implementación en la plataforma. Exporta primero los datos que necesites conservar antes de eliminar. +La tarifa de despliegue se cobra según la duración del plan; los precios específicos en dólares estadounidenses y las duraciones estarán sujetos a la página de compra. Los costos de invocación de modelos se cobran por separado; comprar tiempo de despliegue no incluye crédito de modelo. Cuando se habilita el acceso de la plataforma, las credenciales de API dedicadas solo habilitan la interfaz de chat correspondiente al modelo seleccionado, y las invocaciones se cobran adicionalmente de tu saldo de plataforma. Cada Application se compra, renueva y administra por separado. -Si la consola no muestra el acceso a la creación, significa que la cuenta actual aún no tiene habilitado este servicio, puedes optar por usar [Asistente Interactivo de Hermes](https://platform.acedata.cloud/documents/hermes-wizard-integration) o [Configuración Manual](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Contraseñas, credenciales y configuración posterior + +Las credenciales de acceso se establecen antes del primer inicio. La generación automática utiliza credenciales aleatorias; la contraseña personalizada debe tener al menos 16 caracteres y el Token de OpenClaw al menos 32 caracteres. Los borradores no guardan contraseñas; es posible que debas volver a introducirlas después de cambiar de página. Tras el despliegue, solo el propietario y los administradores de la Application pueden ver las credenciales de acceso. + +Las credenciales de API de modelo de cada instancia no se reutilizan entre sí, su período de validez se extiende con la renovación del despliegue y se revocan al eliminar la instancia. Después de la inicialización del despliegue, modifica los modelos y canales en la consola nativa; si cambias para seleccionar modelos de otros servicios, ajusta primero la autorización de la interfaz correspondiente en la gestión de credenciales de la plataforma, o utiliza las credenciales correspondientes. Un redespliegue normal no sobrescribirá la configuración nativa. Los entornos de despliegue que no hayan superado la validación de publicación rechazarán temporalmente nuevos despliegues; contacta con soporte. + +## Versiones y datos + +La página de configuración muestra la versión de imagen publicada actualmente. Las nuevas instancias utilizan la versión publicada actual del servicio; las instancias existentes no se reemplazarán automáticamente con las actualizaciones del catálogo. El redespliegue aplicará la versión actual del servicio; realiza primero una copia de seguridad y confirma los requisitos de actualización de la versión utilizada. + +Cada instancia proporciona de forma predeterminada 1 CPU, un límite de memoria de 2 GiB y 10 GiB de almacenamiento persistente. Los reinicios conservan los datos de la instancia. La eliminación activa del despliegue o la recuperación tras el vencimiento eliminarán el almacenamiento; exporta con antelación los datos que necesites conservar. + +## Renovación y vencimiento + +Renueva en la página de compra de la Application actual; el período de validez se extenderá según las reglas de duración vigentes de la plataforma. Tras el vencimiento, el acceso se suspende; renovar durante el período de gracia restablece el acceso. Si se supera el período de gracia, la instancia y los datos se recuperarán. Prevalecerán la hora de vencimiento, el estado de facturación y los avisos de eliminación de la página de administración. + +## Inicio de sesión en la interfaz de administración + +En la página de gestión del despliegue, copia la dirección del Dashboard, el nombre de usuario `admin` y la contraseña, y ábrela para iniciar sesión. La información de inicio de sesión solo se proporciona al propietario de esa Application y a los administradores de la plataforma. Los modelos, habilidades y canales se configuran en la interfaz nativa de Hermes. + +## Preguntas frecuentes + +- **¿Por qué la nueva instancia aún no puede responder?** La finalización del despliegue significa que el contenedor está listo; debes configurar el modelo y las credenciales en la interfaz nativa antes de poder empezar a utilizarlo. +- **¿Se preinstalan complementos adicionales o fallback de modelos?** No se añaden de forma predeterminada; configúralos según sea necesario en la interfaz nativa. +- **¿Cómo se actualiza una instancia existente?** La Application y el pedido originales se conservan, y se utiliza la versión actual del servicio al redesplegar; realiza primero una copia de seguridad de los datos y comprueba la compatibilidad de versiones antes de actualizar. +- **¿Qué hacer si el inicio falla?** Primero consulta los registros y eventos del despliegue, y configura el modelo después de confirmar que la instancia está lista. No expongas las contraseñas y claves de la instancia en comentarios públicos o capturas de pantalla. diff --git a/es/guides/platform/wework_bot.mdx b/es/guides/platform/wework_bot.mdx deleted file mode 100644 index d0e758b34..000000000 --- a/es/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/fi/guides/aichat/aichat2_conversations.mdx index 6363bfa74..f51ce9226 100644 --- a/fi/guides/aichat/aichat2_conversations.mdx +++ b/fi/guides/aichat/aichat2_conversations.mdx @@ -1,36 +1,36 @@ --- -title: "AI Chat v2 API -integraation ohje" +title: "AI Chat v2 API -integrointiohjeet" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API (`/aichat2/conversations`) on uuden sukupolven keskustelurajapinta ja [AI Chat API:n](https://platform.acedata.cloud/documents/aichat-conversations) kokonaisvaltaisesti päivitetty versio. Se laajentaa v1:n yksinkertaista, hallinnoitua monikierroksista keskustelua seuraavasti: +AI Chat v2 API (`/aichat2/conversations`) on uuden sukupolven keskustelurajapinta ja [AI Chat API:n](https://platform.acedata.cloud/documents/aichat-conversations) kattavasti päivitetty versio. Se laajentaa v1:n yksinkertaista, hallittua monikierroksista keskustelua seuraavilla ominaisuuksilla: -- **Monimodaaliset käyttäjäsyötteet**: Lähetä teksti + kuva + tiedostolohkot suoraan rakenteellisen `message`-kentän kautta ilman, että ne tarvitsee ensin liittää epäsuorasti `references`-kentällä. -- **Agenttimaiset työkalukutsut**: Sisältää joukon työkaluja verkkohakuun, verkkosivujen noutamiseen, tiedostojen lukemiseen jne., ja siihen voidaan liittää käyttäjän valtuuttamia MCP-palvelimia (Google Drive, Notion, Slack, GitHub jne.). Malli voi kutsua työkaluja itsenäisesti useilla kierroksilla yhden pyynnön aikana monimutkaisten tehtävien suorittamiseksi. -- **Rakenteiset suoratoistotapahtumat**: `accept: text/event-stream`- tai `application/x-ndjson`-asetuksella voidaan saada token kerrallaan `text_delta`-, `tool_use`-, `tool_result`-, `thinking`-, `citation`-, `card`-, `artifact`- ja muita tapahtumia, mikä helpottaa niiden erillistä renderöintiä käyttöliittymässä vastaavan tyypin mukaan. -- **Keskeytettävä / jatkettava**: Kun malli tarvitsee käyttäjältä lisätietoja, se lähettää `ask_user_question`-tapahtuman ja keskeytyy. Seuraavassa kutsussa vastaus voidaan täyttää takaisin `tool_results`-kentän kautta ja jatkaa. -- **Uudet CRUD-toiminnot**: Suorita `retrieve` / `retrieve_batch` / `update` / `delete` `action`-kentän avulla samassa endpointissa ilman erillistä keskustelunhallinta-API:a. -- **Jatkuvasti päivittyvä malliluettelo**: Oletuksena käytettävissä ovat nykyajan mallit, kuten GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 jne. +- **Monimuotoiset käyttäjäsyötteet**: rakenneistetun `message`-kentän kautta voi lähettää suoraan teksti- + kuva- + tiedostolohkoja ilman, että ne tarvitsee ensin liittää epäsuorasti `references`-kentällä. +- **Agenttipohjaiset työkalukutsut**: sisältää joukon verkkohaku-, verkkosivujen nouto-, tiedostonluku- ja muita työkaluja, ja siihen voidaan liittää käyttäjän valtuuttamia MCP-palvelimia (Google Drive, Notion, Slack, GitHub jne.). Malli voi yhdessä pyynnössä kutsua työkaluja itsenäisesti useilla kierroksilla monimutkaisten tehtävien suorittamiseksi. +- **Rakenteistetut suoratoistotapahtumat**: käyttämällä `accept: text/event-stream`- tai `application/x-ndjson`-asetusta voidaan saada token kerrallaan `text_delta`-, `tool_use`-, `tool_result`-, `thinking`-, `citation`-, `card`-, `artifact`- ja muita tapahtumia, mikä helpottaa niiden erillistä renderöintiä käyttöliittymässä tyypin mukaan. +- **Keskeytettävissä / jatkettavissa**: kun malli tarvitsee käyttäjältä lisätietoja, se lähettää `ask_user_question`-tapahtuman ja keskeyttää toiminnan. Seuraavalla kutsulla vastaukset voidaan täyttää takaisin `tool_results`-kentän kautta, jolloin toiminta jatkuu. +- **Uudet CRUD-toiminnot**: samalla endpointilla voidaan suorittaa `retrieve` / `retrieve_batch` / `update` / `delete` `action`-kentän avulla ilman erillistä keskustelunhallinta-APIa. +- **Jatkuvasti päivittyvä malliluettelo**: oletusarvoisesti käytettävissä ovat nykyaikaiset mallit, kuten GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4 ja Kimi K3. -Samalla se on pyyntörungon tasolla **täysin taaksepäin yhteensopiva v1:n kanssa**: Lähettämällä vain `model` + `question` (+ valinnaiset `stateful` / `id` / `references` / `preset`) saat v1:tä vastaavan `{answer, id}` JSON-vastauksen. Näin ollen `/aichat/conversations`-rajapinnasta siirryttäessä asiakasohjelmaa ei tarvitse kirjoittaa uudelleen, vaan polku tarvitsee vain vaihtaa muotoon `/aichat2/conversations`. +Samalla se on pyyntörungon tasolla **täysin taaksepäin yhteensopiva v1:n kanssa**: lähettämällä vain `model` + `question` (+ valinnaiset `stateful` / `id` / `references` / `preset`) saat v1:tä vastaavan `{answer, id}` JSON-vastauksen. Siksi siirtyminen `/aichat/conversations`-rajapinnasta ei edellytä asiakasohjelman uudelleenkirjoittamista; riittää, että polku vaihdetaan muotoon `/aichat2/conversations`. -> Jos käytät tällä hetkellä `/aichat/conversations`-rajapintaa, vanha rajapinta pysyy edelleen käytössä, ja voit siirtyä omaan tahtiisi. +> Jos käytät tällä hetkellä `/aichat/conversations`-rajapintaa, vanha rajapinta säilyy edelleen käytettävissä, ja voit siirtyä omaan tahtiisi. ## Hakuprosessi -Käyttääksesi AI Chat v2 API:a hae ensin API Tokenisi [Ace Data Cloud -konsolista](https://platform.acedata.cloud/console/applications) ja säilytä se varalla. +Käyttääksesi AI Chat v2 APIa hae ensin API Tokenisi [Ace Data Cloud -konsolista](https://platform.acedata.cloud/console/applications) ja säilytä 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, minkä jälkeen palaat automaattisesti nykyiselle sivulle. +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 nykyiselle sivulle. -**Yhdellä API Tokenilla voi kutsua kaikkia alustan palveluita, eikä sitä tarvitse hakea erikseen jokaiselle palvelulle.** Ensimmäisen hakemuksen yhteydessä annetaan ilmaiskiintiö maksutonta kokeilua varten; jos kiintiö ei riitä, voit ladata yleissaldoa [konsolissa](https://platform.acedata.cloud/console/coin). +**Yhdellä API Tokenilla voi kutsua kaikkia alustan palveluita, eikä jokaiselle palvelulle tarvitse hakea erikseen omaa tunnusta.** Ensimmäisestä hakemuksesta myönnetään maksutonta käyttökiintiötä ilmaista kokeilua varten; jos kiintiö ei riitä, voit ladata yleissaldoa [konsolissa](https://platform.acedata.cloud/console/coin). > 📘 Täydellinen dokumentaatio: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Peruskäyttö -Yksinkertaisin käyttötapa on täysin sama kuin v1: lähetä `model` + `question` ja saat `{answer, id}`. +Yksinkertaisin käyttö vastaa täysin v1:tä: lähetä `model` + `question` ja vastaanota `{answer, id}`. CURL-esimerkki: @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Käytettävissä olevat `model`-arvot näkyvät suoraan oikeanpuoleisen Try-paneelin pudotusvalikossa, ja yleisiä luokkia ovat: +Käytettävissä olevat `model`-arvot näkyvät suoraan oikealla olevan Try-paneelin pudotusvalikossa. Yleisiä luokkia ovat: - OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` jne. - Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` jne. @@ -90,7 +90,7 @@ Katso tarkat hinnoittelusäännöt palvelusivun Pricing-kortista. ## Monikierroksinen keskustelu -Kuten v1:ssä, lähetä `stateful: true` ottaaksesi keskustelun tallennuksen käyttöön. API palauttaa `id`:n; seuraavissa pyynnöissä riittää, että lähetät `id`:n mukana keskustelun jatkamiseksi, eikä messages-historiaa tarvitse ylläpitää itse. +Kuten v1:ssä, lähetä `stateful: true` ottaaksesi keskustelun tallennuksen käyttöön. API palauttaa `id`-tunnuksen; seuraavissa pyynnöissä voit jatkaa keskustelua lähettämällä `id`-tunnuksen takaisin ilman, että sinun tarvitsee itse ylläpitää messages-historiaa. Ensimmäinen pyyntö: @@ -115,7 +115,7 @@ Palautus: } ``` -Toinen pyyntö, lisää sama `id`: +Toinen pyyntö, lähetä sama `id` mukana: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -136,11 +136,11 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful` on oletusarvoisesti `true`; sen pois jättäminen vastaa `true`-arvon välittämistä eksplisiittisesti. Jos et halua palvelinpuolen tallentavan tätä keskustelukierrosta, voit asettaa eksplisiittisesti `stateful: false`. +> `stateful` on oletusarvoisesti `true`; sen pois jättäminen vastaa `true`-arvon antamista eksplisiittisesti. Jos et halua palvelinpuolen tallentavan tätä keskustelukierrosta, voit asettaa eksplisiittisesti `stateful: false`. ## Suoratoistovastaus -v2 tukee kahta suoratoistomuotoa, jotka valitaan `accept`-otsakkeen perusteella: +v2 tukee kahta suoratoistomuotoa, jotka valitaan `accept`-otsakkeen mukaan: | Tilanne | `accept` | Tietomuoto | | --------------------- | ---------------------- | ------------------------------------------ | @@ -195,7 +195,7 @@ Jokainen NDJSON-rivi on strukturoitu tapahtuma, joista yleisin on `text_delta`: ### SSE-esimerkki -Selaimessa `EventSource` ei tue mukautettua pyyntörunkoa, joten on suositeltavaa käyttää `fetch`-kutsua + manuaalista jäsennystä viipaloimalla `\n\n`-kohdista: +Selainpuolen `EventSource` ei tue mukautettuja pyyntöjä, joten on suositeltavaa käyttää `fetch`-kutsua + manuaalista jäsentämistä `\n\n`-erottimella: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +236,24 @@ while (true) { | `type` | Merkitys | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Avustajan vastauksen inkrementaalinen tekstikatkelma. `content` on lisätty sisältö; v1-yhteensopivuuden vuoksi sama tapahtuma sisältää myös `delta_answer`-kentän (sama kuin `content`) ja `id`:n. | -| `thinking` | Mallin ajatteluprosessi (esiintyy vain, kun valittu malli paljastaa päättelynsä). | +| `text_delta` | Avustajan vastauksen inkrementaalinen tekstikatkelma. `content` on uusi sisältö; v1-yhteensopivuuden vuoksi sama tapahtuma sisältää myös `delta_answer`-kentän (sama kuin `content`) ja `id`:n. | +| `thinking` | Mallin ajatteluprosessi (näkyy vain, kun valittu malli paljastaa reasoning-tiedot). | | `tool_use` | Malli päättää kutsua työkalua; tapahtuma sisältää `tool_id`:n, `tool_name`:n ja `input`:n. | -| `tool_result` | Työkalun suoritustulos, joka yhdistetään edelliseen `tool_use`-tapahtumaan `tool_id`:n kautta; `is_error` ilmaisee, epäonnistuiko se. | -| `card` | Työkalun tuottama strukturoitu kortti (kuten kuva tai linkin esikatselu), joka soveltuu suoraan renderöitäväksi. | -| `citation` | Lähde-URL, jota käytetään vastaavan tekstikatkelman viitteiden täydentämiseen. | -| `ask_user_question` | Lähetetään, kun malli tarvitsee käyttäjältä lisätietoja; keskustelu siirtyy `awaiting_user_input`-tilaan, katso alempaa [keskeytetyn keskustelun jatkaminen](#恢复暂停的对话). | +| `tool_result` | Työkalun suoritusresultaatio, joka yhdistetään edelliseen `tool_use`-tapahtumaan `tool_id`:n kautta; `is_error` ilmaisee, epäonnistuiko se. | +| `card` | Työkalun tuottama strukturoitu kortti (kuten kuva tai linkin esikatselu), joka sopii suoraan renderöitäväksi. | +| `citation` | Käytetään vastaavan tekstikatkelman viittausten lähde-URL-osoitteiden täydentämiseen. | +| `ask_user_question` | Lähetetään, kun malli tarvitsee käyttäjältä lisätietoja; keskustelu siirtyy `awaiting_user_input`-tilaan, katso alempaa [keskeytetyn keskustelun jatkaminen](#keskeytetyn-keskustelun-jatkaminen). | | `artifact` | Mallin luoma itsenäinen tuotos (kuten koodilohko tai asiakirja), joka voidaan tallentaa tai ladata. | -| `system_message` | Järjestelmän ilmoitusviesti (ei käyttäjän eikä avustajan sisältöä), vain käyttöliittymän ilmoituksia varten. | -| `compact` | Tapahtuma, jossa sisäinen konteksti on pakattu; ei vaadi erityiskäsittelyä. | +| `system_message` | Järjestelmän ilmoitustieto (ei käyttäjän tai avustajan sisältöä), vain käyttöliittymäilmoituksia varten. | +| `compact` | Tapahtuma, jossa sisäinen konteksti on tiivistetty; ei vaadi erityiskäsittelyä. | | `error` | Tällä kierroksella tapahtui virhe; `message` kuvaa virheen sisällön. | | `done` | Suoratoistovastaus päättyy; sisältää `usage`-tiedot (mukaan lukien `prompt_tokens` / `completion_tokens` / `total_tokens`) ja `terminal_reason`:n. | -Asiakasohjelmille, jotka välittävät vain lopullisesta vastauksesta, kaikkien `text_delta`-tapahtumien `content`-arvojen yhdistäminen vastaa `application/json`-tilan `answer`-arvoa. +Asiakkaille, jotka välittävät vain lopullisesta vastauksesta, kaikkien `text_delta`-tapahtumien `content`-kenttien yhdistäminen vastaa `application/json`-tilan `answer`-kenttää. -## Monimodaalinen syöte +## Multimodaalinen syöte -Jos käyttäjän syöte sisältää kuvan tai tiedoston, välitä `message` (taulukko) `question`-kentän sijaan. Jokainen taulukon elementti on sisältölohko: +Jos käyttäjän syöte sisältää kuvia tai tiedostoja, välitä `message` (taulukko) `question`-kentän sijaan. Jokainen taulukkoelementti on sisältölohko: ```json { @@ -268,30 +268,30 @@ Jos käyttäjän syöte sisältää kuvan tai tiedoston, välitä `message` (tau Tuetut lohkotyypit: -- `text` — Tavallinen teksti, vaatii `text`-kentän. -- `image_url` — Kuva, vaatii `image_url.url`-kentän. -- `file_url` — Tiedosto (PDF, CSV, TXT jne.), vaatii `file_url.url`-kentän. +- `text` — Tavallinen teksti, `text`-kenttä on pakollinen. +- `image_url` — Kuva, `image_url.url` on pakollinen. +- `file_url` — Tiedosto (PDF, CSV, TXT jne.), `file_url.url` on pakollinen. ### Suhde v1:n `references`-kenttään -Vanhojen asiakasohjelmien yhteensopivuuden vuoksi v2 tunnistaa edelleen `references: ["https://...", ...]` -kentän: -- Jos URL-pääte on `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, se muunnetaan automaattisesti `image_url`-lohkoksi; +Vanhojen asiakkaiden yhteensopivuuden vuoksi v2 tunnistaa edelleen kentän `references: ["https://...", ...]`: +- URL-pääte on `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, muunnetaan automaattisesti `image_url`-lohkoksi; - Muut tiedostopäätteet muunnetaan `file_url`-lohkoksi; -- Jos samalla annetaan myös `question`, se asetetaan eteen `text`-lohkoksi. +- Jos samalla annetaan myös `question`, se sijoitetaan edelle `text`-lohkona. -Jos siis haluat vain siirtyä v1:stä etkä halua muuttaa pyyntörungkoa, riittää, että vaihdat poluksi `/aichat2/conversations`; alkuperäinen `references`-käyttötapa toimii edelleen normaalisti. +Jos siis haluat vain siirtyä v1:stä etkä halua muuttaa pyyntörungkoa, vaihda poluksi `/aichat2/conversations`, jolloin alkuperäinen `references`-käyttö toimii edelleen normaalisti. -Jos tarvitset tarkempaa hallintaa (esimerkiksi haluat sijoittaa useita kuvia tekstien väliin tai järjestys on tärkeä), käytä suoraan `message`-taulukkoa. +Jos tarvitset tarkempaa hallintaa (esimerkiksi useiden kuvien sijoittamista tekstin väliin tai jos järjestys on tärkeä), käytä suoraan `message`-taulukkoa. ## Työkalukutsut ja MCP -v2:n keskeinen parannus on, että malli voi kutsua itsenäisesti työkaluja monivaiheisten tehtävien suorittamiseksi, **tämä on oletusarvoisesti käytössä**, eikä asiakasohjelman tarvitse tehdä pyynnössä mitään lisämäärityksiä. Tyypillisiä tilanteita: +v2:n keskeinen parannus on, että malli voi itsenäisesti kutsua työkaluja monivaiheisten tehtävien suorittamiseksi, **tämä on oletusarvoisesti käytössä**, eikä asiakasohjelman tarvitse tehdä pyynnössä mitään lisämäärityksiä. Yleisiä tilanteita: -- Käyttäjä kysyy: ”Etsi minulle, mitä uusia näyttelyitä Shanghaissa on lähiaikoina” → malli kutsuu sisäänrakennettua web searchia → jäsentää tulokset vastaukseksi. -- Käyttäjä kysyy: ”Lue tämä PDF ja kirjoita sitten tiivistelmä” → malli kutsuu file_readia → kirjoittaa tiivistelmän. +- Käyttäjä kysyy: ”Etsi minulle, mitä uusia näyttelyitä Shanghaissa on lähiaikoina” → malli kutsuu sisäänrakennettua web-hakua → kokoaa tulokset vastaukseksi. +- Käyttäjä kysyy: ”Lue tämä PDF ja kirjoita sitten tiivistelmä” → malli kutsuu file_read-työkalua → kirjoittaa tiivistelmän. - Käyttäjä on valtuuttanut [Connections](https://platform.acedata.cloud/connections)-kohdassa Google Driven / GitHubin / Notionin jne. → malli voi kutsua vastaavia MCP-työkaluja niiden tietojen lukemiseen ja kirjoittamiseen. -NDJSON- / SSE-virrassa työkalukutsut esitetään `tool_use`- ja `tool_result`-tapahtumien kautta, esimerkiksi: +NDJSON- / SSE-virrassa työkalukutsut esitetään kahden tapahtumatyypin, `tool_use` ja `tool_result`, kautta, esimerkiksi: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,19 +301,19 @@ NDJSON- / SSE-virrassa työkalukutsut esitetään `tool_use`- ja `tool_result`-t ... ``` -Jos et halua näyttää työkalukutsujen yksityiskohtia käyttöliittymässä, riittää, että ohitat `tool_use` / `tool_result` / `card` / `citation` -tapahtumatyypit; mallin lopullinen tuloste virtaa silti `text_delta`-tapahtumien kautta. +Jos et halua näyttää työkalukutsujen yksityiskohtia käyttöliittymässä, jätä huomiotta tapahtumatyypit `tool_use` / `tool_result` / `card` / `citation`; mallin lopullinen tuloste virtaa edelleen `text_delta`-tapahtumien kautta. -`max_turns` voi rajoittaa, kuinka monta kierrosta malli voi enintään kutsua työkaluja itse tässä pyynnössä; oletusylärajan määrittää alusta. Sen asettaminen pieneksi (esimerkiksi `max_turns: 1`) voi pakottaa yksittäisen vastauksen eikä sallia mitään työkalukutsuja. +`max_turns` voi rajoittaa, kuinka monta kierrosta malli voi enintään kutsua työkaluja itse tässä pyynnössä; arvoalue on 1–500, ja jos se jätetään pois, oletusarvo on 500. Sen asettaminen pieneksi (esimerkiksi `max_turns: 1`) voi pakottaa kertaluonteisen vastauksen eikä salli mitään työkalukutsuja. ## Asynkroninen suoritus ja valtuutus ilman valvontaa -Jos kutsusi tulee hälytys-Webhookista, CI/CD:stä, valvontajärjestelmästä tai muusta taustatehtävästä, voit asettaa `async: true`, jolloin rajapinta palauttaa välittömästi tehtävätunnuksen ja jatkaa suoritusta taustalla: +Jos kutsusi tulee hälytys-Webhookista, CI/CD:stä, valvontajärjestelmästä tai muusta taustatehtävästä, voit asettaa `async: true`, jolloin rajapinta palauttaa tehtävätunnuksen välittömästi ja jatkaa suorittamista taustalla: ```json { "model": "gpt-5.5", "async": true, - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Palveluni hälyttää, ilmoita henkilökohtaisella WeChatilla WeChat-ryhmälle 「AceDataCloud团队」……" } ``` @@ -328,9 +328,9 @@ Palautusesimerkki: } ``` -Tämän jälkeen voit käyttää `action: retrieve` + `id` -yhdistelmää keskustelun tuloksen kyselyyn; voit myös antaa `callback_url`-osoitteen, jolloin tehtävän valmistuttua alusta POSTaa `{ status, answer, usage, error }` takaisinsoitto-osoitteeseesi. `callback_url`-osoitteen on käytettävä `http` / `https`-protokollaa, eikä siinä voi suoraan ilmoittaa `localhost`-osoitetta tai yksityisen IP-osoitteen literaalia. +Tämän jälkeen voit hakea keskustelun tuloksen käyttämällä `action: retrieve` + `id`; voit myös antaa `callback_url`-osoitteen, jolloin alusta POSTaa `{ status, answer, usage, error }` takaisinsoitto-osoitteeseesi tehtävän valmistuttua. `callback_url`-osoitteen on käytettävä `http` / `https`-protokollaa, eikä siihen voi suoraan kirjoittaa `localhost`-osoitetta tai yksityisen IP:n literaaliosoitetta. -Taustatehtävissä ei yleensä ole ketään, joka voisi klikata vahvistusta. Jos haluat, että tietyt Skillit tai MCP Serverit suorittavat lähetys-, julkaisu-, kirjoitus- tai muita toimintoja ilman valvontaa, välitä pyynnön rungossa nimenomaisesti esivaltuutusluettelo: +Taustatehtävissä ei yleensä ole ketään, joka voisi klikata vahvistuksen. Jos haluat tiettyjen Skillien tai MCP Serverien suorittavan lähetys-, julkaisu-, kirjoitus- tai muita toimintoja ilman valvontaa, välitä pyynnön rungossa nimenomaisesti esivaltuutuslista: ```json { @@ -338,13 +338,13 @@ Taustatehtävissä ei yleensä ole ketään, joka voisi klikata vahvistusta. Jos "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Palveluni hälyttää, ilmoita henkilökohtaisella WeChatilla WeChat-ryhmälle 「AceDataCloud团队」……" } ``` -`allowed_skills`-arvot ovat yhdistettyjen Skillien slugeja; `allowed_mcp_servers`-arvot ovat yhdistettyjen MCP Serverien slugeja. Skillit / MCP Serverit, joita ei ole sisällytetty esivaltuutukseen, voivat ilman valvontaa toimivassa tilassa edelleen vain esikatsella, suorittaa dry-runin tai kieltäytyä kirjoitustoiminnon suorittamisesta. +`allowed_skills`-kohdan arvot ovat yhdistettyjen Skillien slug-arvoja; `allowed_mcp_servers`-kohdan arvot ovat yhdistettyjen MCP Serverien slug-arvoja. Skillit / MCP Serverit, joita ei ole lueteltu esivaltuutuksissa, voivat ilman valvontaa toimivassa tilassa edelleen vain esikatsella, suorittaa dry-runin tai kieltäytyä kirjoitustoimintojen suorittamisesta. -Jos tarvitset tarkempaa hallintaa, voit käyttää myös vastaavaa `unattended_policy`-objektia: +Jos tarvitset tarkempaa hallintaa, voit myös käyttää vastaavaa `unattended_policy`-objektia: ```json { @@ -356,26 +356,26 @@ Jos tarvitset tarkempaa hallintaa, voit käyttää myös vastaavaa `unattended_p } ``` -Esivaltuutus on juuri nämä kaksi luetteloa: tyhjä luettelo tarkoittaa, ettei mitään toimintoja valtuuteta, eikä erillistä kytkinkenttää tarvita. +Esivaltuutus koostuu näistä kahdesta listasta itsestään: tyhjä lista ei valtuuta mitään toimintoja, eikä erillistä kytkentäkenttää tarvita. -Huomaa: esivaltuutus tarkoittaa vain, että ”tämä pyyntö sallii näiden ominaisuuksien ohittaa ihmisen vahvistuksen ilman valvontaa olevassa tilassa”. Kyseisen Skillin on silti tuettava `--unattended-confirm`-toimintoa tai vastaavaa turvamekanismia; muussa tapauksessa se jatkaa dry-run-tilassa eikä suorita kirjoitustoimintoa suoraan. +Huomaa: esivaltuutus tarkoittaa vain, että ”tämä pyyntö sallii näiden ominaisuuksien ohittaa ihmisen vahvistuksen ilman valvontaa”. Kyseisen Skillin on silti tuettava `--unattended-confirm`-toimintoa tai vastaavaa turvallisuusmekanismia; muutoin se jatkaa dry-run-tilassa eikä suorita kirjoitustoimintoa suoraan. ## Keskeytetyn keskustelun jatkaminen -Jotkin työkalut saavat mallin ”esittämään käyttäjälle vastakysymyksen”; tällöin malli lähettää `ask_user_question`-tapahtuman, ja keskustelu jäädytetään `awaiting_user_input`-tilaan: +Jotkin työkalut voivat saada mallin ”esittämään vastakysymyksen käyttäjälle”; tällöin malli lähettää `ask_user_question`-tapahtuman, ja keskustelu jäädytetään `awaiting_user_input`-tilaan: ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "你希望生成的报告是中文还是英文？", - "options": ["中文", "英文"], + "question": "Haluatko, että luotu raportti on kiinaksi vai englanniksi?", + "options": ["kiina", "englanti"], "id": "f2f4b3e8-..." } ``` -Renderöi tämä tapahtuma käyttöliittymässä kortiksi, josta käyttäjä voi valita vastauksen, ja tee sitten seuraava pyyntö samalla `id`:llä täyttämällä vastaus takaisin `tool_results`-kentän kautta: +Renderöi tämä tapahtuma käyttöliittymässä kortiksi, josta käyttäjä voi valita vastauksen, ja käynnistä sitten seuraava pyyntö samalla `id`:llä täyttämällä vastaus takaisin `tool_results`-kentän kautta: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Pyynnön rungossa olevan `tool_use_id`-arvon **täytyy** vastata täsmälleen keskeytyshetken `tool_id`-arvoa; jos ne eivät täsmää, palautetaan 400. Kun pyynnössä on samanaikaisesti `tool_results`, `question` / `message` / `references` jätetään kaikki huomiotta. +Pyynnön rungossa olevan `tool_use_id`-arvon **on** vastattava täsmälleen keskeytyshetken `tool_id`-arvoa; jos ne eivät vastaa toisiaan, palautetaan 400. Kun pyynnössä on samanaikaisesti `tool_results`, `question` / `message` / `references` jätetään kaikki huomiotta. Jos käyttäjä päättää luopua tästä kysymyksestä, välitä suoraan uusi `question` / `message`; alusta merkitsee keskeytetyn työkalukutsun automaattisesti tilaan ”käyttäjä ohitti”. -## Keskustelun hallinta (CRUD) - -v2 tarjoaa kevyen keskustelunhallinnan samalla endpointilla `action`-kentän kautta, eikä erillistä APIa tarvitse avata. +## Keskustelujen hallinta (CRUD) +v2 tarjoaa kevyen keskustelujen hallinnan samalla endpointilla `action`-kentän kautta ilman erillistä API:a. ### `action: retrieve` —— Hae keskustelu + ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Palauttaa täydellisen keskusteluasiakirjan (mukaan lukien `messages`-historia, `model`, `title`, `tools_used` jne.). +Palauttaa koko keskusteluasiakirjan (mukaan lukien `messages`-historia, `model`, `title`, `tools_used` jne.). -### `action: retrieve_batch` —— listaa keskustelujen yhteenvedot +### `action: retrieve_batch` —— Luettele keskustelujen yhteenvedot ```json { @@ -428,11 +428,11 @@ Palauttaa täydellisen keskusteluasiakirjan (mukaan lukien `messages`-historia, } ``` -Palauttaa `{ items: [...], total }`. **Yhteenveto ei sisällä `messages`-kenttää**, joten se soveltuu sivupalkkiluetteloksi; jos käyttäjä avaa tietyn keskustelun, hae sen täydelliset viestit erikseen käyttämällä `action: retrieve`. +Palauttaa `{ items: [...], total }`. **Yhteenveto ei sisällä `messages`-kenttää**, joten se soveltuu sivupalkin luetteloon; jos käyttäjä avaa keskustelun, hae sen täydelliset viestit erikseen käyttämällä `action: retrieve` -toimintoa. Valinnaiset suodatusparametrit: `user_id`, `application_id`, `model_group`, `model`. -### `action: update` —— muuta otsikkoa tai kirjoita historia uudelleen +### `action: update` —— Muuta otsikkoa tai kirjoita historia uudelleen ```json { @@ -442,9 +442,9 @@ Valinnaiset suodatusparametrit: `user_id`, `application_id`, `model_group`, `mod } ``` -Myös `messages` voidaan välittää, mutta palvelin suorittaa tiukan schema-validoinnin (sen on oltava tiivistetty `ToolUseContent`-muoto), ja virheellisestä muodosta palautetaan 400. Yleensä sitä suositellaan käytettäväksi vain `title`-kentän muuttamiseen. +Myös `messages` voidaan välittää, mutta palvelin suorittaa tiukan schema-validoinnin (sen on oltava tiivistetty `ToolUseContent`-muoto), ja vaatimustenvastaisesta palautetaan 400. Yleensä sitä suositellaan käytettäväksi vain `title`-kentän muuttamiseen. -### `action: delete` —— poista yksi keskustelu +### `action: delete` —— Poista keskustelu ```json { @@ -453,21 +453,21 @@ Myös `messages` voidaan välittää, mutta palvelin suorittaa tiukan schema-val } ``` -Palauttaa `{ id, success: true }`. Poistamisen jälkeen tietoja ei voi palauttaa, joten varmista ennen kutsua. +Palauttaa `{ id, success: true }`. Poistamisen jälkeen palautus ei ole mahdollista, joten varmista ennen kutsua. ## Sujuva siirtyminen v1:stä -Jos käytät jo [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations)-rajapintaa, siirtyminen v2:een ei vaadi juuri lainkaan koodimuutoksia: +Jos käytät jo [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) -rajapintaa, siirtyminen v2:een ei juuri vaadi koodimuutoksia: -1. Muuta URL-osoite `https://api.acedata.cloud/aichat/conversations` muotoon `https://api.acedata.cloud/aichat2/conversations`. -2. Jos välitit aiemmin v1-mallin nimen (kuten `gpt-3.5`, `gpt-4-browsing` jne.), v2:een vaihdettaessa suositellaan päivittämään nykyaikaisiin malleihin (kuten `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` jne.). -3. NDJSON-virran kentät säilyvät taaksepäin yhteensopivina: jokainen `text_delta`-tapahtuma sisältää edelleen `delta_answer`- ja `id`-kentät, joten asiakkaan, joka jäsentää aiemmin `delta_answer`-kentän riveittäin, ei tarvitse muuttua. +1. Vaihda URL-osoite `https://api.acedata.cloud/aichat/conversations` osoitteeksi `https://api.acedata.cloud/aichat2/conversations`. +2. Jos välitit aiemmin v1-mallin nimen (kuten `gpt-3.5`, `gpt-4-browsing` jne.), v2:een siirtyessä suositellaan päivittämistä nykyaikaiseen malliin (kuten `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` jne.). +3. NDJSON-virran kentät säilyvät taaksepäin yhteensopivina: jokainen `text_delta`-tapahtuma sisältää edelleen `delta_answer`- ja `id`-kentät, joten asiakkaat, jotka jäsentävät `delta_answer`-kentän riveittäin, eivät tarvitse muutoksia. -Siirtymisen jälkeen voit ottaa v2:n uudet ominaisuudet käyttöön tarpeen mukaan (monimuotoinen `message`, SSE, työkalukutsut, `action` CRUD) ja edetä omaan tahtiin. +Siirtymisen jälkeen voit ottaa käyttöön v2:n uusia ominaisuuksia tarpeen mukaan (multimodaalinen `message`, SSE, työkalukutsut, `action` CRUD) ja edetä omaan tahtiin. ## Virheenkäsittely -Virhevastaus on yhdenmukaisesti: +Virhevastaus on yhtenäisesti: ```json { @@ -481,14 +481,14 @@ Virhevastaus on yhdenmukaisesti: Yleiset virheet: -- `400 bad_request`: pakollisia kenttiä puuttuu, `tool_use_id` ei täsmää, `messages`-schema on virheellinen jne. +- `400 bad_request`: pakollinen kenttä puuttuu, `tool_use_id` ei täsmää, `messages`-schema on virheellinen jne. - `401 invalid_token`: `authorization`-otsake on virheellinen. -- `404 not_found`: `action: retrieve / update / delete` -toiminnossa `id`:tä vastaavaa keskustelua ei ole olemassa. -- `429 too_many_requests`: nopeusrajoitus on lauennut. -- `500 chat_error`: ylempi LLM palautti virheen tai tämän kierroksen `completion_tokens=0` (käsitellään kuluttamattomana, eikä siitä veloiteta). +- `404 not_found`: `action: retrieve / update / delete` -toimintoa käytettäessä `id`-kenttää vastaavaa keskustelua ei ole olemassa. +- `429 too_many_requests`: nopeusrajoitus on laukaistu. +- `500 chat_error`: ylävirran LLM raportoi virheen tai tämän kierroksen `completion_tokens=0` (käsitellään käyttämättömänä, eikä siitä veloiteta). -Virtausvastauksessa virhe lähetetään tapahtumana `{"type":"error","message":"..."}`, jonka jälkeen virta päättyy välittömästi. +Virtaavassa vastauksessa virhe lähetetään `{"type":"error","message":"..."}`-tapahtumana, minkä jälkeen virta päättyy välittömästi. ## Johtopäätös -AI Chat v2 API säilyttää v1:n taaksepäin yhteensopivuuden ja samalla päivittää keskustelut ”yhden / usean kierroksen kysymys-vastaus”-mallista ”Agent-pohjaisiksi, tarkkailtaviksi keskusteluiksi”: monimuotoinen syöte, työkalukutsut, keskeytettävä / jatkettava toiminta, virtaavat rakenteiset tapahtumat sekä sisäänrakennettu CRUD. Uusille integraatioille suositellaan v2:n käyttöä suoraan; olemassa olevat v1-integraatiot voidaan siirtää sujuvasti vaiheittain. Jos sinulla on kysyttävää, ota milloin tahansa yhteyttä tekniseen tukitiimiimme. +AI Chat v2 API säilyttää v1:n taaksepäin yhteensopivuuden ja samalla päivittää keskustelut ”yhden / usean kierroksen kysymys-vastaus”-mallista ”Agent-pohjaisiksi tarkkailtaviksi keskusteluiksi”: multimodaaliset syötteet, työkalukutsut, keskeytys / jatkaminen, virtaavat jäsennellyt tapahtumat ja sisäänrakennettu CRUD. Uusille integraatioille suositellaan suoraan v2:n käyttöä; olemassa olevat v1-integraatiot voidaan siirtää sujuvasti vaiheittain. Jos sinulla on kysyttävää, ota milloin tahansa yhteyttä tekniseen tukitiimiimme. diff --git a/fi/guides/platform/hermes_managed.mdx b/fi/guides/platform/hermes_managed.mdx index 8ebf2fc4f..42a6074e2 100644 --- a/fi/guides/platform/hermes_managed.mdx +++ b/fi/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Yksityinen käyttöönotto" +title: "Hermes-käyttöönotto" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud tarjoaa Hermes Agentin yksityisen käyttöönoton sisäänkäynnin. Tämä sisäänkäynti on hallittu palvelu, ja saatavuus sekä valittavat resurssit määräytyvät konsolin nykyisen näytön mukaan. +Luo jokaiselle Applicationille erillinen Hermes-kontti-instanssi. Oletusarvoisesti käytetään kiinteän julkaisuversion peruskuvaa ja alkuperäiset toiminnot säilytetään; alusta tarjoaa oston, uusimisen, pysyvän tallennustilan ja käyttöönoton hallinnan. -## Käyttöohjeet +## Luominen ja ostaminen -1. Etsi alustalta **Hermes Agent Yksityinen käyttöönotto**. -2. Valitse sivun ohjeiden mukaan käytettävissä olevat asetukset ja luo palvelu. -3. Odota, että alusta näyttää valmiustilan. -4. Käytä sivulla annettuja sisäänkäyntejä ja tunnistetietoja päästäksesi instanssiin. -5. Lähetä ensin `Reply only OK`, ja aloita sitten todellinen tehtävä. +1. Avaa [Hermes-käyttöönotto](https://platform.acedata.cloud/services/hermes) ja luo Application. +2. Valitse ostosivulla kestopaketti ja suorita maksu. +3. Palaa asetussivulle, valitse alustakeskustelumalli avattavasta luettelosta ja tarkastele nykyisen mallin hintaa. Alusta luo tälle instanssille erilliset API-tunnistetiedot; voit myös poistaa alustayhteyden käytöstä ja määrittää sen itse alkuperäisessä hallintapaneelissa. +4. Valitse automaattisesti luotavat käyttöoikeustiedot tai määritä oma vahva salasanasi/Tokenisi, ja käyttöönotto alkaa vahvistuksen jälkeen. Käyttöoikeustiedot ja mallin API-tunnistetiedot ovat toisistaan riippumattomia. +5. Kun instanssi on valmis, nouda hallintasivulta käyttöosoite ja kirjautumistiedot. +6. Kirjaudu alkuperäiseen hallintapaneeliin ja määritä omat mallintarjoajasi, avaimesi ja kanavasi. -Malli, tunnistetiedot, tallennus ja poistokäyttäytyminen määräytyvät luontisivun ja vahvistusikkunan mukaan; älä käytä paikallisen Hermes-opas YAML:ää suoraan alustakäyttösopimuksena. Vie ensin tarvittavat tiedot ennen poistamista. +Käyttöönottomaksu veloitetaan paketin keston mukaan, ja tarkka dollarihinta sekä kesto määräytyvät ostosivun mukaan. Mallikutsujen kustannukset veloitetaan erikseen; käyttöönottokeston ostaminen ei sisällä mallikiintiötä. Kun alustayhteys on käytössä, omat API-tunnistetiedot avaavat vain valittua mallia vastaavan keskustelurajapinnan, ja kutsut veloitetaan erikseen alustasaldostasi. Jokainen Application ostetaan, uusitaan ja hallitaan erikseen. -Jos konsoli ei näytä luontisisäänkäyntiä, se tarkoittaa, että nykyiselle tilille ei ole avattu tätä palvelua, voit käyttää [Hermes vuorovaikutusopasta](https://platform.acedata.cloud/documents/hermes-wizard-integration) tai [manuaalista konfigurointia](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Salasanat, tunnistetiedot ja myöhempi määritys + +Käyttöoikeustiedot asetetaan ennen ensimmäistä käynnistystä. Automaattisesti luotava tapa käyttää satunnaisia tunnistetietoja, mukautetun salasanan on oltava vähintään 16 merkkiä ja OpenClaw Tokenin vähintään 32 merkkiä. Luonnos ei tallenna salasanoja; sivua vaihdettaessa ne voidaan joutua syöttämään uudelleen. Käyttöönoton jälkeen vain Applicationin omistaja ja järjestelmänvalvojat voivat tarkastella käyttöoikeustietoja. + +Kunkin instanssin mallin API-tunnistetietoja ei käytetä uudelleen, niiden voimassaoloa jatketaan käyttöönoton uusimisen yhteydessä ja ne peruutetaan instanssia poistettaessa. Käyttöönoton alustamisen jälkeen muuta malleja ja kanavia alkuperäisessä hallintapaneelissa; jos vaihdat toisen palvelun malliin, säädä ensin vastaavan rajapinnan valtuutusta alustan tunnistetietojen hallinnassa tai käytä vastaavia tunnistetietoja. Tavallinen uudelleenkäyttöönotto ei korvaa alkuperäisiä asetuksia. Julkaisuvarmentamattomat käyttöönottaympäristöt hylkäävät tilapäisesti uudet käyttöönotot, ota yhteyttä tukeen. + +## Versiot ja tiedot + +Asetussivu näyttää tällä hetkellä julkaistun kuvaversion. Uudet instanssit käyttävät palvelun tällä hetkellä julkaistua versiota; olemassa olevia instansseja ei korvata automaattisesti luettelopäivitysten yhteydessä. Uudelleenkäyttöönotto ottaa käyttöön palvelun nykyisen version, varmuuskopioi ensin ja varmista käytetyn version päivitysvaatimukset. + +Jokaiselle instanssille tarjotaan oletusarvoisesti 1 CPU, 2 GiB:n muistiraja ja 10 GiB pysyvää tallennustilaa. Uudelleenkäynnistys säilyttää instanssin tiedot. Käyttöönoton aktiivinen poistaminen tai vanhentumisen jälkeinen takaisinotto poistaa tallennustilan, vie tarvittavat säilytettävät tiedot etukäteen. + +## Uusiminen ja vanhentuminen + +Uusi nykyinen Application ostosivulla, jolloin voimassaoloaikaa pidennetään alustan nykyisten kestosääntöjen mukaisesti. Vanhentumisen jälkeen käyttöosoite keskeytetään, ja uusiminen lisäajan aikana palauttaa käytön; lisäajan ylittäminen johtaa instanssin ja tietojen takaisinottoon. Noudata hallintasivun vanhentumisaikaa, laskutustilaa ja poistamisilmoituksia. + +## Kirjautuminen hallintakäyttöliittymään + +Kopioi käyttöönoton hallintasivulta Dashboard-osoite, käyttäjätunnus `admin` ja salasana, avaa osoite ja kirjaudu sisään. Kirjautumistiedot annetaan vain kyseisen Applicationin omistajalle ja alustan järjestelmänvalvojille. Mallit, taidot ja kanavat määritetään Hermesin alkuperäisessä käyttöliittymässä. + +## Usein kysytyt kysymykset + +- **Miksi uusi instanssi ei vielä voi vastata?** Käyttöönoton valmistuminen tarkoittaa, että kontti on valmis; malli ja tunnistetiedot on määritettävä alkuperäisessä käyttöliittymässä ennen käytön aloittamista. +- **Asennetaanko ylimääräisiä lisäosia tai mallin fallbackia valmiiksi?** Oletusarvoisesti niitä ei lisätä, määritä ne tarpeen mukaan alkuperäisessä käyttöliittymässä. +- **Miten olemassa oleva instanssi päivitetään?** Alkuperäinen Application ja tilaus säilytetään, ja uudelleenkäyttöönotossa käytetään palvelun nykyistä versiota; varmuuskopioi tiedot ja tarkista versiokompatibiliteetti ennen päivitystä. +- **Mitä tehdä, jos käynnistys epäonnistuu?** Tarkista ensin käyttöönoton lokit ja tapahtumat ja määritä malli vasta, kun instanssi on valmis. Älä paljasta instanssin salasanaa ja avaimia julkisissa kommenteissa tai kuvakaappauksissa. diff --git a/fi/guides/platform/wework_bot.mdx b/fi/guides/platform/wework_bot.mdx deleted file mode 100644 index d28cc15a5..000000000 --- a/fi/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/fr/guides/aichat/aichat2_conversations.mdx index 6f5f53831..e7c02c1e8 100644 --- a/fr/guides/aichat/aichat2_conversations.mdx +++ b/fr/guides/aichat/aichat2_conversations.mdx @@ -1,36 +1,36 @@ --- -title: "Guide d’intégration de l’API AI Chat v2" +title: "Instructions d’intégration de l’API AI Chat v2" description: "AI Dialogue API guide - Ace Data Cloud" --- -L’API AI Chat v2 (`/aichat2/conversations`) est une interface de conversation de nouvelle génération, représentant une mise à niveau complète de [l’API AI Chat](https://platform.acedata.cloud/documents/aichat-conversations). Sur la base de la simplicité de v1 et de la gestion hébergée des conversations multi-tours, elle étend : +L’API AI Chat v2 (`/aichat2/conversations`) est une interface de conversation de nouvelle génération et une version entièrement améliorée de [l’API AI Chat](https://platform.acedata.cloud/documents/aichat-conversations). En s’appuyant sur la simplicité de v1 et la gestion hébergée des conversations multi-tours, elle étend : -- **Entrées utilisateur multimodales** : envoyez directement des blocs de texte + images + fichiers via le champ `message` structuré, sans avoir à les joindre indirectement d’abord avec `references`. -- **Appel d’outils orienté Agent** : intègre un ensemble d’outils de recherche en ligne, de récupération de pages web, de lecture de fichiers, etc., et permet de monter des serveurs MCP autorisés par l’utilisateur (Google Drive, Notion, Slack, GitHub, etc.) ; le modèle peut appeler les outils de manière autonome sur plusieurs tours dans une seule requête pour accomplir des tâches complexes. -- **Événements de streaming structurés** : via `accept: text/event-stream` ou `application/x-ndjson`, vous pouvez obtenir des événements tels que `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact`, etc., token par token, facilitant leur rendu séparé selon le type côté frontend. -- **Interruptible / récupérable** : lorsque le modèle a besoin que l’utilisateur complète des informations, il émet un événement `ask_user_question` et se met en pause ; lors de l’appel suivant, il suffit de renseigner la réponse via `tool_results` pour continuer. -- **Nouvelles actions CRUD** : complétez `retrieve` / `retrieve_batch` / `update` / `delete` via le champ `action` sur le même endpoint, sans API supplémentaire de gestion des conversations. +- **Entrées utilisateur multimodales** : envoyez directement des blocs de texte + image + fichier via le champ `message` structuré, sans devoir d’abord les joindre indirectement avec `references`. +- **Appels d’outils orientés Agent** : intègre un ensemble d’outils de recherche en ligne, d’extraction de pages web, de lecture de fichiers, etc., et peut également connecter des serveurs MCP autorisés par l’utilisateur (Google Drive, Notion, Slack, GitHub, etc.) ; le modèle peut appeler les outils de manière autonome sur plusieurs tours au sein d’une seule requête afin d’accomplir des tâches complexes. +- **Événements de streaming structurés** : via `accept: text/event-stream` ou `application/x-ndjson`, vous pouvez obtenir des événements tels que `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact`, etc., token par token, facilitant leur rendu séparé par type dans le frontend. +- **Interrompable / reprenable** : lorsque le modèle a besoin que l’utilisateur fournisse des informations supplémentaires, il émet un événement `ask_user_question` et se met en pause ; lors de l’appel suivant, il suffit de renseigner la réponse via `tool_results` pour continuer. +- **Nouvelles actions CRUD** : effectuez `retrieve` / `retrieve_batch` / `update` / `delete` via le champ `action` sur le même endpoint, sans API supplémentaire de gestion des conversations. - **Liste de modèles continuellement mise à jour** : intègre par défaut des modèles contemporains tels que GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3, etc. -En même temps, au niveau du corps de requête, elle est **entièrement rétrocompatible avec v1** : il suffit d’envoyer `model` + `question` (+ `stateful` / `id` / `references` / `preset` optionnels) pour obtenir une réponse JSON `{answer, id}` équivalente à v1. Ainsi, aucune réécriture du client n’est nécessaire pour migrer depuis `/aichat/conversations` : il suffit de remplacer le chemin par `/aichat2/conversations`. +En même temps, au niveau du corps de la requête, elle est **entièrement rétrocompatible avec v1** : en envoyant seulement `model` + `question` (+ éventuellement `stateful` / `id` / `references` / `preset`), vous pouvez obtenir une réponse JSON `{answer, id}` équivalente à v1. Ainsi, une migration depuis `/aichat/conversations` ne nécessite pas de réécrire le client ; il suffit de remplacer le chemin par `/aichat2/conversations`. -> Si vous utilisez actuellement `/aichat/conversations`, l’ancienne interface restera disponible, et vous pouvez migrer à votre propre rythme. +> Si vous utilisez actuellement `/aichat/conversations`, l’ancienne interface continuera d’être maintenue ; vous pouvez migrer à votre propre rythme. ## Processus de demande -Pour utiliser l’API AI Chat v2, obtenez d’abord votre API Token dans la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications), et conservez-le en réserve. +Pour utiliser l’API AI Chat v2, rendez-vous d’abord sur la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) afin d’obtenir votre API Token, à conserver 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 pour vous inviter à vous inscrire et à vous connecter ; une fois cela fait, vous reviendrez automatiquement à la page actuelle. -**Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir à en demander un séparément pour chaque service.** Une demande initiale offre un crédit gratuit permettant une utilisation d’essai gratuite ; lorsque le crédit est insuffisant, vous pouvez recharger le solde commun depuis 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.** Une demande initiale offre un crédit gratuit permettant de tester le service gratuitement ; lorsque le crédit est insuffisant, vous pouvez recharger votre solde universel dans la [console](https://platform.acedata.cloud/console/coin). > 📘 Documentation complète : [API AI Chat v2 →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Utilisation de base -L’utilisation la plus simple est exactement la même que v1 : envoyez `model` + `question`, et obtenez `{answer, id}`. +L’utilisation la plus simple est exactement la même que pour v1 : envoyez `model` + `question`, et obtenez `{answer, id}`. Exemple CURL : @@ -41,7 +41,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-5.4", - "question": "用一句话介绍下 AceDataCloud。" + "question": "Présentez AceDataCloud en une phrase." }' ``` @@ -49,7 +49,7 @@ Résultat retourné : ```json { - "answer": "AceDataCloud 是一个聚合主流 AI 模型与多模态服务的统一 API 平台，开发者通过一个密钥即可调用 GPT、Claude、Gemini、Midjourney、Suno、Veo 等多家服务。", + "answer": "AceDataCloud est une plateforme d’API unifiée regroupant les principaux modèles d’IA et services multimodaux, permettant aux développeurs d’appeler des services tels que GPT, Claude, Gemini, Midjourney, Suno et Veo à l’aide d’une seule clé.", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` @@ -69,14 +69,14 @@ headers = { payload = { "model": "gpt-5.4", - "question": "用一句话介绍下 AceDataCloud。", + "question": "Présentez AceDataCloud en une phrase.", } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Les valeurs `model` disponibles peuvent être visualisées directement dans la liste déroulante du panneau Try à droite ; les catégories courantes incluent : +Les valeurs `model` disponibles peuvent être consultées directement dans la liste déroulante du panneau Try à droite ; les catégories courantes comprennent : - OpenAI : `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini`, etc. - Anthropic : `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`, etc. @@ -90,7 +90,7 @@ Pour les règles de tarification spécifiques, consultez la carte Pricing sur la ## Conversation multi-tours -Comme avec v1, envoyez `stateful: true` pour activer la sauvegarde de la conversation ; l’API renverra un `id` ; il suffit de renvoyer cet `id` dans les requêtes ultérieures pour continuer la conversation, sans devoir maintenir vous-même l’historique des messages. +Comme avec v1, envoyez `stateful: true` pour activer la sauvegarde de la conversation ; l’API retourne un `id` ; il suffit de renvoyer cet `id` dans les requêtes suivantes pour continuer la conversation, sans devoir maintenir vous-même l’historique des messages. Première requête : @@ -102,7 +102,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -d '{ "model": "gpt-5.4", "stateful": true, - "question": "记住一个数字：42。" + "question": "Souvenez-vous d’un nombre : 42." }' ``` @@ -110,7 +110,7 @@ Retour : ```json { - "answer": "好的，我已经记住了 42。需要我用它做什么吗？", + "answer": "D’accord, je me souviens déjà de 42. Que souhaitez-vous que j’en fasse ?", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` @@ -136,7 +136,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful` vaut par défaut `true` ; l’omettre est équivalent à transmettre explicitement `true`. Si vous ne souhaitez pas que le serveur enregistre ce tour de conversation, vous pouvez définir explicitement `stateful: false`. +> `stateful` est défini sur `true` par défaut ; l’omettre est équivalent à transmettre explicitement `true`. Si vous ne souhaitez pas que le serveur enregistre ce tour de conversation, vous pouvez définir explicitement `stateful: false`. ## Réponse en streaming @@ -144,9 +144,9 @@ v2 prend en charge deux formats de streaming, sélectionnés selon l’en-tête | Scénario | `accept` | Format des données | | --------------------- | ---------------------- | ------------------------------------------ | -| Frontend Web / EventSource | `text/event-stream` | `data: {json}\n\n`, avec pour dernière ligne `data: [DONE]\n\n` | +| Frontend Web / EventSource | `text/event-stream` | `data: {json}\n\n`, avec comme dernière ligne `data: [DONE]\n\n` | | Serveur / CLI / analyse de flux Node | `application/x-ndjson` | Un objet JSON par ligne | -| Pas besoin de streaming | `application/json`（par défaut） | Retour unique de `{answer, id}` | +| Streaming non requis | `application/json`（par défaut） | Retourne `{answer, id}` en une seule fois | ### Exemple NDJSON @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -Chaque ligne de NDJSON est un événement structuré, le plus courant étant `text_delta` : +Chaque ligne NDJSON est un événement structuré, le plus courant étant `text_delta` : ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +195,7 @@ Chaque ligne de NDJSON est un événement structuré, le plus courant étant `te ### Exemple SSE -L’utilisation de `EventSource` côté navigateur ne prend pas en charge les corps de requête personnalisés ; il est recommandé d’utiliser `fetch` + une analyse manuelle par segments `\n\n` : +L’utilisation de `EventSource` côté navigateur ne prend pas en charge les corps de requête personnalisés ; il est recommandé d’utiliser `fetch` + une analyse manuelle par découpage sur `\n\n` : ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,20 +236,20 @@ while (true) { | `type` | Signification | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Fragment de texte incrémentiel de la réponse de l’assistant. `content` contient le nouveau contenu ; pour la compatibilité avec v1, le même événement porte également `delta_answer` (égal à `content`) et `id`. | +| `text_delta` | Fragment de texte incrémentiel de la réponse de l’assistant. `content` correspond au nouveau contenu ; pour la compatibilité avec v1, le même événement contient également `delta_answer` (égal à `content`) et `id`. | | `thinking` | Processus de réflexion du modèle (apparaît uniquement lorsque le modèle sélectionné expose le raisonnement). | | `tool_use` | Le modèle décide d’appeler un outil ; l’événement contient `tool_id`, `tool_name`, `input`. | -| `tool_result` | Résultat de l’exécution de l’outil, associé au `tool_use` précédent via `tool_id` ; `is_error` indique si l’exécution a échoué. | -| `card` | Carte structurée produite par un outil (comme une image ou un aperçu de lien), adaptée au rendu direct. | -| `citation` | URL source utilisée pour compléter la référence du fragment de texte correspondant. | -| `ask_user_question` | Émis lorsque le modèle a besoin que l’utilisateur fournisse des informations supplémentaires ; la conversation entre dans l’état `awaiting_user_input`. Voir [Reprendre une conversation en pause](#恢复暂停的对话) ci-dessous. | -| `artifact` | Production indépendante générée par le modèle (comme un bloc de code ou un document), pouvant être enregistrée ou téléchargée. | -| `system_message` | Message d’information système (n’appartenant ni à l’utilisateur ni à l’assistant), utilisé uniquement pour les indications d’interface. | -| `compact` | Événement indiquant que le contexte interne a été compressé, sans traitement particulier requis. | -| `error` | Une erreur est survenue pendant ce tour ; `message` décrit le contenu de l’erreur. | -| `done` | La réponse en streaming est terminée ; elle contient `usage` (incluant `prompt_tokens` / `completion_tokens` / `total_tokens`) et `terminal_reason`. | - -Pour les clients qui ne s’intéressent qu’à la réponse finale, concaténer le `content` de tous les `text_delta` est équivalent à `answer` en mode `application/json`. +| `tool_result` | Résultat de l’exécution de l’outil, associé au `tool_use` précédent via `tool_id` ; `is_error` indique s’il a échoué. | +| `card` | Carte structurée produite par un outil (par exemple une image, un aperçu de lien), adaptée à un rendu direct. | +| `citation` | URL source utilisée pour compléter les citations du fragment de texte correspondant. | +| `ask_user_question` | Émis lorsque le modèle a besoin que l’utilisateur fournisse des informations supplémentaires ; la conversation entre dans l’état `awaiting_user_input`, voir [Reprendre une conversation suspendue](#恢复暂停的对话) ci-dessous. | +| `artifact` | Produit indépendant généré par le modèle (par exemple un bloc de code, un document), pouvant être enregistré ou téléchargé. | +| `system_message` | Message d’invite système (ni contenu utilisateur ni contenu assistant), utilisé uniquement pour les indications de l’interface utilisateur. | +| `compact` | Événement indiquant que le contexte interne a été compressé, ne nécessitant aucun traitement particulier. | +| `error` | Une erreur est survenue durant ce tour ; `message` décrit le contenu de l’erreur. | +| `done` | La réponse en streaming est terminée ; contient `usage` (avec `prompt_tokens` / `completion_tokens` / `total_tokens`) et `terminal_reason`. | + +Pour les clients qui ne s’intéressent qu’à la réponse finale, concaténer les `content` de tous les `text_delta` est équivalent à `answer` en mode `application/json`. ## Entrée multimodale @@ -268,30 +268,30 @@ Si l’entrée utilisateur contient des images ou des fichiers, transmettez `mes Types de blocs pris en charge : -- `text` — Texte normal, champ `text` obligatoire. +- `text` — Texte ordinaire, champ `text` obligatoire. - `image_url` — Image, champ `image_url.url` obligatoire. - `file_url` — Fichier (PDF, CSV, TXT, etc.), champ `file_url.url` obligatoire. -### Relation avec les `references` de v1 +### Relation avec `references` de v1 -Pour assurer la compatibilité avec les anciens clients, v2 reconnaît toujours le champ `references: ["https://...", ...]` : -- Si le suffixe de l’URL est `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, le convertir automatiquement en bloc `image_url` ; -- Convertir les autres extensions en bloc `file_url` ; -- Si un `question` est également fourni, le placer en tête sous forme de bloc `text`. +Afin d’assurer la compatibilité avec les anciens clients, v2 reconnaît toujours le champ `references: ["https://...", ...]` : +- Les suffixes d’URL sont `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, convertis automatiquement en blocs `image_url` ; +- Les autres extensions sont converties en blocs `file_url` ; +- Si un `question` est également fourni, il est alors placé en tête en tant que bloc `text`. -Ainsi, si vous voulez seulement migrer depuis v1 sans modifier le corps de la requête, il suffit de remplacer le chemin par `/aichat2/conversations`, et l’utilisation originale de `references` continuera de fonctionner normalement. +Par conséquent, si vous souhaitez uniquement migrer depuis v1 sans modifier le corps de la requête, remplacez simplement le chemin par `/aichat2/conversations`, et l’usage original de `references` continuera de fonctionner normalement. -Si vous avez besoin d’un contrôle plus précis (par exemple, placer plusieurs images entre des textes, ou si l’ordre est important), utilisez directement le tableau `message`. +Si vous avez besoin d’un contrôle plus précis (par exemple, placer plusieurs images entre des textes, ou si l’ordre est très important), utilisez directement le tableau `message`. ## Appels d’outils et MCP -L’amélioration principale de v2 est que le modèle peut appeler des outils de manière autonome pour accomplir des tâches en plusieurs étapes, **c’est activé par défaut**, sans qu’aucune configuration supplémentaire ne soit nécessaire côté client dans la requête. Cas d’usage courants : +L’amélioration principale de v2 est que le modèle peut appeler lui-même des outils afin d’accomplir des tâches en plusieurs étapes, **cela est activé par défaut**, et ne nécessite aucune configuration supplémentaire du client dans la requête. Scénarios courants : -- L’utilisateur demande « Aidez-moi à rechercher les nouvelles expositions récentes à Shanghai » → le modèle appelle la recherche web intégrée → organise les résultats dans une réponse. -- L’utilisateur demande « Lisez ce PDF puis rédigez un résumé » → le modèle appelle file_read → rédige le résumé. -- L’utilisateur a autorisé Google Drive / GitHub / Notion, etc. dans [Connections](https://platform.acedata.cloud/connections) → le modèle peut appeler les outils MCP correspondants pour lire et écrire leurs données. +- L’utilisateur demande « Aidez-moi à chercher quelles nouvelles expositions sont prévues récemment à Shanghai » → Le modèle appelle la recherche web intégrée → Il organise les résultats en réponse. +- L’utilisateur demande « Lisez ce PDF puis rédigez un résumé » → Le modèle appelle file_read → Il rédige un résumé. +- L’utilisateur a déjà autorisé Google Drive / GitHub / Notion, etc. dans [Connections](https://platform.acedata.cloud/connections) → Le modèle peut appeler les outils MCP correspondants pour lire et écrire leurs données. -Dans les flux NDJSON / SSE, les appels d’outils sont représentés par deux types d’événements, `tool_use` et `tool_result`, par exemple : +Dans le flux NDJSON / SSE, les appels d’outils sont présentés par deux types d’événements, `tool_use` et `tool_result`, par exemple : ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,13 +301,13 @@ Dans les flux NDJSON / SSE, les appels d’outils sont représentés par deux ty ... ``` -Si vous ne souhaitez pas afficher les détails des appels d’outils dans le frontend, ignorez simplement les types d’événements `tool_use` / `tool_result` / `card` / `citation`, la sortie finale du modèle continuera d’être diffusée via `text_delta`. +Si vous ne souhaitez pas afficher les détails des appels d’outils dans le frontend, ignorez simplement les événements de type `tool_use` / `tool_result` / `card` / `citation`, la sortie finale du modèle continuera d’être diffusée via `text_delta`. -`max_turns` peut limiter le nombre maximal de tours pendant lesquels le modèle peut s’appeler lui-même via des outils dans cette requête, la limite par défaut étant déterminée par la plateforme. Le définir à une faible valeur (par exemple `max_turns: 1`) permet de forcer une réponse unique et d’interdire tout appel d’outil. +`max_turns` peut limiter le nombre maximal de cycles d’auto-appel d’outils du modèle dans cette requête, avec une plage de 1 à 500, et la valeur par défaut est 500 lorsqu’il est omis. Le définir à une petite valeur (par exemple `max_turns: 1`) peut forcer une réponse unique et n’autoriser aucun appel d’outil. ## Exécution asynchrone et autorisation sans supervision -Si votre appel provient d’un Webhook d’alerte, d’un CI/CD, d’un système de surveillance ou d’une autre tâche en arrière-plan, vous pouvez définir `async: true` afin que l’interface retourne immédiatement un ID de tâche et poursuive l’exécution en arrière-plan : +Si votre appel provient d’un Webhook d’alerte, d’un CI/CD, d’un système de surveillance ou d’une autre tâche en arrière-plan, vous pouvez définir `async: true` afin que l’interface renvoie immédiatement l’ID de la tâche et poursuive l’exécution en arrière-plan : ```json { @@ -328,9 +328,9 @@ Exemple de retour : } ``` -Vous pouvez ensuite utiliser `action: retrieve` + `id` pour consulter le résultat de la conversation ; vous pouvez aussi fournir un `callback_url`, et lorsque la tâche est terminée, la plateforme enverra `{ status, answer, usage, error }` en POST à votre adresse de rappel. `callback_url` doit utiliser `http` / `https`, et ne peut pas indiquer directement `localhost` ou une adresse IP privée littérale. +Vous pouvez ensuite utiliser `action: retrieve` + `id` pour consulter le résultat de la conversation ; vous pouvez également fournir `callback_url`, et une fois la tâche terminée, la plateforme enverra `{ status, answer, usage, error }` par POST à votre adresse de rappel. `callback_url` doit utiliser `http` / `https`, et ne peut pas indiquer directement `localhost` ou une adresse IP privée littérale. -Les tâches en arrière-plan n’ont généralement personne pour cliquer afin de confirmer. Si vous souhaitez que certains Skill ou MCP Server effectuent des actions telles que l’envoi, la publication ou l’écriture en mode sans supervision, transmettez explicitement une liste de préautorisations dans le corps de la requête : +Les tâches en arrière-plan ne disposent généralement de personne pour cliquer sur une confirmation. Si vous souhaitez que certains Skill ou MCP Server exécutent des actions d’envoi, de publication, d’écriture, etc. en mode sans supervision, transmettez explicitement une liste de préautorisation dans le corps de la requête : ```json { @@ -342,7 +342,7 @@ Les tâches en arrière-plan n’ont généralement personne pour cliquer afin d } ``` -Les valeurs dans `allowed_skills` sont les slugs des Skill connectés ; les valeurs dans `allowed_mcp_servers` sont les slugs des MCP Server connectés. Les Skill / MCP Server non inclus dans la préautorisation ne peuvent toujours qu’afficher un aperçu, effectuer un dry-run ou refuser d’exécuter des opérations d’écriture en mode sans supervision. +Les valeurs dans `allowed_skills` sont les slugs des Skill connectés ; les valeurs dans `allowed_mcp_servers` sont les slugs des MCP Server connectés. Les Skill / MCP Server non inclus dans la préautorisation ne peuvent toujours qu’afficher un aperçu, effectuer un dry-run ou refuser les opérations d’écriture en mode sans supervision. Si un contrôle plus fin est nécessaire, vous pouvez également utiliser l’objet `unattended_policy` équivalent : @@ -356,13 +356,13 @@ Si un contrôle plus fin est nécessaire, vous pouvez également utiliser l’ob } ``` -La préautorisation correspond à ces deux listes elles-mêmes : une liste vide signifie qu’aucune capacité n’est autorisée, sans nécessiter de champ d’activation supplémentaire. +La préautorisation correspond à ces deux listes elles-mêmes : une liste vide n’autorise aucune capacité, aucun champ d’activation supplémentaire n’est nécessaire. -Attention : la préautorisation signifie uniquement que « cette requête autorise ces capacités à ignorer la confirmation humaine en mode sans supervision ». Le Skill concerné doit toujours prendre en charge `--unattended-confirm` ou le mécanisme de sécurité correspondant ; sinon, il continuera à effectuer un dry-run et n’exécutera pas directement les opérations d’écriture. +Remarque : la préautorisation signifie uniquement que « cette requête autorise ces capacités à ignorer la confirmation humaine en mode sans supervision ». Le Skill spécifique doit toujours prendre en charge `--unattended-confirm` ou le mécanisme de sécurité correspondant ; sinon, il continuera en dry-run et n’exécutera pas directement les opérations d’écriture. -## Reprendre une conversation suspendue +## Reprendre les conversations suspendues -Certains outils amènent le modèle à « poser une question à l’utilisateur ». Le modèle émet alors un événement `ask_user_question`, et la conversation est gelée dans l’état `awaiting_user_input` : +Certains outils peuvent amener le modèle à « poser une question à l’utilisateur » ; le modèle émet alors un événement `ask_user_question`, et la conversation est gelée dans l’état `awaiting_user_input` : ```json { @@ -375,7 +375,7 @@ Certains outils amènent le modèle à « poser une question à l’utilisateur } ``` -Dans le frontend, rendez cet événement sous forme de carte afin que l’utilisateur puisse choisir une réponse, puis lancez la requête suivante avec le même `id`, en renseignant la réponse via `tool_results` : +Dans le frontend, affichez cet événement sous forme de carte afin que l’utilisateur puisse choisir une réponse, puis lancez la requête suivante avec le même `id`, en renseignant la réponse via `tool_results` : ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Le `tool_use_id` dans le corps de la requête **doit** être exactement identique au `tool_id` au moment de la suspension ; sinon, une erreur 400 sera renvoyée. Lorsque `tool_results` est présent dans la requête, `question` / `message` / `references` sont tous ignorés. +Le `tool_use_id` dans le corps de la requête **doit** être exactement identique au `tool_id` au moment de la suspension ; dans le cas contraire, une erreur 400 sera renvoyée. Lorsque `tool_results` est présent dans la requête, `question` / `message` / `references` seront tous ignorés. Si l’utilisateur décide d’abandonner cette question, transmettez directement un nouveau `question` / `message`, et la plateforme marquera automatiquement l’appel d’outil suspendu comme « ignoré par l’utilisateur ». ## Gestion des conversations (CRUD) v2 fournit une gestion légère des conversations via le champ `action` sur le même endpoint, sans nécessiter d’API supplémentaire. - ### `action: retrieve` —— Récupérer une conversation + ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -417,7 +417,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ Renvoie le document complet de la conversation (y compris l’historique `messages`, `model`, `title`, `tools_used`, etc.). -### `action: retrieve_batch` —— Lister les résumés de conversations +### `action: retrieve_batch` —— Lister les résumés des conversations ```json { @@ -428,9 +428,9 @@ Renvoie le document complet de la conversation (y compris l’historique `messag } ``` -Renvoie `{ items: [...], total }`. **Les résumés ne contiennent pas `messages`**, ce qui convient à une liste dans la barre latérale ; si l’utilisateur ouvre une conversation, utilisez ensuite `action: retrieve` pour récupérer séparément ses messages complets. +Renvoie `{ items: [...], total }`. **Les résumés ne contiennent pas `messages`**, ils conviennent pour créer une liste dans la barre latérale ; si l’utilisateur ouvre une conversation, utilisez ensuite `action: retrieve` pour récupérer séparément ses messages complets. -Paramètres de filtrage optionnels : `user_id`, `application_id`, `model_group`, `model`. +Paramètres de filtrage facultatifs : `user_id`, `application_id`, `model_group`, `model`. ### `action: update` —— Modifier le titre ou réécrire l’historique @@ -442,7 +442,7 @@ Paramètres de filtrage optionnels : `user_id`, `application_id`, `model_group`, } ``` -`messages` peut également être transmis, mais le serveur effectuera une validation stricte du schéma (il doit être sous la forme `ToolUseContent` repliée) ; en cas de non-conformité, une erreur 400 sera renvoyée. En général, il est recommandé de l’utiliser uniquement pour modifier `title`. +`messages` peut également être transmis, mais le serveur effectue une validation stricte du schéma (il doit obligatoirement être sous la forme `ToolUseContent` repliée) ; sinon, une erreur 400 sera renvoyée. En général, il est recommandé de l’utiliser uniquement pour modifier `title`. ### `action: delete` —— Supprimer une conversation @@ -455,19 +455,19 @@ Paramètres de filtrage optionnels : `user_id`, `application_id`, `model_group`, Renvoie `{ id, success: true }`. La suppression est irréversible, veuillez confirmer avant d’appeler cette action. -## Migrer en douceur depuis v1 +## Migration fluide depuis v1 -Si vous utilisez déjà [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), la migration vers v2 ne nécessite pratiquement aucune modification de code : +Si vous utilisez déjà [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), la migration vers v2 ne nécessite pratiquement aucune modification du code : 1. Remplacez l’URL `https://api.acedata.cloud/aichat/conversations` par `https://api.acedata.cloud/aichat2/conversations`. -2. Si vous transmettiez auparavant des noms de modèles v1 (tels que `gpt-3.5`, `gpt-4-browsing`, etc.), il est recommandé de passer à des modèles contemporains lors du passage à v2 (tels que `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview`, etc.). -3. Les champs du flux NDJSON restent rétrocompatibles : chaque événement `text_delta` contient toujours `delta_answer` et `id`, de sorte que les clients existants qui analysent `delta_answer` ligne par ligne n’ont pas besoin d’être modifiés. +2. Si vous transmettiez auparavant des noms de modèles v1 (tels que `gpt-3.5`, `gpt-4-browsing`, etc.), il est recommandé de passer à des modèles contemporains lors du basculement vers v2 (tels que `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview`, etc.). +3. Les champs du flux NDJSON restent rétrocompatibles : chaque événement `text_delta` contient toujours `delta_answer` et `id`, les clients qui analysaient auparavant `delta_answer` ligne par ligne ne nécessitent donc aucune modification. -Après la migration, vous pouvez activer selon vos besoins les nouvelles capacités de v2 (`message` multimodal, SSE, appels d’outils, CRUD `action`) et progresser à votre rythme. +Après la migration, vous pouvez activer selon vos besoins les nouvelles fonctionnalités de v2 (`message` multimodal, SSE, appels d’outils, CRUD `action`) et progresser à votre rythme. ## Gestion des erreurs -Les réponses d’erreur suivent toutes ce format : +Les réponses d’erreur sont uniformisées comme suit : ```json { @@ -481,14 +481,14 @@ Les réponses d’erreur suivent toutes ce format : Erreurs courantes : -- `400 bad_request` : champ obligatoire manquant, `tool_use_id` non correspondant, schéma `messages` invalide, etc. +- `400 bad_request` : champs obligatoires manquants, incompatibilité de `tool_use_id`, schéma `messages` invalide, etc. - `401 invalid_token` : l’en-tête `authorization` est incorrect. - `404 not_found` : la conversation correspondant à `id` n’existe pas lors de `action: retrieve / update / delete`. - `429 too_many_requests` : la limite de débit a été déclenchée. - `500 chat_error` : erreur du LLM en amont ou `completion_tokens=0` pour ce tour (traité comme non consommé, aucun frais ne sera facturé). -Dans les réponses en streaming, les erreurs sont émises sous forme d’événements `{"type":"error","message":"..."}`, après quoi le flux se termine immédiatement. +Dans les réponses en flux, les erreurs sont émises sous forme d’événement `{"type":"error","message":"..."}`, puis le flux se termine immédiatement. ## Conclusion -Tout en restant rétrocompatible avec v1, l’API AI Chat v2 fait évoluer les conversations de « questions-réponses à un ou plusieurs tours » vers des « conversations observables orientées Agent » : entrées multimodales, appels d’outils, interruption / reprise, événements structurés en streaming, CRUD intégré. Il est recommandé d’utiliser directement v2 pour les nouvelles intégrations ; les intégrations v1 existantes peuvent migrer progressivement par étapes. Pour toute question, n’hésitez pas à contacter notre équipe de support technique. +Tout en restant rétrocompatible avec v1, l’API AI Chat v2 fait évoluer les conversations de « questions-réponses à un tour / plusieurs tours » vers des « conversations observables orientées Agent » : entrées multimodales, appels d’outils, mise en pause / reprise, événements structurés en flux, CRUD intégré. Il est recommandé aux nouvelles intégrations d’utiliser directement v2 ; les intégrations v1 existantes peuvent migrer progressivement par étapes. Pour toute question, n’hésitez pas à contacter notre équipe de support technique. diff --git a/fr/guides/platform/hermes_managed.mdx b/fr/guides/platform/hermes_managed.mdx index c6b4f77f1..ea18e7afa 100644 --- a/fr/guides/platform/hermes_managed.mdx +++ b/fr/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Déploiement privé de l'Agent Hermes" +title: "Déploiement Hermes" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud propose un accès au déploiement privé de l'Agent Hermes. Cet accès est un service contrôlé, la disponibilité et les ressources optionnelles sont conformes à ce qui est actuellement affiché dans la console. +Créer une instance de conteneur Hermes indépendante pour chaque Application. Utilise par défaut une image de base d’une version publiée fixe, en conservant les fonctionnalités natives ; la plateforme fournit l’achat, le renouvellement, le stockage persistant et la gestion du déploiement. -## Étapes d'utilisation +## Création et achat -1. Trouvez **Déploiement privé de l'Agent Hermes** sur la plateforme. -2. Sélectionnez la configuration disponible et créez le service selon les indications de la page. -3. Attendez que la plateforme affiche l'état prêt. -4. Accédez à l'instance en utilisant l'entrée et les identifiants fournis sur la page. -5. Envoyez d'abord `Reply only OK`, puis commencez la tâche réelle. +1. Ouvrez [Déploiement Hermes](https://platform.acedata.cloud/services/hermes) et créez une Application. +2. Sélectionnez une formule de durée sur la page d’achat et terminez le paiement. +3. Retournez à la page de configuration, où vous pouvez sélectionner un modèle de chat de la plateforme dans la liste déroulante et consulter le prix actuel du modèle. La plateforme créera des identifiants API indépendants pour cette instance ; vous pouvez également désactiver l’accès à la plateforme et effectuer vous-même la configuration dans la console native. +4. Choisissez de générer automatiquement des identifiants d’accès, ou définissez votre propre mot de passe/Token fort, puis confirmez pour démarrer le déploiement. Les identifiants d’accès et les identifiants API du modèle sont indépendants les uns des autres. +5. Une fois l’instance prête, récupérez l’adresse d’accès et les identifiants de connexion depuis la page de gestion. +6. Connectez-vous à la console native et configurez vos propres fournisseurs de modèles, clés et canaux. -Les modèles, identifiants, comportements de stockage et de suppression sont conformes à la page de création et à la fenêtre de confirmation ; ne considérez pas le YAML du tutoriel local Hermes comme un contrat de déploiement sur la plateforme. Exportez d'abord les données à conserver avant de supprimer. +Les frais de déploiement sont facturés selon la durée de la formule ; les prix précis en dollars américains et les durées prévalent selon la page d’achat. Les frais d’appel de modèle sont facturés séparément ; l’achat d’une durée de déploiement n’offre pas de crédits de modèle. Lorsque l’accès à la plateforme est activé, les identifiants API dédiés n’ouvrent que l’interface de chat correspondant au modèle sélectionné, et les appels sont facturés séparément sur le solde de votre plateforme. Chaque Application est achetée, renouvelée et gérée séparément. -Si la console n'affiche pas l'entrée de création, cela signifie que le compte actuel n'a pas encore accès à ce service, vous pouvez utiliser [l'assistant interactif Hermes](https://platform.acedata.cloud/documents/hermes-wizard-integration) ou [la configuration manuelle](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Mots de passe, identifiants et configuration ultérieure + +Les identifiants d’accès sont définis avant le premier démarrage. La génération automatique utilise des identifiants aléatoires, le mot de passe personnalisé comporte au moins 16 caractères, et le Token OpenClaw au moins 32 caractères. Les brouillons n’enregistrent pas les mots de passe ; il peut être nécessaire de les saisir à nouveau après un changement de page. Après le déploiement, seuls le propriétaire et les administrateurs de l’Application peuvent consulter les identifiants d’accès. + +Les identifiants API de modèle de chaque instance ne sont pas réutilisés, leur validité est prolongée avec le renouvellement du déploiement, et ils sont révoqués lors de la suppression de l’instance. Après l’initialisation du déploiement, veuillez modifier les modèles et les canaux dans la console native ; si vous choisissez plutôt le modèle d’un autre service, ajustez d’abord l’autorisation de l’interface correspondante dans la gestion des identifiants de la plateforme, ou utilisez les identifiants correspondants. Un redéploiement ordinaire n’écrasera pas les paramètres natifs. Les environnements de déploiement non validés pour la publication refuseront temporairement les nouveaux déploiements ; veuillez contacter le support. + +## Version et données + +La page de configuration affiche la version d’image actuellement publiée. Les nouvelles instances utilisent la version actuellement publiée du service ; les instances existantes ne sont pas automatiquement remplacées avec les mises à jour du catalogue. Le redéploiement appliquera la version actuelle du service ; veuillez d’abord effectuer une sauvegarde et confirmer les exigences de mise à niveau de la version utilisée. + +Chaque instance fournit par défaut 1 CPU, une limite de 2 GiB de mémoire et 10 GiB de stockage persistant. Les redémarrages conservent les données de l’instance. La suppression active du déploiement ou la récupération à l’expiration supprimera le stockage ; veuillez exporter à l’avance les données devant être conservées. + +## Renouvellement et expiration + +Renouvelez sur la page d’achat de l’Application actuelle ; la période de validité est prolongée selon les règles de durée existantes de la plateforme. Après expiration, le point d’accès est suspendu, et un renouvellement pendant la période de grâce rétablit l’accès ; après la période de grâce, l’instance et les données seront récupérées. Référez-vous à la date d’expiration, à l’état de facturation et aux indications de suppression sur la page de gestion. + +## Connexion à l’interface de gestion + +Sur la page de gestion du déploiement, copiez l’adresse Dashboard, le nom d’utilisateur `admin` et le mot de passe, puis ouvrez-la pour vous connecter. Les informations de connexion sont fournies uniquement au propriétaire de cette Application et aux administrateurs de la plateforme. Les modèles, compétences et canaux sont configurés dans l’interface native de Hermes. + +## Questions fréquentes + +- **Pourquoi la nouvelle instance ne peut-elle pas encore répondre ?** La fin du déploiement signifie que le conteneur est prêt ; vous devez configurer les modèles et les identifiants dans l’interface native avant de pouvoir commencer à l’utiliser. +- **Des plugins supplémentaires ou un fallback de modèle sont-ils préinstallés ?** Aucun n’est ajouté par défaut ; configurez-les selon vos besoins dans l’interface native. +- **Comment mettre à jour une instance existante ?** L’Application et la commande d’origine sont conservées, et la version actuelle du service est utilisée lors du redéploiement ; sauvegardez d’abord les données et vérifiez la compatibilité des versions avant la mise à niveau. +- **Que faire en cas d’échec du démarrage ?** Consultez d’abord les journaux et les événements du déploiement, puis configurez le modèle après avoir confirmé que l’instance est prête. N’exposez pas le mot de passe et les clés de l’instance dans des commentaires publics ou des captures d’écran. diff --git a/fr/guides/platform/wework_bot.mdx b/fr/guides/platform/wework_bot.mdx deleted file mode 100644 index a7b44a1b6..000000000 --- a/fr/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/it/guides/aichat/aichat2_conversations.mdx index 37868db25..fcf0a183a 100644 --- a/it/guides/aichat/aichat2_conversations.mdx +++ b/it/guides/aichat/aichat2_conversations.mdx @@ -1,36 +1,36 @@ --- -title: "Istruzioni di integrazione dell'API AI Chat v2" +title: "Documentazione di integrazione dell'API AI Chat v2" description: "AI Dialogue API guide - Ace Data Cloud" --- -L'API AI Chat v2 (`/aichat2/conversations`) è l'interfaccia di conversazione di nuova generazione, una versione completamente aggiornata della [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Sulla base della semplicità di v1 e della gestione delle conversazioni multi-turno, espande: +L'API AI Chat v2 (`/aichat2/conversations`) è l'interfaccia di conversazione di nuova generazione, una versione completamente aggiornata della [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Sulla base della semplicità di v1 e della gestione delle conversazioni multi-turn, estende: -- **Input utente multimodale**: attraverso il campo strutturato `message` è possibile inviare direttamente blocchi di testo + immagini + file, senza doverli prima allegare indirettamente tramite `references`. -- **Chiamate di strumenti agentici**: include una serie di strumenti per la ricerca online, il recupero di pagine web, la lettura di file e altro, e può collegare server MCP autorizzati dall'utente (Google Drive, Notion, Slack, GitHub ecc.); il modello può chiamare autonomamente gli strumenti più volte in una singola richiesta per completare attività complesse. -- **Eventi di streaming strutturati**: tramite `accept: text/event-stream` o `application/x-ndjson` è possibile ottenere eventi quali `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` e altri, token per token, semplificando il rendering separato nel frontend in base al tipo corrispondente. -- **Interrompibile / ripristinabile**: quando il modello necessita di ulteriori informazioni dall'utente, emette un evento `ask_user_question` e si mette in pausa; alla chiamata successiva è possibile continuare compilando la risposta tramite `tool_results`. -- **Nuove azioni CRUD**: sullo stesso endpoint, utilizzare il campo `action` per completare `retrieve` / `retrieve_batch` / `update` / `delete`, senza necessità di API aggiuntive per la gestione delle conversazioni. -- **Elenco dei modelli costantemente aggiornato**: per impostazione predefinita integra modelli contemporanei come GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 e altri. +- **Input utente multimodale**: tramite il campo `message` strutturato, invia direttamente blocchi di testo + immagini + file, senza dover prima allegarli indirettamente usando `references`. +- **Chiamate di strumenti in stile Agent**: include una suite di strumenti per ricerca online, scraping di pagine web, lettura di file e altro, e può collegare server MCP autorizzati dall'utente (Google Drive, Notion, Slack, GitHub e altri); il modello può chiamare autonomamente gli strumenti per più turni in una singola richiesta per completare attività complesse. +- **Eventi di streaming strutturati**: tramite `accept: text/event-stream` o `application/x-ndjson` è possibile ottenere eventi come `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` e altri, token per token, facilitando il rendering separato per tipo nel frontend. +- **Interrompibile / ripristinabile**: quando il modello necessita di ulteriori informazioni dall'utente, emette un evento `ask_user_question` e si mette in pausa; nella chiamata successiva è possibile continuare compilando la risposta tramite `tool_results`. +- **Nuove azioni CRUD**: sullo stesso endpoint, completa `retrieve` / `retrieve_batch` / `update` / `delete` tramite il campo `action`, senza necessitare di API aggiuntive per la gestione delle conversazioni. +- **Elenco di modelli aggiornato continuamente**: per impostazione predefinita integra modelli contemporanei quali GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 e altri. -Allo stesso tempo, a livello di corpo della richiesta è **completamente retrocompatibile con v1**: basta passare `model` + `question` (+ opzionalmente `stateful` / `id` / `references` / `preset`) per ottenere una risposta JSON `{answer, id}` equivalente a v1; pertanto, per migrare da `/aichat/conversations` non è necessario riscrivere il client, basta sostituire il percorso con `/aichat2/conversations`. +Allo stesso tempo, a livello di corpo della richiesta è **completamente retrocompatibile con v1**: è sufficiente inviare `model` + `question` (+ opzionalmente `stateful` / `id` / `references` / `preset`) per ottenere una risposta JSON `{answer, id}` equivalente a v1; pertanto, per migrare da `/aichat/conversations` non è necessario riscrivere il client, basta sostituire il percorso con `/aichat2/conversations`. -> Se stai attualmente utilizzando `/aichat/conversations`, la vecchia interfaccia continuerà a essere disponibile e potrai migrare secondo i tuoi tempi. +> Se al momento utilizzi `/aichat/conversations`, il vecchio endpoint continuerà a essere disponibile, e potrai migrare secondo i tuoi tempi. ## Procedura di richiesta -Per utilizzare l'API AI Chat v2, vai prima alla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token e conservarlo per l'uso. +Per utilizzare l'API AI Chat v2, innanzitutto ottieni il tuo API Token dalla [console di Ace Data Cloud](https://platform.acedata.cloud/console/applications) e conservalo come riserva. ![](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; al termine, tornerai automaticamente alla pagina corrente. -**Un solo API Token può chiamare tutti i servizi della piattaforma, senza doverne richiedere uno separatamente per ogni servizio.** La prima richiesta include crediti gratuiti per una prova gratuita; quando i crediti non sono sufficienti, puoi ricaricare il saldo comune 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 ogni servizio.** Alla prima richiesta verrà assegnato un credito gratuito, che consente di provare il servizio gratuitamente; quando il credito non è sufficiente, puoi ricaricare il saldo universale nella [console](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Utilizzo di base -L'utilizzo più semplice è esattamente uguale a v1: passa `model` + `question` e ottieni `{answer, id}`. +L'utilizzo più semplice è completamente identico a v1: invia `model` + `question` e ottieni `{answer, id}`. Esempio CURL: @@ -76,21 +76,21 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -I valori `model` disponibili possono essere visualizzati direttamente nel menu a discesa del pannello Try sulla destra; le categorie comuni includono: +I valori `model` disponibili possono essere visualizzati direttamente nel menu a discesa del pannello Try sulla destra; le categorie più comuni includono: -- OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` ecc. -- Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` ecc. -- Google: `gemini-3.1-pro-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-image`, `gemini-3.1-pro-preview`, `gemini-2.5-flash-lite` ecc. -- xAI: `grok-4` ecc. -- DeepSeek: `deepseek-v4-pro`, `deepseek-v4.1-flash`, `deepseek-v4-flash`, `deepseek-v3.2-exp`, `deepseek-r1-0528` ecc. -- Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` ecc. -- Zhipu: `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` ecc. +- OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` e altri +- Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` e altri +- Google: `gemini-3.1-pro-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-image`, `gemini-3.1-pro-preview`, `gemini-2.5-flash-lite` e altri +- xAI: `grok-4` e altri +- DeepSeek: `deepseek-v4-pro`, `deepseek-v4.1-flash`, `deepseek-v4-flash`, `deepseek-v3.2-exp`, `deepseek-r1-0528` e altri +- Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` e altri +- Zhipu: `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` e altri Per le regole di fatturazione specifiche, consulta la scheda Pricing nella pagina del servizio. ## Conversazione multi-turno -Come in v1, passa `stateful: true` per attivare il salvataggio della conversazione; l'API restituirà un `id`; nelle richieste successive, basta riportare l'`id` per continuare la conversazione, senza dover gestire personalmente la cronologia dei messages. +Come in v1, invia `stateful: true` per abilitare il salvataggio della conversazione; l'API restituirà un `id`; nelle richieste successive, basta inviare nuovamente l'`id` per continuare la conversazione, senza dover gestire personalmente la cronologia dei messaggi. Prima richiesta: @@ -136,7 +136,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful` è `true` per impostazione predefinita, ometterlo equivale a passare esplicitamente `true`. Se non vuoi che il server salvi questo turno di conversazione, puoi impostare esplicitamente `stateful: false`. +> Il valore predefinito di `stateful` è `true`; ometterlo equivale a passare esplicitamente `true`. Se non desideri che il server salvi questo turno di conversazione, puoi impostare esplicitamente `stateful: false`. ## Risposta in streaming @@ -144,9 +144,9 @@ v2 supporta due formati di streaming, selezionati in base all'header `accept`: | Scenario | `accept` | Forma dei dati | | --------------------- | ---------------------- | ------------------------------------------ | -| Frontend Web / EventSource | `text/event-stream` | `data: {json}\n\n`, ultima riga `data: [DONE]\n\n` | +| Front-end Web / EventSource | `text/event-stream` | `data: {json}\n\n`, ultima riga `data: [DONE]\n\n` | | Server / CLI / parsing streaming Node | `application/x-ndjson` | Un oggetto JSON per riga | -| Streaming non necessario | `application/json`（predefinito） | Restituisce `{answer, id}` in un'unica volta | +| Streaming non necessario | `application/json`（predefinito） | Restituisce in un'unica volta `{answer, id}` | ### Esempio NDJSON @@ -195,7 +195,7 @@ Ogni riga di NDJSON è un evento strutturato; il più comune è `text_delta`: ### Esempio SSE -L'uso di `EventSource` nel browser non supporta corpi di richiesta personalizzati; si consiglia di usare `fetch` + parsing manuale per sezioni tramite `\n\n`: +L'uso di `EventSource` nel browser non supporta corpi di richiesta personalizzati; si consiglia di usare `fetch` + analisi manuale suddividendo per `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -232,28 +232,28 @@ while (true) { } ``` -### Tipi di eventi streaming +### Tipi di eventi in streaming | `type` | Significato | | ------------------- | ----------------------------------------------------------------------------------------------- | | `text_delta` | Frammento di testo incrementale della risposta dell'assistente. `content` è il nuovo contenuto; per compatibilità con v1, lo stesso evento include anche `delta_answer` (uguale a `content`) e `id`. | | `thinking` | Processo di ragionamento del modello (appare solo quando il modello selezionato espone il reasoning). | | `tool_use` | Il modello decide di chiamare uno strumento; l'evento include `tool_id`, `tool_name`, `input`. | -| `tool_result` | Risultato dell'esecuzione dello strumento, associato al precedente `tool_use` tramite `tool_id`; `is_error` indica se l'operazione è fallita. | -| `card` | Scheda strutturata prodotta dallo strumento (come immagini o anteprime di link), adatta al rendering diretto. | -| `citation` | URL della fonte usato per integrare le citazioni del frammento di testo corrispondente. | -| `ask_user_question` | Emesso quando il modello necessita di ulteriori informazioni dall'utente; la conversazione entra nello stato `awaiting_user_input`, vedi sotto [Riprendere una conversazione in pausa](#riprendere-una-conversazione-in-pausa). | -| `artifact` | Prodotto indipendente generato dal modello (come blocchi di codice o documenti), che può essere salvato o scaricato. | -| `system_message` | Messaggio di sistema (non contenuto dell'utente o dell'assistente), utilizzato solo per suggerimenti dell'interfaccia utente. | -| `compact` | Evento in cui il contesto interno è stato compresso, senza necessità di gestione speciale. | +| `tool_result` | Risultato dell'esecuzione dello strumento, associato al precedente `tool_use` tramite `tool_id`; `is_error` indica se si è verificato un errore. | +| `card` | Scheda strutturata prodotta dallo strumento (come immagini, anteprime di link), adatta al rendering diretto. | +| `citation` | URL della fonte utilizzato per integrare le citazioni del corrispondente frammento di testo. | +| `ask_user_question` | Emesso quando il modello necessita che l'utente integri informazioni; la conversazione entra nello stato `awaiting_user_input`; vedi [Riprendere una conversazione in pausa](#riprendere-una-conversazione-in-pausa) qui sotto. | +| `artifact` | Artefatto indipendente generato dal modello (come blocchi di codice, documenti), che può essere salvato o scaricato. | +| `system_message` | Messaggio di sistema (non contenuto dell'utente o dell'assistente), utilizzato solo per i suggerimenti dell'interfaccia utente. | +| `compact` | Evento in cui il contesto interno viene compresso, senza necessità di una gestione speciale. | | `error` | Si è verificato un errore in questo turno; `message` descrive il contenuto dell'errore. | -| `done` | La risposta streaming è terminata; include `usage` (con `prompt_tokens` / `completion_tokens` / `total_tokens`) e `terminal_reason`. | +| `done` | La risposta in streaming termina e include `usage` (con `prompt_tokens` / `completion_tokens` / `total_tokens`) e `terminal_reason`. | -Per i client che si interessano solo della risposta finale, concatenare il `content` di tutti i `text_delta` equivale a `answer` nella modalità `application/json`. +Per i client che si interessano solo alla risposta finale, concatenare i `content` di tutti i `text_delta` equivale a `answer` nella modalità `application/json`. ## Input multimodale -Se l'input dell'utente include immagini o file, passa `message` (array) invece di `question`. Ogni elemento dell'array è un blocco di contenuto: +Se l'input dell'utente contiene immagini o file, passa `message` (array) al posto di `question`. Ogni elemento dell'array è un blocco di contenuto: ```json { @@ -266,32 +266,32 @@ Se l'input dell'utente include immagini o file, passa `message` (array) invece d } ``` -Tipi di blocchi supportati: +Tipi di blocco supportati: - `text` — Testo normale, campo `text` obbligatorio. -- `image_url` — Immagine, campo `image_url.url` obbligatorio. -- `file_url` — File (PDF, CSV, TXT ecc.), campo `file_url.url` obbligatorio. +- `image_url` — Immagine, `image_url.url` obbligatorio. +- `file_url` — File (PDF, CSV, TXT, ecc.), `file_url.url` obbligatorio. ### Relazione con `references` di v1 -Per compatibilità con i vecchi client, v2 riconosce ancora il campo `references: ["https://...", ...]`: -- I suffissi URL sono `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, convertiti automaticamente in blocchi `image_url`; -- le altre estensioni vengono convertite in blocchi `file_url`; -- se viene fornito contemporaneamente anche `question`, allora viene anteposto come blocco `text`. +Per compatibilità con i vecchi client, v2 continua a riconoscere il campo `references: ["https://...", ...]`: +- I suffissi URL sono `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, vengono automaticamente convertiti in blocchi `image_url`; +- Le altre estensioni vengono convertite in blocchi `file_url`; +- Se viene fornito anche `question`, viene anteposto come blocco `text`. -Pertanto, se vuoi solo migrare da v1 senza modificare il corpo della richiesta, basta sostituire il percorso con `/aichat2/conversations`, e l'uso originale di `references` continua a funzionare normalmente. +Pertanto, se vuoi solo migrare da v1 senza modificare il corpo della richiesta, ti basta cambiare il percorso in `/aichat2/conversations`, e l'uso originale di `references` continuerà a funzionare normalmente. -Se è necessario un controllo più preciso (ad esempio inserire più immagini tra i testi, oppure se l'ordine è molto importante), usa direttamente l'array `message`. +Se è necessario un controllo più preciso (ad esempio, inserire più immagini tra i testi, oppure se l'ordine è molto importante), usa direttamente l'array `message`. -## Chiamate degli strumenti e MCP +## Chiamata di strumenti e MCP Il principale miglioramento di v2 è che il modello può chiamare autonomamente strumenti per completare attività in più passaggi, **ed è abilitato per impostazione predefinita**, senza che il client debba effettuare alcuna configurazione aggiuntiva nella richiesta. Scenari comuni: -- L'utente chiede «Cercami quali nuove mostre ci sono recentemente a Shanghai» → il modello chiama la ricerca web integrata → organizza i risultati in una risposta. -- L'utente chiede «Leggi questo PDF e poi scrivi un riepilogo» → il modello chiama file_read → scrive il riepilogo. -- L'utente ha già autorizzato Google Drive / GitHub / Notion ecc. in [Connections](https://platform.acedata.cloud/connections) → il modello può chiamare gli strumenti MCP corrispondenti per leggere e scrivere i relativi dati. +- L'utente chiede «Cercami le nuove mostre recenti a Shanghai» → il modello chiama la ricerca web integrata → organizza i risultati in una risposta. +- L'utente chiede «Leggi questo PDF e poi scrivi un riassunto» → il modello chiama file_read → scrive un riassunto. +- L'utente ha già autorizzato Google Drive / GitHub / Notion ecc. in [Connections](https://platform.acedata.cloud/connections) → il modello può chiamare gli strumenti MCP corrispondenti per leggere e scrivere i suoi dati. -Nel flusso NDJSON / SSE, le chiamate degli strumenti vengono presentate tramite due tipi di eventi, `tool_use` e `tool_result`, ad esempio: +Nel flusso NDJSON / SSE, le chiamate di strumenti vengono presentate tramite due tipi di eventi, `tool_use` e `tool_result`, ad esempio: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,19 +301,19 @@ Nel flusso NDJSON / SSE, le chiamate degli strumenti vengono presentate tramite ... ``` -Se non vuoi mostrare nel frontend i dettagli delle chiamate degli strumenti, basta ignorare gli eventi `tool_use` / `tool_result` / `card` / `citation`; l'output finale del modello continua comunque a fluire tramite `text_delta`. +Se non vuoi mostrare nel frontend i dettagli delle chiamate di strumenti, basta ignorare gli eventi `tool_use` / `tool_result` / `card` / `citation`; l'output finale del modello verrà comunque trasmesso tramite `text_delta`. -`max_turns` può limitare il numero massimo di cicli in cui il modello può richiamare autonomamente strumenti in questa richiesta; il limite predefinito è deciso dalla piattaforma. Impostarlo a un valore basso (ad esempio `max_turns: 1`) può forzare una singola risposta e non consentire alcuna chiamata di strumenti. +`max_turns` può limitare il numero massimo di cicli in cui il modello può chiamare autonomamente strumenti in questa richiesta; l'intervallo è 1–500 e, se omesso, il valore predefinito è 500. Impostarlo a un valore basso (ad esempio `max_turns: 1`) può forzare una risposta singola e non consentire alcuna chiamata di strumenti. -## Esecuzione asincrona e autorizzazione non supervisionata +## Esecuzione asincrona e autorizzazione non presidiata -Se la tua chiamata proviene da un Webhook di avviso, CI/CD, sistema di monitoraggio o altre attività di backend, puoi impostare `async: true` affinché l'interfaccia restituisca immediatamente l'ID dell'attività e continui l'esecuzione in background: +Se la tua chiamata proviene da un Webhook di allarme, CI/CD, sistema di monitoraggio o altre attività backend, puoi impostare `async: true` affinché l'interfaccia restituisca immediatamente l'ID dell'attività e continui l'esecuzione in background: ```json { "model": "gpt-5.5", "async": true, - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Il mio servizio ha generato un allarme, usa WeChat personale per notificare il gruppo WeChat 「AceDataCloud团队」……" } ``` @@ -328,9 +328,9 @@ Esempio di risposta: } ``` -Successivamente puoi usare `action: retrieve` + `id` per interrogare il risultato della conversazione; puoi anche fornire `callback_url`, e al completamento dell'attività la piattaforma invierà `{ status, answer, usage, error }` tramite POST al tuo indirizzo di callback. `callback_url` deve usare `http` / `https` e non può indicare direttamente `localhost` o un indirizzo IP privato letterale. +Successivamente puoi usare `action: retrieve` + `id` per interrogare il risultato della conversazione; puoi anche fornire `callback_url`, e dopo il completamento dell'attività la piattaforma invierà `{ status, answer, usage, error }` tramite POST al tuo indirizzo di callback. `callback_url` deve usare `http` / `https` e non può indicare direttamente `localhost` o un indirizzo IP privato letterale. -Di solito nelle attività di background non c'è nessuno che possa fare clic per confermare. Se desideri che determinate Skill o MCP Server eseguano azioni come invio, pubblicazione, scrittura ecc. in modalità non supervisionata, passa esplicitamente un elenco di pre-autorizzazione nel corpo della richiesta: +Di norma, nelle attività backend non c'è nessuno che possa fare clic per confermare. Se desideri che alcuni Skill o MCP Server eseguano azioni come invio, pubblicazione, scrittura ecc. in modalità non presidiata, passa esplicitamente un elenco di preautorizzazioni nel corpo della richiesta: ```json { @@ -338,13 +338,13 @@ Di solito nelle attività di background non c'è nessuno che possa fare clic per "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Il mio servizio ha generato un allarme, usa WeChat personale per notificare il gruppo WeChat 「AceDataCloud团队」……" } ``` -I valori in `allowed_skills` sono gli slug delle Skill connesse; i valori in `allowed_mcp_servers` sono gli slug degli MCP Server connessi. Le Skill / gli MCP Server non inclusi nella pre-autorizzazione, in modalità non supervisionata, possono comunque solo visualizzare in anteprima, effettuare dry-run o rifiutarsi di eseguire operazioni di scrittura. +I valori in `allowed_skills` sono gli slug dei Skill connessi; i valori in `allowed_mcp_servers` sono gli slug dei MCP Server connessi. I Skill / MCP Server non inclusi nella preautorizzazione, in modalità non presidiata, possono ancora solo fare anteprima, dry-run o rifiutare di eseguire operazioni di scrittura. -Se è necessario un controllo più dettagliato, puoi anche usare l'equivalente oggetto `unattended_policy`: +Se è necessario un controllo più granulare, puoi anche usare l'oggetto equivalente `unattended_policy`: ```json { @@ -356,11 +356,11 @@ Se è necessario un controllo più dettagliato, puoi anche usare l'equivalente o } ``` -La pre-autorizzazione consiste proprio in questi due elenchi: un elenco vuoto significa non autorizzare alcuna capacità, senza necessità di campi di attivazione aggiuntivi. +La preautorizzazione è costituita da questi due elenchi stessi: se gli elenchi sono vuoti, non viene autorizzata alcuna capacità, senza necessità di un campo interruttore aggiuntivo. -Nota: la pre-autorizzazione rappresenta solo il fatto che «questa richiesta consente a queste capacità di saltare la conferma manuale in modalità non supervisionata». La Skill specifica deve comunque supportare `--unattended-confirm` o il corrispondente meccanismo di sicurezza; altrimenti continuerà a effettuare dry-run e non eseguirà direttamente operazioni di scrittura. +Nota: la preautorizzazione significa solo che «questa richiesta consente a queste capacità di saltare la conferma manuale in modalità non presidiata». Lo Skill specifico deve comunque supportare `--unattended-confirm` o il corrispondente meccanismo di sicurezza; altrimenti continuerà a fare dry-run e non eseguirà direttamente operazioni di scrittura. -## Riprendere una conversazione sospesa +## Riprendere una conversazione in pausa Alcuni strumenti fanno sì che il modello «ponga una domanda all'utente»; in questo momento il modello emette un evento `ask_user_question` e la conversazione viene congelata nello stato `awaiting_user_input`: @@ -375,7 +375,7 @@ Alcuni strumenti fanno sì che il modello «ponga una domanda all'utente»; in q } ``` -Nel frontend, rendi questo evento come una scheda affinché l'utente scelga una risposta, quindi avvia la richiesta successiva con lo stesso `id`, reinserendo la risposta tramite `tool_results`: +Nel frontend, rendi questo evento come una scheda affinché l'utente possa scegliere una risposta, quindi avvia la richiesta successiva usando lo stesso `id` e reinserisci la risposta tramite `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Il `tool_use_id` nel corpo della richiesta **deve** corrispondere esattamente al `tool_id` al momento della sospensione; in caso contrario verrà restituito 400. Quando nella richiesta sono presenti contemporaneamente `tool_results`, `question` / `message` / `references` vengono tutti ignorati. +Il `tool_use_id` nel corpo della richiesta **deve** corrispondere esattamente al `tool_id` al momento della sospensione; in caso contrario verrà restituito 400. Quando nella richiesta è presente contemporaneamente `tool_results`, `question` / `message` / `references` verranno tutti ignorati. -Se l'utente decide di abbandonare questa domanda, basta passare un nuovo `question` / `message`; la piattaforma contrassegnerà automaticamente la chiamata dello strumento sospesa come «saltata dall'utente». +Se l'utente decide di abbandonare questa domanda, basta passare un nuovo `question` / `message`; la piattaforma contrassegnerà automaticamente la chiamata di strumento sospesa come «saltata dall'utente». ## Gestione delle conversazioni (CRUD) v2 fornisce una gestione leggera delle conversazioni sullo stesso endpoint tramite il campo `action`, senza necessità di aprire un'altra API. - ### `action: retrieve` —— Recuperare una conversazione + ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Restituisce il documento completo della conversazione (inclusi la cronologia di `messages`, `model`, `title`, `tools_used` e così via). +Restituisce il documento completo della conversazione (inclusi la cronologia `messages`, `model`, `title`, `tools_used` e così via). -### `action: retrieve_batch` —— Elenca i riepiloghi delle conversazioni +### `action: retrieve_batch` —— Elencare i riepiloghi delle conversazioni ```json { @@ -428,23 +428,23 @@ Restituisce il documento completo della conversazione (inclusi la cronologia di } ``` -Restituisce `{ items: [...], total }`. **I riepiloghi non includono `messages`**, quindi sono adatti per un elenco nella barra laterale; se l'utente apre una conversazione, usa poi `action: retrieve` per recuperare separatamente i suoi messaggi completi. +Restituisce `{ items: [...], total }`. **I riepiloghi non contengono `messages`**, e sono adatti per gli elenchi nella barra laterale; se l'utente apre una conversazione, usa poi `action: retrieve` per recuperare separatamente i suoi messaggi completi. Parametri di filtro opzionali: `user_id`, `application_id`, `model_group`, `model`. -### `action: update` —— Modifica il titolo o riscrive la cronologia +### `action: update` —— Modificare il titolo o riscrivere la cronologia ```json { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "title": "杭州旅行计划" + "title": "Piano di viaggio a Hangzhou" } ``` -È possibile passare anche `messages`, ma il server eseguirà una rigorosa convalida dello schema (deve avere la forma `ToolUseContent` compressa); in caso contrario restituirà 400. In generale, si consiglia di usarlo solo per modificare `title`. +È possibile passare anche `messages`, ma il server eseguirà una rigorosa convalida dello schema (deve avere la forma `ToolUseContent` compressa); se non è conforme, restituirà 400. In generale, si consiglia di usarlo solo per modificare `title`. -### `action: delete` —— Elimina una conversazione +### `action: delete` —— Eliminare una conversazione ```json { @@ -453,21 +453,21 @@ Parametri di filtro opzionali: `user_id`, `application_id`, `model_group`, `mode } ``` -Restituisce `{ id, success: true }`. Dopo l'eliminazione non sarà possibile ripristinarla, conferma prima di chiamarla. +Restituisce `{ id, success: true }`. Dopo l'eliminazione non è possibile ripristinarla, conferma prima di effettuare la chiamata. ## Migrazione fluida da v1 Se stai già utilizzando [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), la migrazione a v2 non richiede quasi alcuna modifica al codice: 1. Modifica l'URL da `https://api.acedata.cloud/aichat/conversations` a `https://api.acedata.cloud/aichat2/conversations`. -2. Se in precedenza passavi nomi di modelli v1 (come `gpt-3.5`, `gpt-4-browsing` e così via), quando passi a v2 è consigliabile aggiornare ai modelli contemporanei (come `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` e così via). -3. I campi del flusso NDJSON rimangono retrocompatibili: ogni evento `text_delta` include ancora `delta_answer` e `id`, pertanto i client originali che analizzano riga per riga `delta_answer` non richiedono modifiche. +2. Se in precedenza trasmettevi nomi di modelli v1 (come `gpt-3.5`, `gpt-4-browsing` e così via), quando passi a v2 è consigliabile aggiornare ai modelli contemporanei (come `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` e così via). +3. I campi del flusso NDJSON rimangono retrocompatibili: ogni evento `text_delta` continua a includere `delta_answer` e `id`, pertanto i client che originariamente analizzavano `delta_answer` riga per riga non richiedono modifiche. -Dopo la migrazione, puoi abilitare secondo necessità le nuove funzionalità di v2 (`message` multimodale, SSE, chiamate di strumenti, CRUD `action`), procedendo secondo i tuoi ritmi. +Dopo la migrazione, puoi abilitare secondo necessità le nuove funzionalità di v2 (`message` multimodale, SSE, chiamate agli strumenti, CRUD `action`) e procedere secondo i tuoi ritmi. ## Gestione degli errori -Le risposte di errore sono uniformemente nel formato: +La risposta di errore è uniformemente: ```json { @@ -481,14 +481,14 @@ Le risposte di errore sono uniformemente nel formato: Errori comuni: -- `400 bad_request`: campi obbligatori mancanti, mancata corrispondenza di `tool_use_id`, schema di `messages` non valido e così via. -- `401 invalid_token`: l'header `authorization` non è corretto. +- `400 bad_request`: mancano campi obbligatori, `tool_use_id` non corrisponde, lo schema `messages` non è valido, ecc. +- `401 invalid_token`: l'intestazione `authorization` non è corretta. - `404 not_found`: la conversazione corrispondente a `id` non esiste durante `action: retrieve / update / delete`. -- `429 too_many_requests`: è stato attivato il limite di velocità. -- `500 chat_error`: errore dell'LLM upstream o `completion_tokens=0` in questo turno (trattato come non consumato, non verrà addebitato). +- `429 too_many_requests`: è stato attivato il limite di frequenza. +- `500 chat_error`: errore dell'LLM a monte oppure `completion_tokens=0` in questo turno (trattato come non consumato, non verrà addebitato). -Nella risposta in streaming, gli errori vengono emessi come evento `{"type":"error","message":"..."}`, subito dopo il flusso terminerà. +Nelle risposte in streaming, gli errori vengono emessi come eventi `{"type":"error","message":"..."}`, dopodiché il flusso terminerà immediatamente. ## Conclusione -L'API AI Chat v2, pur mantenendo la retrocompatibilità con v1, aggiorna le conversazioni da «domande e risposte a turno singolo / multiplo» a «conversazioni osservabili agentiche»: input multimodale, chiamate di strumenti, sospendibili / ripristinabili, eventi strutturati in streaming, CRUD integrato. Si consiglia alle nuove integrazioni di utilizzare direttamente v2; le integrazioni v1 esistenti possono migrare gradualmente per fasi. Per qualsiasi domanda, contatta in qualsiasi momento il nostro team di supporto tecnico. +L'API AI Chat v2, pur mantenendo la retrocompatibilità con v1, aggiorna le conversazioni da «domande e risposte a turno singolo / multiplo» a «conversazioni osservabili basate su Agent»: input multimodale, chiamate agli strumenti, sospendibili / ripristinabili, eventi strutturati in streaming, CRUD integrato. Per le nuove integrazioni, si consiglia di utilizzare direttamente v2; le integrazioni v1 esistenti possono migrare gradualmente e senza interruzioni. Per qualsiasi domanda, contatta in qualsiasi momento il nostro team di supporto tecnico. diff --git a/it/guides/platform/hermes_managed.mdx b/it/guides/platform/hermes_managed.mdx index de54c471d..b7706b11e 100644 --- a/it/guides/platform/hermes_managed.mdx +++ b/it/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Distribuzione Privata di Hermes Agent" +title: "Distribuzione di Hermes" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud offre un ingresso per la distribuzione privata di Hermes Agent. Questo ingresso è un servizio controllato, la disponibilità e le risorse selezionabili sono soggette a quanto attualmente visualizzato nella console. +Crea un'istanza di contenitore Hermes indipendente per ogni Application. Per impostazione predefinita viene utilizzata un'immagine di base con una versione di rilascio fissa, mantenendo le funzionalità native; la piattaforma fornisce acquisto, rinnovo, archiviazione persistente e gestione della distribuzione. -## Passaggi da seguire +## Creazione e acquisto -1. Trova **Distribuzione Privata di Hermes Agent** sulla piattaforma. -2. Segui le istruzioni della pagina per selezionare la configurazione disponibile e creare il servizio. -3. Attendi che la piattaforma mostri lo stato di prontezza. -4. Utilizza l'ingresso e le credenziali forniti dalla pagina per accedere all'istanza. -5. Invia prima `Reply only OK`, poi inizia il compito reale. +1. Apri [Distribuzione di Hermes](https://platform.acedata.cloud/services/hermes) e crea un'Application. +2. Nella pagina di acquisto seleziona un piano di durata e completa il pagamento. +3. Torna alla pagina di configurazione, seleziona il modello di chat della piattaforma dall'elenco a discesa e visualizza il prezzo del modello corrente. La piattaforma creerà credenziali API indipendenti per questa istanza; puoi anche disattivare l'accesso alla piattaforma e configurare autonomamente nella console nativa. +4. Scegli di generare automaticamente le credenziali di accesso oppure imposta una password/Token sicuro personalizzato; dopo la conferma inizia la distribuzione. Le credenziali di accesso e le credenziali API del modello sono indipendenti tra loro. +5. Quando l'istanza è pronta, ottieni l'indirizzo di accesso e le credenziali di login dalla pagina di gestione. +6. Accedi alla console nativa e configura i tuoi provider di modelli, chiavi e canali. -Modelli, credenziali, comportamenti di archiviazione e cancellazione sono soggetti alla pagina di creazione e alla finestra di conferma; non considerare direttamente il YAML del tutorial locale di Hermes come contratto di distribuzione della piattaforma. Prima di eliminare, esporta i dati che desideri conservare. +La tariffa di distribuzione viene calcolata in base alla durata del piano; i prezzi specifici in dollari USA e le durate fanno fede alla pagina di acquisto. I costi delle chiamate al modello vengono addebitati separatamente; l'acquisto della durata di distribuzione non include crediti per il modello. Quando l'accesso alla piattaforma è abilitato, le credenziali API dedicate espongono solo l'interfaccia chat corrispondente al modello selezionato e le chiamate vengono addebitate separatamente dal saldo della tua piattaforma. Ogni Application viene acquistata, rinnovata e gestita separatamente. -Se la console non mostra l'ingresso per la creazione, significa che l'account attuale non ha ancora accesso a questo servizio, puoi utilizzare [Guida Interattiva di Hermes](https://platform.acedata.cloud/documents/hermes-wizard-integration) o [Configurazione Manuale](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Password, credenziali e configurazione successiva + +Le credenziali di accesso vengono impostate prima del primo avvio. La generazione automatica utilizza credenziali casuali, la password personalizzata deve avere almeno 16 caratteri e il Token OpenClaw almeno 32 caratteri. Le bozze non salvano le password; dopo aver cambiato pagina potrebbe essere necessario inserirle nuovamente. Dopo la distribuzione, solo il proprietario e gli amministratori dell'Application possono visualizzare le credenziali di accesso. + +Le credenziali API del modello di ogni istanza non vengono riutilizzate tra loro, la loro validità viene estesa con il rinnovo della distribuzione e vengono revocate quando l'istanza viene eliminata. Dopo l'inizializzazione della distribuzione, modifica i modelli e i canali nella console nativa; se selezioni modelli di altri servizi, regola prima l'autorizzazione dell'interfaccia corrispondente nella gestione delle credenziali della piattaforma oppure utilizza le credenziali corrispondenti. Una normale nuova distribuzione non sovrascrive le impostazioni native. Gli ambienti di distribuzione non verificati per la pubblicazione rifiuteranno temporaneamente le nuove distribuzioni; contatta il supporto. + +## Versioni e dati + +La pagina di configurazione mostra la versione dell'immagine attualmente pubblicata. Le nuove istanze utilizzano la versione attualmente pubblicata del servizio; le istanze esistenti non vengono sostituite automaticamente con gli aggiornamenti del catalogo. La nuova distribuzione applicherà la versione corrente del servizio; esegui prima un backup e verifica i requisiti di aggiornamento della versione utilizzata. + +Ogni istanza fornisce per impostazione predefinita 1 CPU, un limite di memoria di 2 GiB e 10 GiB di archiviazione persistente. Il riavvio conserva i dati dell'istanza. L'eliminazione attiva della distribuzione o il recupero alla scadenza elimineranno l'archiviazione; esporta in anticipo i dati che devono essere conservati. + +## Rinnovo e scadenza + +Rinnova nella pagina di acquisto dell'Application corrente; il periodo di validità verrà esteso secondo le attuali regole di durata della piattaforma. Dopo la scadenza, il punto di accesso viene sospeso; il rinnovo durante il periodo di grazia ripristina l'accesso; oltre il periodo di grazia, l'istanza e i dati verranno recuperati. Fanno fede l'orario di scadenza, lo stato di fatturazione e l'avviso di eliminazione nella pagina di gestione. + +## Accesso all'interfaccia di gestione + +Nella pagina di gestione della distribuzione copia l'indirizzo Dashboard, il nome utente `admin` e la password, quindi apri e accedi. Le informazioni di accesso sono fornite solo al proprietario di tale Application e agli amministratori della piattaforma. Modelli, competenze e canali vengono configurati nell'interfaccia nativa di Hermes. + +## Domande frequenti + +- **Perché la nuova istanza non può ancora rispondere?** Il completamento della distribuzione indica che il contenitore è pronto; è necessario configurare il modello e le credenziali nell'interfaccia nativa prima di poter iniziare a usarla. +- **Sono preinstallati plugin aggiuntivi o fallback del modello?** Per impostazione predefinita non vengono aggiunti; configura secondo necessità nell'interfaccia nativa. +- **Come si aggiornano le istanze esistenti?** L'Application e l'ordine originali vengono mantenuti; durante la nuova distribuzione viene utilizzata la versione corrente del servizio; prima dell'aggiornamento esegui un backup dei dati e verifica la compatibilità della versione. +- **Cosa fare se l'avvio non riesce?** Visualizza prima i log e gli eventi di distribuzione, quindi configura il modello dopo aver confermato che l'istanza è pronta. Non esporre password e chiavi dell'istanza in commenti pubblici o screenshot. diff --git a/it/guides/platform/wework_bot.mdx b/it/guides/platform/wework_bot.mdx deleted file mode 100644 index ca871bc12..000000000 --- a/it/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/ja/guides/aichat/aichat2_conversations.mdx index 039b7555a..4f7051e86 100644 --- a/ja/guides/aichat/aichat2_conversations.mdx +++ b/ja/guides/aichat/aichat2_conversations.mdx @@ -1,36 +1,36 @@ --- -title: "AI Chat v2 API 連携説明" +title: "AI Chat v2 API 連携ガイド" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API（`/aichat2/conversations`）は新世代の対話インターフェースであり、[AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations) の全面アップグレード版です。v1 のシンプルでホスト型のマルチターン対話を基盤として、以下を拡張しています： +AI Chat v2 API（`/aichat2/conversations`）は、新世代の対話インターフェースであり、[AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations) の完全アップグレード版です。v1 のシンプルでホスト型のマルチターン対話をベースに、以下を拡張しています： -- **マルチモーダルなユーザー入力**：構造化された `message` フィールドを通じて、テキスト + 画像 + ファイルブロックを直接渡せます。まず `references` を使用して間接的に添付する必要はありません。 -- **Agent 化されたツール呼び出し**：Web 検索、Web ページの取得、ファイル読み取りなどのツールセットを内蔵しており、ユーザーが認可した MCP サーバー（Google Drive、Notion、Slack、GitHub など）も接続できます。モデルは1回のリクエスト内で複数回自律的にツールを呼び出し、複雑なタスクを完了できます。 -- **構造化ストリーミングイベント**：`accept: text/event-stream` または `application/x-ndjson` により、トークン単位の `text_delta`、`tool_use`、`tool_result`、`thinking`、`citation`、`card`、`artifact` などのイベントを取得でき、フロントエンドで対応する型ごとに個別にレンダリングできます。 -- **中断 / 再開可能**：モデルはユーザーによる情報補足が必要な際に `ask_user_question` イベントを発行して一時停止します。次回の呼び出し時に `tool_results` を通じて回答を返すことで継続できます。 -- **新しい CRUD アクション**：同一の endpoint 上で `action` フィールドにより `retrieve` / `retrieve_batch` / `update` / `delete` を完了でき、追加の会話管理 API は不要です。 -- **継続的に更新されるモデルリスト**：デフォルトで GPT-5.4、Claude Opus 4.8、Claude Sonnet 4.6、Gemini 3.1 Pro、GLM 5.1、DeepSeek V4、Kimi K3 などの現代的なモデルに対応しています。 +- **マルチモーダルなユーザー入力**：構造化された `message` フィールドを通じて、テキスト + 画像 + ファイルブロックを直接送信でき、事前に `references` を使用して間接的に添付する必要がありません。 +- **Agent 化されたツール呼び出し**：インターネット検索、Web ページ取得、ファイル読み取りなどのツールセットを内蔵し、ユーザー認可済みの MCP サーバー（Google Drive、Notion、Slack、GitHub など）をマウントすることもできます。モデルは 1 回のリクエスト内で複数回自律的にツールを呼び出し、複雑なタスクを完了できます。 +- **構造化ストリーミングイベント**：`accept: text/event-stream` または `application/x-ndjson` を通じて、トークンごとの `text_delta`、`tool_use`、`tool_result`、`thinking`、`citation`、`card`、`artifact` などのイベントを取得でき、フロントエンドで対応するタイプごとに個別にレンダリングできます。 +- **中断 / 再開可能**：モデルがユーザーによる追加情報を必要とする場合、`ask_user_question` イベントを発行して一時停止します。次回の呼び出し時に `tool_results` を通じて回答を返送すれば、継続できます。 +- **新たな CRUD アクション**：同一 endpoint 上で `action` フィールドを通じて `retrieve` / `retrieve_batch` / `update` / `delete` を実行でき、追加の会話管理 API は不要です。 +- **継続的に更新されるモデル一覧**：デフォルトで GPT-5.4、Claude Opus 4.8、Claude Sonnet 4.6、Gemini 3.1 Pro、GLM 5.1、DeepSeek V4、Kimi K3 などの現代的なモデルに接続します。 -同時に、リクエストボディのレベルでは**完全に v1 と後方互換**です。`model` + `question`（+ オプションの `stateful` / `id` / `references` / `preset`）のみを渡すことで、v1 と同等の `{answer, id}` JSON レスポンスを取得できます。そのため、`/aichat/conversations` から移行する際にクライアントを書き直す必要はなく、パスを `/aichat2/conversations` に変更するだけです。 +同時に、リクエストボディのレベルで**v1 と完全に後方互換**です：`model` + `question`（+ 任意の `stateful` / `id` / `references` / `preset`）のみを送信すれば、v1 と同等の `{answer, id}` JSON レスポンスを取得できます。そのため、`/aichat/conversations` から移行する場合、クライアントを書き直す必要はなく、パスを `/aichat2/conversations` に変更するだけです。 -> 現在 `/aichat/conversations` を使用している場合、旧インターフェースも引き続き提供されるため、ご自身のペースで移行できます。 +> 現在 `/aichat/conversations` を使用している場合でも、旧インターフェースは引き続き提供されるため、ご自身のペースで移行できます。 ## 申請手順 -AI Chat v2 API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。 +AI Chat v2 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) で共通残高をチャージできます。 > 📘 完全なドキュメント：[AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## 基本的な使用方法 -最もシンプルな使い方は v1 と完全に同じです：`model` + `question` を渡し、`{answer, id}` を取得します。 +最もシンプルな使用方法は v1 と完全に同じです：`model` + `question` を送信し、`{answer, id}` を取得します。 CURL の例： @@ -45,7 +45,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -返却結果： +レスポンス： ```json { @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -利用可能な `model` の値は、右側の Try パネルのドロップダウンで直接確認できます。一般的なカテゴリには以下が含まれます： +利用可能な `model` の値は、右側の Try パネルのドロップダウンで直接確認できます。主なカテゴリには以下が含まれます： - OpenAI：`gpt-5.4-mini`、`gpt-5.4-nano`、`gpt-5.2-pro`、`gpt-5.1-all`、`gpt-5-all`、`gpt-4.1`、`gpt-4o`、`gpt-4o-image`、`o3`、`o4-mini` など - Anthropic：`claude-opus-4-8`、`claude-opus-4-7`、`claude-opus-4-6`、`claude-opus-4-5-20251101`、`claude-sonnet-4-6`、`claude-sonnet-4-5-20250929`、`claude-haiku-4-5-20251001` など @@ -90,7 +90,7 @@ print(response.json()) ## マルチターン対話 -v1 と同様に、`stateful: true` を渡すことで会話保存を有効化できます。API は `id` を返し、後続のリクエストで `id` を渡し戻すことで対話を継続できます。自分で messages 履歴を管理する必要はありません。 +v1 と同様に、`stateful: true` を送信して会話保存を有効にすると、API は `id` を返します。後続のリクエストでこの `id` を送信すれば、`messages` の履歴を自分で管理することなく対話を継続できます。 最初のリクエスト： @@ -106,7 +106,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -返却： +レスポンス： ```json { @@ -115,7 +115,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -2回目のリクエストでは、同じ `id` を渡します： +2 回目のリクエストでは、同じ `id` を指定します： ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -136,17 +136,17 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful` のデフォルトは `true` であり、省略した場合と明示的に `true` を渡す場合は同等です。サーバー側でこのラウンドの会話を保存したくない場合は、明示的に `stateful: false` を設定できます。 +> `stateful` のデフォルトは `true` であり、省略することは明示的に `true` を渡すことと同等です。サーバー側で今回の会話を保存したくない場合は、明示的に `stateful: false` を設定できます。 ## ストリーミングレスポンス -v2 は 2 種類のストリーミング形式をサポートしており、`accept` ヘッダーに応じて選択します： +v2 は 2 種類のストリーミング形式をサポートしており、`accept` ヘッダーに応じて選択します。 | シナリオ | `accept` | データ形式 | | --------------------- | ---------------------- | ------------------------------------------ | | Web フロントエンド / EventSource | `text/event-stream` | `data: {json}\n\n`、最終行は `data: [DONE]\n\n` | -| サーバーサイド / CLI / Node のストリーミング解析 | `application/x-ndjson` | 1 行につき 1 つの JSON オブジェクト | -| ストリーミング不要 | `application/json`（デフォルト） | 一度に `{answer, id}` を返す | +| サーバーサイド / CLI / Node ストリーミング解析 | `application/x-ndjson` | 1 行につき 1 つの JSON オブジェクト | +| ストリーミング不要 | `application/json`（デフォルト） | 一括で `{answer, id}` を返す | ### NDJSON の例 @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -NDJSON の各行は構造化イベントであり、最も一般的なのは `text_delta` です： +NDJSON の各行は構造化イベントであり、最も一般的なのは `text_delta` です。 ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +195,7 @@ NDJSON の各行は構造化イベントであり、最も一般的なのは `te ### SSE の例 -ブラウザ側では `EventSource` はカスタムリクエストボディをサポートしていないため、`fetch` + 手動で `\n\n` ごとに分割して解析することを推奨します： +ブラウザー側で `EventSource` を使用するとカスタムリクエストボディがサポートされないため、`fetch` + `\n\n` による手動スライス解析の使用を推奨します。 ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +236,24 @@ while (true) { | `type` | 意味 | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | アシスタントの回答の増分テキスト断片。`content` は追加された内容です。v1 との互換性のため、同じイベントには `delta_answer`（`content` と等しい）と `id` も含まれます。 | -| `thinking` | モデルの思考過程（選択したモデルが reasoning を公開する場合にのみ出現します）。 | -| `tool_use` | モデルがツールを呼び出すことを決定した際のイベントで、`tool_id`、`tool_name`、`input` を含みます。 | -| `tool_result` | ツールの実行結果。前の `tool_use` と `tool_id` によって対応付けられ、`is_error` は失敗したかどうかを示します。 | -| `card` | ツールによって生成された構造化カード（画像、リンクプレビューなど）で、直接レンダリングするのに適しています。 | +| `text_delta` | アシスタント回答の増分テキスト断片。`content` は追加内容です。v1 との互換性のため、同じイベントには `delta_answer`（`content` と等しい）および `id` も含まれます。 | +| `thinking` | モデルの思考プロセス（選択したモデルが reasoning を公開する場合にのみ発生します）。 | +| `tool_use` | モデルがツールの呼び出しを決定したことを示し、イベントには `tool_id`、`tool_name`、`input` が含まれます。 | +| `tool_result` | ツールの実行結果。前の `tool_use` と `tool_id` により対応付けられ、`is_error` は失敗したかどうかを示します。 | +| `card` | ツールが生成した構造化カード（画像、リンクプレビューなど）であり、直接レンダリングするのに適しています。 | | `citation` | 対応するテキスト断片の引用元 URL を補足するために使用されます。 | -| `ask_user_question` | モデルがユーザーに追加情報を求める際に発行され、会話は `awaiting_user_input` 状態になります。詳細は下記の [一時停止した会話を再開する](#一時停止した会話を再開する) を参照してください。 | -| `artifact` | モデルが生成した独立した成果物（コードブロック、ドキュメントなど）で、保存またはダウンロードできます。 | -| `system_message` | システム通知情報（ユーザーおよびアシスタントの内容ではない）であり、UI 通知のみに使用されます。 | +| `ask_user_question` | モデルがユーザーに追加情報を求める際に発生し、会話は `awaiting_user_input` 状態になります。詳細は以下の [一時停止した会話の再開](#一時停止した会話の再開) を参照してください。 | +| `artifact` | モデルが生成した独立した成果物（コードブロック、ドキュメントなど）であり、保存またはダウンロードできます。 | +| `system_message` | システム通知情報（ユーザーおよびアシスタントの内容ではない）であり、UI 通知にのみ使用されます。 | | `compact` | 内部コンテキストが圧縮されたイベントであり、特別な処理は不要です。 | -| `error` | このラウンドでエラーが発生し、`message` がエラー内容を説明します。 | +| `error` | 今回の処理でエラーが発生し、`message` がエラー内容を説明します。 | | `done` | ストリーミングレスポンスの終了。`usage`（`prompt_tokens` / `completion_tokens` / `total_tokens` を含む）および `terminal_reason` を含みます。 | -最終回答のみを必要とするクライアントでは、すべての `text_delta` の `content` を連結すれば、`application/json` モードでの `answer` と同等になります。 +最終回答だけを必要とするクライアントでは、すべての `text_delta` の `content` を連結すれば、`application/json` モードにおける `answer` と同等です。 ## マルチモーダル入力 -ユーザー入力に画像またはファイルが含まれる場合は、`question` の代わりに `message`（配列）を渡します。各配列要素はコンテンツブロックです： +ユーザー入力に画像またはファイルが含まれる場合は、`question` の代わりに `message`（配列）を渡します。各配列要素はコンテンツブロックです。 ```json { @@ -268,28 +268,28 @@ while (true) { サポートされるブロックタイプ： -- `text` — 通常のテキスト。`text` フィールドが必須です。 -- `image_url` — 画像。`image_url.url` が必須です。 -- `file_url` — ファイル（PDF、CSV、TXT など）。`file_url.url` が必須です。 +- `text` — 通常のテキスト。`text` フィールドは必須です。 +- `image_url` — 画像。`image_url.url` は必須です。 +- `file_url` — ファイル（PDF、CSV、TXT など）。`file_url.url` は必須です。 ### v1 の `references` との関係 -旧クライアントとの互換性のため、v2 でも引き続き `references: ["https://...", ...]` フィールドを認識します： -- URL の末尾が `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif` の場合、自動的に `image_url` ブロックへ変換します； -- その他の拡張子は `file_url` ブロックへ変換します； -- さらに同時に `question` が提供されている場合は、それを `text` ブロックとして先頭に配置します。 +旧クライアントとの互換性のため、v2 でも `references: ["https://...", ...]` フィールドを認識します。 +- URL の拡張子が `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif` の場合、自動的に `image_url` ブロックに変換されます。 +- その他の拡張子は `file_url` ブロックに変換されます。 +- さらに `question` も同時に提供されている場合は、それを先頭の `text` ブロックとして追加します。 -したがって、v1 から移行したいだけでリクエストボディを変更したくない場合は、パスを `/aichat2/conversations` に置き換えるだけでよく、元の `references` の使い方はそのまま機能します。 +したがって、v1 から移行したいだけでリクエストボディを変更したくない場合は、パスを `/aichat2/conversations` に変更するだけでよく、元の `references` の使い方はそのまま機能します。 -より細かい制御が必要な場合（たとえば複数の画像をテキストの間に配置する、または順序が重要な場合）は、直接 `message` 配列を使用してください。 +より細かい制御が必要な場合（たとえば複数の画像をテキストの間に配置したい、または順序が重要な場合）は、直接 `message` 配列を使用してください。 ## ツール呼び出しと MCP -v2 の中核的な強化点は、モデルがツールを自律的に呼び出して複数ステップのタスクを完了できることであり、**これはデフォルトで有効です**。クライアント側でリクエストに追加の設定を行う必要はありません。一般的なシナリオ： +v2 の中核となる強化点は、モデルがツールを自主的に呼び出して複数ステップのタスクを完了できることです。**これはデフォルトで有効**であり、クライアント側でリクエストに追加設定を行う必要はありません。一般的なシナリオ： -- ユーザーが「最近上海でどんな新しい展覧会があるか調べて」→ モデルが組み込みの web search を呼び出す → 結果を整理して回答します。 -- ユーザーが「この PDF を読んで要約を書いて」→ モデルが file_read を呼び出す → 要約を書きます。 -- ユーザーが [Connections](https://platform.acedata.cloud/connections) で Google Drive / GitHub / Notion などを認可済み → モデルが対応する MCP ツールを呼び出してそのデータを読み書きできます。 +- ユーザーが「最近上海でどんな新しい展覧会があるか検索して」→ モデルが組み込みの web search を呼び出す → 結果を整理して回答する。 +- ユーザーが「この PDF を読んで要約を書いて」→ モデルが file_read を呼び出す → 要約を書く。 +- ユーザーが [Connections](https://platform.acedata.cloud/connections) で Google Drive / GitHub / Notion などを認可済み → モデルは対応する MCP ツールを呼び出してそのデータを読み書きできる。 NDJSON / SSE ストリームでは、ツール呼び出しは `tool_use` と `tool_result` の2種類のイベントで表現されます。例： @@ -301,19 +301,19 @@ NDJSON / SSE ストリームでは、ツール呼び出しは `tool_use` と `to ... ``` -フロントエンドでツール呼び出しの詳細を表示したくない場合は、`tool_use` / `tool_result` / `card` / `citation` といったイベントを無視すればよく、モデルの最終出力は引き続き `text_delta` を通じてストリーミングされます。 +フロントエンドでツール呼び出しの詳細を表示したくない場合は、`tool_use` / `tool_result` / `card` / `citation` のこれらのイベントを無視すればよく、モデルの最終出力は引き続き `text_delta` を通じてストリーミングされます。 -`max_turns` では、今回のリクエスト内でモデルが自らツールを呼び出せる最大ラウンド数を制限できます。デフォルトの上限はプラットフォームによって決まります。これを小さく設定する（たとえば `max_turns: 1`）ことで、単一の回答を強制し、ツール呼び出しを一切許可しないようにできます。 +`max_turns` で、このリクエスト内でモデルがツールを自己呼び出しできる最大ラウンド数を制限できます。範囲は 1～500 で、省略時はデフォルトで 500 です。これを小さく設定する（たとえば `max_turns: 1`）ことで、単一回答を強制し、ツール呼び出しを一切許可しないことができます。 ## 非同期実行と無人認可 -呼び出し元がアラート Webhook、CI/CD、監視システム、またはその他のバックグラウンドタスクである場合、`async: true` を設定すると、インターフェースは直ちにタスク ID を返し、バックグラウンドで実行を継続します： +呼び出しがアラート Webhook、CI/CD、監視システム、またはその他のバックグラウンドタスクからのものである場合、`async: true` を設定すると、インターフェースは直ちにタスク ID を返し、バックグラウンドで実行を継続します： ```json { "model": "gpt-5.5", "async": true, - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "私のサービスでアラートが発生しました。個人用 WeChat を使って WeChat グループ「AceDataCloudチーム」に通知して……" } ``` @@ -328,9 +328,9 @@ NDJSON / SSE ストリームでは、ツール呼び出しは `tool_use` と `to } ``` -その後、`action: retrieve` + `id` を使用して会話結果を照会できます；また、`callback_url` を提供することもでき、タスク完了後にプラットフォームが `{ status, answer, usage, error }` をコールバックアドレスへ POST します。`callback_url` は `http` / `https` を使用する必要があり、`localhost` またはプライベート IP のリテラルアドレスを直接指定することはできません。 +その後、`action: retrieve` + `id` を使用して会話結果を照会できます。`callback_url` を提供することもでき、タスク完了後にプラットフォームは `{ status, answer, usage, error }` をコールバックアドレスへ POST します。`callback_url` は `http` / `https` を使用する必要があり、`localhost` またはプライベート IP のリテラルアドレスを直接指定することはできません。 -バックグラウンドタスクでは通常、確認をクリックできる人がいません。特定の Skill または MCP Server に無人モードで送信、公開、書き込みなどのアクションを実行させたい場合は、リクエストボディで事前認可リストを明示的に渡してください： +バックグラウンドタスクでは通常、誰も確認をクリックできません。特定の Skill または MCP Server に無人モードで送信、公開、書き込みなどのアクションを実行させたい場合は、リクエストボディで明示的に事前認可リストを渡してください： ```json { @@ -338,13 +338,13 @@ NDJSON / SSE ストリームでは、ツール呼び出しは `tool_use` と `to "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "私のサービスでアラートが発生しました。個人用 WeChat を使って WeChat グループ「AceDataCloudチーム」に通知して……" } ``` -`allowed_skills` 内の値は、接続済み Skill の slug です；`allowed_mcp_servers` 内の値は、接続済み MCP Server の slug です。事前認可リストに含まれていない Skill / MCP Server は、無人モードでは引き続きプレビュー、dry-run、または書き込み操作の実行拒否のみとなります。 +`allowed_skills` 内の値は、接続済み Skill の slug です。`allowed_mcp_servers` 内の値は、接続済み MCP Server の slug です。事前認可に含まれていない Skill / MCP Server は、無人モードでは引き続きプレビュー、dry-run、または書き込み操作の実行拒否しかできません。 -より細かな制御が必要な場合は、同等の `unattended_policy` オブジェクトを使用することもできます： +より細かい制御が必要な場合は、同等の `unattended_policy` オブジェクトを使用することもできます： ```json { @@ -356,26 +356,26 @@ NDJSON / SSE ストリームでは、ツール呼び出しは `tool_use` と `to } ``` -事前認可とはこの2つのリスト自体のことです：リストが空であれば、いかなる機能も認可されません。追加のスイッチフィールドは不要です。 +事前認可とは、この2つのリスト自体です。リストが空であれば、いかなる能力も認可されず、追加のスイッチフィールドは不要です。 -注意：事前認可は「今回のリクエストで、これらの機能が無人モードにおいて人による確認をスキップすることを許可する」ことのみを意味します。具体的な Skill は依然として `--unattended-confirm` または対応するセキュリティ機構をサポートしている必要があります；そうでなければ、引き続き dry-run となり、書き込み操作が直接実行されることはありません。 +注意：事前認可は、「今回のリクエストでは、これらの能力が無人モードで人による確認をスキップすることを許可する」ことのみを意味します。具体的な Skill は依然として `--unattended-confirm` または対応するセキュリティメカニズムをサポートしている必要があります。そうでない場合は、引き続き dry-run となり、書き込み操作を直接実行しません。 -## 一時停止した会話を再開する +## 一時停止した会話の再開 -一部のツールでは、モデルが「ユーザーに質問を返す」ことがあり、その際モデルは `ask_user_question` イベントを発行し、会話は `awaiting_user_input` 状態で凍結されます： +一部のツールはモデルに「ユーザーへ質問を返す」ことをさせます。このときモデルは `ask_user_question` イベントを発行し、会話は `awaiting_user_input` 状態でフリーズします： ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "你希望生成的报告是中文还是英文？", - "options": ["中文", "英文"], + "question": "生成するレポートは中国語と英語のどちらを希望しますか？", + "options": ["中国語", "英語"], "id": "f2f4b3e8-..." } ``` -フロントエンドでこのイベントをカードとしてレンダリングし、ユーザーに回答を選択させた後、同じ `id` を使用して次のリクエストを開始し、回答を `tool_results` 経由で返します： +フロントエンドでこのイベントをカードとしてレンダリングし、ユーザーに回答を選ばせます。その後、同じ `id` を使用して次のリクエストを開始し、回答を `tool_results` を通じて返します： ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -389,21 +389,21 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ "tool_results": [ { "tool_use_id": "toolu_01XYZW", - "output": "中文" + "output": "中国語" } ] }' ``` -リクエストボディ内の `tool_use_id` は、一時停止時の `tool_id` と**完全に**一致している必要があります；一致しない場合は 400 が返されます。リクエスト内に `tool_results` が同時に存在する場合、`question` / `message` / `references` はすべて無視されます。 +リクエストボディ内の `tool_use_id` は、一時停止時の `tool_id` と**完全に一致**している必要があります。一致しない場合は 400 が返されます。リクエスト内に `tool_results` が同時に存在する場合、`question` / `message` / `references` はすべて無視されます。 -ユーザーがこの質問を放棄することを決めた場合は、新しい `question` / `message` を直接渡せばよく、プラットフォームは一時停止中のツール呼び出しを自動的に「ユーザーがスキップ」とマークします。 +ユーザーがこの質問を放棄することにした場合は、新しい `question` / `message` を直接渡せばよく、プラットフォームは一時停止したツール呼び出しを自動的に「ユーザーがスキップ」とマークします。 ## 会話管理（CRUD） -v2 では、同じ endpoint 上で `action` フィールドを通じて軽量な会話管理を提供しており、別途 API を用意する必要はありません。 +v2 は同じ endpoint 上で `action` フィールドを通じて軽量な会話管理を提供しており、別途 API を開設する必要はありません。 +### `action: retrieve` —— 会話を取得する -### `action: retrieve` —— 会話を1件取得する ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -完全な会話ドキュメント（`messages` 履歴、`model`、`title`、`tools_used` などを含む）を返します。 +完全な会話ドキュメント（`messages` の履歴、`model`、`title`、`tools_used` などを含む）を返します。 -### `action: retrieve_batch` —— 会話サマリーを一覧表示 +### `action: retrieve_batch` —— 会話の概要を一覧表示する ```json { @@ -428,11 +428,11 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -`{ items: [...], total }` を返します。**サマリーには `messages` は含まれません**。サイドバーの一覧に適しています。ユーザーが特定の会話を開いた場合は、`action: retrieve` を使用してその完全なメッセージを個別に取得します。 +`{ items: [...], total }` を返します。**概要には `messages` は含まれません**。サイドバーのリストに適しています。ユーザーがある会話を開いた場合は、`action: retrieve` を使用してその完全なメッセージを個別に取得します。 -任意のフィルターパラメーター：`user_id`、`application_id`、`model_group`、`model`。 +任意のフィルターパラメータ：`user_id`、`application_id`、`model_group`、`model`。 -### `action: update` —— タイトルの変更または履歴の書き換え +### `action: update` —— タイトルを変更する、または履歴を書き換える ```json { @@ -442,9 +442,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -`messages` も渡せますが、サーバー側で厳格な schema 検証が行われます（折りたたまれた `ToolUseContent` 形式である必要があります）。条件に合わない場合は 400 が返されます。通常は `title` の変更にのみ使用することを推奨します。 +`messages` も渡せますが、サーバー側で厳格な schema 検証が行われます（折りたたまれた `ToolUseContent` 形式である必要があります）。条件を満たさない場合は 400 が返されます。通常は `title` の変更にのみ使用することを推奨します。 -### `action: delete` —— 会話を1件削除 +### `action: delete` —— 会話を1件削除する ```json { @@ -453,21 +453,21 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -`{ id, success: true }` を返します。削除後は復元できないため、確認してから呼び出してください。 +`{ id, success: true }` を返します。削除後は復元できません。確認してから呼び出してください。 ## v1 からのスムーズな移行 -すでに [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) を使用している場合、v2 への移行にはほとんどコード変更が必要ありません： +すでに [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) を使用している場合、v2 への移行ではほとんどコードを変更する必要がありません： 1. URL を `https://api.acedata.cloud/aichat/conversations` から `https://api.acedata.cloud/aichat2/conversations` に変更します。 -2. 以前に v1 のモデル名（`gpt-3.5`、`gpt-4-browsing` など）を渡していた場合は、v2 への切り替え時に現代的なモデル（`gpt-5.4`、`claude-opus-4-8`、`gemini-3.1-pro-preview` など）へアップグレードすることを推奨します。 -3. NDJSON ストリームのフィールドは後方互換性を維持しています。各 `text_delta` イベントには引き続き `delta_answer` と `id` が含まれるため、従来行単位で `delta_answer` を解析していたクライアントは変更不要です。 +2. 以前に v1 のモデル名（例：`gpt-3.5`、`gpt-4-browsing` など）を渡していた場合は、v2 への切り替え時に現行世代のモデル（例：`gpt-5.4`、`claude-opus-4-8`、`gemini-3.1-pro-preview` など）へアップグレードすることを推奨します。 +3. NDJSON ストリームのフィールドは後方互換性を維持しています。各 `text_delta` イベントには引き続き `delta_answer` と `id` が含まれるため、行ごとに `delta_answer` を解析する既存のクライアントは変更不要です。 -移行後は必要に応じて v2 の新機能（マルチモーダル `message`、SSE、ツール呼び出し、`action` CRUD）を有効にし、段階的に進めることができます。 +移行後は、必要に応じて v2 の新機能（マルチモーダル `message`、SSE、ツール呼び出し、`action` CRUD）を有効にし、段階的に進めることができます。 ## エラー処理 -エラーレスポンスは統一して以下の形式です： +エラーレスポンスは以下の形式に統一されています： ```json { @@ -479,16 +479,16 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -よくあるエラー： +一般的なエラー： -- `400 bad_request`：必須フィールドの欠落、`tool_use_id` の不一致、`messages` schema の不正など。 +- `400 bad_request`：必須フィールドの不足、`tool_use_id` の不一致、`messages` schema の不正など。 - `401 invalid_token`：`authorization` ヘッダーが正しくありません。 -- `404 not_found`：`action: retrieve / update / delete` 実行時に、`id` に対応する会話が存在しません。 -- `429 too_many_requests`：レート制限に達しました。 -- `500 chat_error`：上流 LLM のエラー、またはこのラウンドの `completion_tokens=0`（未消費として扱われ、課金されません）。 +- `404 not_found`：`action: retrieve / update / delete` 時に、`id` に対応する会話が存在しません。 +- `429 too_many_requests`：レート制限が発動しました。 +- `500 chat_error`：上流の LLM エラー、またはこのターンの `completion_tokens=0`（未消費として処理され、課金されません）。 ストリーミングレスポンスでは、エラーは `{"type":"error","message":"..."}` イベントとして送信され、その直後にストリームが終了します。 ## 結論 -AI Chat v2 API は、v1 との後方互換性を保ちながら、対話を「単発 / 複数ターンの質疑応答」から「Agent 化された観測可能な対話」へとアップグレードします：マルチモーダル入力、ツール呼び出し、一時停止 / 再開、ストリーミング構造化イベント、組み込み CRUD。新規導入では直接 v2 を使用することを推奨します。既存の v1 統合は段階的にスムーズに移行できます。ご不明な点がございましたら、いつでも技術サポートチームまでお問い合わせください。 +AI Chat v2 API は v1 との後方互換性を維持しながら、会話を「単一ターン / 複数ターンのQ&A」から「Agent 化された観測可能な会話」へとアップグレードします：マルチモーダル入力、ツール呼び出し、一時停止 / 再開、ストリーミング構造化イベント、組み込み CRUD。新規導入では v2 を直接使用することを推奨します。既存の v1 統合は段階的にスムーズに移行できます。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。 diff --git a/ja/guides/platform/hermes_managed.mdx b/ja/guides/platform/hermes_managed.mdx index 0e8ffd9f2..941d785c8 100644 --- a/ja/guides/platform/hermes_managed.mdx +++ b/ja/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent プライベートデプロイ" +title: "Hermes デプロイ" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud は Hermes Agent プライベートデプロイの入口を提供します。この入口は制御されたサービスであり、利用可能かどうかおよび選択可能なリソースは、コンソールに現在表示されている内容に基づきます。 +各 Application ごとに独立した Hermes コンテナインスタンスを作成します。デフォルトでは固定リリースバージョンのベースイメージを使用し、ネイティブ機能を保持します。プラットフォームは購入、更新、永続ストレージおよびデプロイ管理を提供します。 -## 使用手順 +## 作成と購入 -1. プラットフォームで **Hermes Agent プライベートデプロイ** を見つけます。 -2. ページの指示に従って利用可能な構成を選択し、サービスを作成します。 -3. プラットフォームが準備完了の状態を表示するのを待ちます。 -4. ページで提供された入口と認証情報を使用してインスタンスにアクセスします。 -5. まず `Reply only OK` を送信し、その後に実際のタスクを開始します。 +1. [Hermes デプロイ](https://platform.acedata.cloud/services/hermes) を開き、Application を作成します。 +2. 購入ページで期間プランを選択し、支払いを完了します。 +3. 設定ページに戻り、ドロップダウンリストからプラットフォームのチャットモデルを選択し、現在のモデル価格を確認できます。プラットフォームはこのインスタンス用に独立した API 認証情報を作成します。プラットフォーム接続をオフにして、ネイティブコンソールで自身で設定することもできます。 +4. アクセス認証情報を自動生成するか、自身の強力なパスワード/Token を設定し、確認後にデプロイを開始します。アクセス認証情報とモデル API 認証情報は互いに独立しています。 +5. インスタンスの準備が完了したら、管理ページからアクセスアドレスとログイン認証情報を取得します。 +6. ネイティブコンソールにログインし、自身のモデルプロバイダー、キーおよびチャネルを設定します。 -モデル、認証情報、ストレージ、および削除の動作は、作成ページおよび確認ポップアップに基づきます；ローカルの Hermes チュートリアルにある YAML を直接プラットフォームのデプロイ契約として扱わないでください。削除する前に、保持する必要のあるデータをエクスポートしてください。 +デプロイ料金はプラン期間に応じて課金され、具体的な米ドル価格と期間は購入ページに準じます。モデル呼び出し料金は別途かかります。デプロイ期間を購入してもモデル利用枠は付与されません。プラットフォーム接続を有効にした場合、専用 API 認証情報では選択したモデルに対応するチャットインターフェースのみが公開され、呼び出しはプラットフォーム残高から別途課金されます。各 Application はそれぞれ購入、更新および管理します。 -コンソールに作成入口が表示されていない場合、現在のアカウントではこのサービスが開放されていないことを示します。その場合は、[Hermes インタラクティブウィザード](https://platform.acedata.cloud/documents/hermes-wizard-integration) または [手動構成](https://platform.acedata.cloud/documents/hermes-manual-integration) を利用してください。 +## パスワード、認証情報および後続設定 + +アクセス認証情報は初回起動前に設定されます。自動生成方式ではランダムな認証情報を使用し、カスタムパスワードは少なくとも 16 文字、OpenClaw Token は少なくとも 32 文字必要です。下書きにはパスワードは保存されません。ページを切り替えた後、再入力が必要になる場合があります。デプロイ後、アクセス認証情報を確認できるのは Application 所有者と管理者のみです。 + +各インスタンスのモデル API 認証情報は共有されず、デプロイの更新に伴って有効期限が延長され、インスタンス削除時に取り消されます。デプロイ初期化後は、ネイティブコンソールでモデルとチャネルを変更してください。他サービスのモデルに変更する場合は、先にプラットフォームの認証情報管理で対応するインターフェースの認可を調整するか、対応する認証情報を使用してください。通常の再デプロイではネイティブ設定は上書きされません。公開検証を通過していないデプロイ環境は、新規デプロイを一時的に拒否します。サポートにお問い合わせください。 + +## バージョンとデータ + +設定ページには現在リリースされているイメージバージョンが表示されます。新規インスタンスはサービスの現在のリリースバージョンを使用します。既存インスタンスはカタログ更新に伴って自動的に置き換えられません。再デプロイでは現在のサービスバージョンが適用されるため、事前にバックアップを取り、使用するバージョンのアップグレード要件を確認してください。 + +各インスタンスにはデフォルトで 1 CPU、2 GiB のメモリ上限、および 10 GiB の永続ストレージが提供されます。再起動してもインスタンスデータは保持されます。デプロイを能動的に削除した場合、または期限切れで回収された場合はストレージが削除されるため、保持が必要なデータは事前にエクスポートしてください。 + +## 更新と期限切れ + +現在の Application の購入ページで更新すると、有効期限はプラットフォームの既存の期間ルールに従って延長されます。期限切れ後はアクセス入口が一時停止し、猶予期間内に更新すればアクセスが復元されます。猶予期間を超えるとインスタンスとデータが回収されます。管理ページの期限日時、課金ステータスおよび削除通知に従ってください。 + +## 管理画面へのログイン + +デプロイ管理ページで Dashboard アドレス、ユーザー名 `admin` およびパスワードをコピーし、開いてログインします。ログイン情報は、その Application の所有者およびプラットフォーム管理者にのみ提供されます。モデル、スキルおよびチャネルは Hermes のネイティブ画面で設定します。 + +## よくある質問 + +- **なぜ新しいインスタンスはまだ応答できないのですか？** デプロイ完了はコンテナの準備が完了したことを意味します。使用を開始するには、ネイティブ画面でモデルと認証情報を設定する必要があります。 +- **追加プラグインまたはモデル fallback はプリインストールされていますか？** デフォルトでは追加されません。必要に応じてネイティブ画面で設定してください。 +- **既存インスタンスはどのように更新しますか？** 既存の Application と注文は保持され、再デプロイ時には現在のサービスバージョンが使用されます。アップグレード前にデータをバックアップし、バージョン互換性を確認してください。 +- **起動に失敗した場合はどうすればよいですか？** まずデプロイログとイベントを確認し、インスタンスの準備完了後にモデルを設定してください。公開コメントやスクリーンショットでインスタンスのパスワードやキーを公開しないでください。 diff --git a/ja/guides/platform/wework_bot.mdx b/ja/guides/platform/wework_bot.mdx deleted file mode 100644 index c57ecc1c9..000000000 --- a/ja/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/ko/guides/aichat/aichat2_conversations.mdx index 88196f07c..2d8ea60cf 100644 --- a/ko/guides/aichat/aichat2_conversations.mdx +++ b/ko/guides/aichat/aichat2_conversations.mdx @@ -3,32 +3,32 @@ title: "AI Chat v2 API 연동 안내" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API(`/aichat2/conversations`)는 차세대 대화 인터페이스이며, [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations)의 전면 업그레이드 버전입니다. v1의 간결하고 관리형인 멀티턴 대화 기반 위에 다음을 확장했습니다: +AI Chat v2 API(`/aichat2/conversations`)는 차세대 대화 인터페이스이며, [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations)의 전면 업그레이드 버전입니다. v1의 간결하고 관리형인 다중 턴 대화 기반 위에 다음 기능을 확장했습니다: -- **멀티모달 사용자 입력**: 구조화된 `message` 필드를 통해 텍스트 + 이미지 + 파일 블록을 직접 전달하며, 먼저 `references`를 사용해 간접적으로 첨부할 필요가 없습니다. -- **Agent화된 도구 호출**: 웹 검색, 웹페이지 크롤링, 파일 읽기 등의 도구 세트가 내장되어 있으며, 사용자가 승인한 MCP 서버(Google Drive, Notion, Slack, GitHub 등)를 연결할 수 있습니다. 모델은 한 번의 요청 안에서 여러 차례 자율적으로 도구를 호출하여 복잡한 작업을 완료할 수 있습니다. -- **구조화된 스트리밍 이벤트**: `accept: text/event-stream` 또는 `application/x-ndjson`를 통해 토큰별 `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` 등의 이벤트를 받을 수 있어, 프런트엔드에서 해당 유형에 따라 각각 렌더링하기 편리합니다. -- **중단 / 재개 가능**: 모델이 사용자의 추가 정보가 필요할 때 `ask_user_question` 이벤트를 발행하고 일시 정지합니다. 다음 호출에서 `tool_results`를 통해 답변을 다시 채우면 계속 진행할 수 있습니다. -- **새로운 CRUD 동작**: 동일한 endpoint에서 `action` 필드를 통해 `retrieve` / `retrieve_batch` / `update` / `delete`를 완료할 수 있으며, 별도의 세션 관리 API가 필요하지 않습니다. -- **지속적으로 업데이트되는 모델 목록**: 기본적으로 GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 등 최신 모델이 연동됩니다. +- **멀티모달 사용자 입력**: 구조화된 `message` 필드를 통해 텍스트 + 이미지 + 파일 블록을 직접 전달할 수 있으며, 더 이상 `references`를 통해 간접적으로 첨부할 필요가 없습니다. +- **Agent화 도구 호출**: 인터넷 검색, 웹페이지 크롤링, 파일 읽기 등의 도구 세트가 내장되어 있으며, 사용자가 승인한 MCP 서버(Google Drive, Notion, Slack, GitHub 등)를 연결할 수도 있습니다. 모델은 하나의 요청에서 여러 차례 자율적으로 도구를 호출하여 복잡한 작업을 완료할 수 있습니다. +- **구조화된 스트리밍 이벤트**: `accept: text/event-stream` 또는 `application/x-ndjson`를 통해 토큰 단위의 `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` 등의 이벤트를 받을 수 있어, 프런트엔드에서 해당 유형별로 각각 렌더링하기 편리합니다. +- **중단 / 재개 가능**: 모델이 사용자에게 추가 정보가 필요할 때 `ask_user_question` 이벤트를 발생시키고 일시 중지합니다. 다음 호출에서 `tool_results`를 통해 답변을 다시 채우면 계속 진행할 수 있습니다. +- **신규 CRUD 작업**: 동일한 endpoint에서 `action` 필드를 통해 `retrieve` / `retrieve_batch` / `update` / `delete`를 완료할 수 있으며, 별도의 대화 관리 API가 필요 없습니다. +- **지속적으로 업데이트되는 모델 목록**: 기본적으로 GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 등의 최신 모델을 지원합니다. 동시에 요청 본문 수준에서 **v1과 완전히 하위 호환**됩니다. `model` + `question`(+ 선택적 `stateful` / `id` / `references` / `preset`)만 전달하면 v1과 동등한 `{answer, id}` JSON 응답을 받을 수 있으므로, `/aichat/conversations`에서 마이그레이션할 때 클라이언트를 다시 작성할 필요 없이 경로만 `/aichat2/conversations`로 변경하면 됩니다. -> 현재 `/aichat/conversations`를 사용하고 있다면, 기존 인터페이스 서비스는 계속 유지되며 원하는 속도에 맞춰 마이그레이션할 수 있습니다. +> 현재 `/aichat/conversations`를 사용 중이라면, 이전 인터페이스도 계속 서비스되므로 원하는 속도에 맞춰 마이그레이션할 수 있습니다. ## 신청 절차 -AI Chat v2 API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 발급받아 예비로 보관하세요. +AI Chat v2 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)에서 공용 잔액을 충전할 수 있습니다. > 📘 전체 문서: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) -## 기본 사용법 +## 기본 사용 가장 간단한 사용법은 v1과 완전히 동일합니다: `model` + `question`을 전달하고 `{answer, id}`를 받습니다. @@ -88,9 +88,9 @@ print(response.json()) 구체적인 과금 규칙은 서비스 페이지의 Pricing 카드에서 확인하세요. -## 멀티턴 대화 +## 다중 턴 대화 -v1과 마찬가지로 `stateful: true`를 전달하여 세션 저장을 활성화하면 API가 `id`를 반환합니다. 후속 요청에서 `id`를 다시 전달하면 직접 messages 히스토리를 관리하지 않아도 대화를 계속할 수 있습니다. +v1과 마찬가지로 `stateful: true`를 전달하여 대화 저장을 활성화하면 API가 `id`를 반환합니다. 이후 요청에서 `id`를 다시 전달하면 직접 messages 기록을 유지할 필요 없이 대화를 계속할 수 있습니다. 첫 번째 요청: @@ -115,7 +115,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -두 번째 요청에서는 동일한 `id`를 함께 전달합니다: +두 번째 요청에서 동일한 `id`를 함께 전달합니다: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -136,7 +136,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful`의 기본값은 `true`이며, 생략하는 것은 명시적으로 `true`를 전달하는 것과 동일합니다. 서버가 이번 대화를 저장하지 않기를 원한다면, 명시적으로 `stateful: false`를 설정할 수 있습니다. +> `stateful`의 기본값은 `true`이며, 생략하는 것은 명시적으로 `true`를 전달하는 것과 동일합니다. 서버가 이번 대화를 저장하지 않기를 원한다면, `stateful: false`를 명시적으로 설정할 수 있습니다. ## 스트리밍 응답 @@ -144,9 +144,9 @@ v2는 두 가지 스트리밍 형식을 지원하며, `accept` 헤더에 따라 | 시나리오 | `accept` | 데이터 형태 | | --------------------- | ---------------------- | ------------------------------------------ | -| Web 프론트엔드 / EventSource | `text/event-stream` | `data: {json}\n\n`, 마지막 줄은 `data: [DONE]\n\n` | -| 서버 / CLI / Node 스트리밍 파싱 | `application/x-ndjson` | 줄마다 하나의 JSON 객체 | -| 스트리밍이 필요하지 않음 | `application/json`（기본값） | 한 번에 `{answer, id}` 반환 | +| Web 프런트엔드 / EventSource | `text/event-stream` | `data: {json}\n\n`, 마지막 줄은 `data: [DONE]\n\n` | +| 서버 / CLI / Node 스트리밍 파싱 | `application/x-ndjson` | 한 줄당 하나의 JSON 객체 | +| 스트리밍 불필요 | `application/json`（기본값） | 한 번에 `{answer, id}` 반환 | ### NDJSON 예시 @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -NDJSON의 각 줄은 모두 구조화된 이벤트이며, 가장 일반적인 것은 `text_delta`입니다: +NDJSON의 각 줄은 모두 구조화된 이벤트이며, 가장 흔한 것은 `text_delta`입니다: ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +195,7 @@ NDJSON의 각 줄은 모두 구조화된 이벤트이며, 가장 일반적인 ### SSE 예시 -브라우저 측에서 `EventSource`를 사용할 경우 사용자 지정 요청 본문을 지원하지 않으므로, `fetch` + 수동으로 `\n\n` 기준 슬라이싱 파싱을 사용하는 것을 권장합니다: +브라우저에서 `EventSource`를 사용할 경우 사용자 지정 요청 본문을 지원하지 않으므로, `fetch` + 수동으로 `\n\n` 분할 파싱을 사용하는 것을 권장합니다: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +236,24 @@ while (true) { | `type` | 의미 | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | 어시스턴트 답변의 증분 텍스트 조각입니다. `content`는 새로 추가된 내용입니다. v1 호환을 위해 동일 이벤트에 `delta_answer`(`content`와 같음) 및 `id`도 함께 포함됩니다. | +| `text_delta` | 어시스턴트 답변의 증분 텍스트 조각입니다. `content`는 새로 추가된 내용입니다. v1 호환을 위해 동일한 이벤트에 `delta_answer`(`content`와 동일)와 `id`도 포함됩니다. | | `thinking` | 모델의 사고 과정입니다(선택한 모델이 reasoning을 노출하는 경우에만 나타남). | | `tool_use` | 모델이 도구 호출을 결정하며, 이벤트에는 `tool_id`, `tool_name`, `input`이 포함됩니다. | -| `tool_result` | 도구 실행 결과이며, 이전 `tool_use`와 `tool_id`를 통해 연결됩니다. `is_error`는 실패 여부를 나타냅니다. | +| `tool_result` | 도구 실행 결과이며, 이전 `tool_use`와 `tool_id`를 통해 쌍을 이룹니다. `is_error`는 실패 여부를 나타냅니다. | | `card` | 도구가 생성한 구조화된 카드(예: 이미지, 링크 미리보기)로, 직접 렌더링하기에 적합합니다. | -| `citation` | 해당 텍스트 조각 인용의 출처 URL을 보충하는 데 사용됩니다. | +| `citation` | 해당 텍스트 조각의 인용을 보완하는 소스 URL에 사용됩니다. | | `ask_user_question` | 모델이 사용자에게 추가 정보를 요청할 때 발생하며, 대화는 `awaiting_user_input` 상태로 진입합니다. 자세한 내용은 아래 [일시 중지된 대화 재개](#恢复暂停的对话)를 참조하세요. | -| `artifact` | 모델이 생성한 독립 산출물(예: 코드 블록, 문서)로, 저장하거나 다운로드할 수 있습니다. | -| `system_message` | 시스템 안내 정보(사용자 및 어시스턴트 콘텐츠가 아님)로, UI 안내용으로만 사용됩니다. | -| `compact` | 내부 컨텍스트가 압축된 이벤트로, 특별한 처리가 필요하지 않습니다. | -| `error` | 이번 라운드에서 오류가 발생했으며, `message`가 오류 내용을 설명합니다. | -| `done` | 스트리밍 응답이 종료되며, `usage`(`prompt_tokens` / `completion_tokens` / `total_tokens` 포함) 및 `terminal_reason`을 포함합니다. | +| `artifact` | 모델이 생성한 독립적인 산출물(예: 코드 블록, 문서)로, 저장하거나 다운로드할 수 있습니다. | +| `system_message` | 시스템 안내 메시지(사용자 및 어시스턴트 콘텐츠 아님)로, UI 안내에만 사용됩니다. | +| `compact` | 내부 컨텍스트가 압축되었음을 나타내는 이벤트로, 특별한 처리가 필요하지 않습니다. | +| `error` | 이번 턴에서 오류가 발생했으며, `message`가 오류 내용을 설명합니다. | +| `done` | 스트리밍 응답이 종료되며, `usage`(`prompt_tokens` / `completion_tokens` / `total_tokens` 포함)와 `terminal_reason`을 포함합니다. | -최종 답변에만 관심이 있는 클라이언트의 경우, 모든 `text_delta`의 `content`를 이어 붙이면 `application/json` 모드의 `answer`와 동일합니다. +최종 답변에만 관심 있는 클라이언트의 경우, 모든 `text_delta`의 `content`를 이어 붙이면 `application/json` 모드의 `answer`와 동일합니다. ## 멀티모달 입력 -사용자 입력에 이미지 또는 파일이 포함된 경우, `question` 대신 `message`(배열)를 전달합니다. 각 배열 요소는 하나의 콘텐츠 블록입니다: +사용자 입력에 이미지나 파일이 포함된 경우, `question` 대신 `message`(배열)를 전달합니다. 각 배열 요소는 콘텐츠 블록입니다: ```json { @@ -274,24 +274,24 @@ while (true) { ### v1 `references`와의 관계 -이전 클라이언트와의 호환성을 위해 v2는 여전히 `references: ["https://...", ...]` 필드를 인식합니다: -- URL 접미사가 `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`이면 자동으로 `image_url` 블록으로 변환됩니다; -- 기타 확장자는 `file_url` 블록으로 변환됩니다; -- 동시에 `question`도 제공된 경우, 이를 하나의 `text` 블록으로 앞에 추가합니다. +기존 클라이언트와의 호환성을 위해, v2는 여전히 `references: ["https://...", ...]` 필드를 인식합니다: +- URL 접미사가 `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`이면 자동으로 `image_url` 블록으로 변환됩니다. +- 기타 확장명은 `file_url` 블록으로 변환됩니다. +- 동시에 `question`도 제공하면, 이를 앞에 배치되는 `text` 블록으로 사용합니다. -따라서 v1에서 마이그레이션만 하고 요청 본문을 수정하고 싶지 않다면, 경로를 `/aichat2/conversations`로 바꾸기만 하면 되며, 기존 `references` 사용법은 그대로 작동합니다. +따라서 v1에서 마이그레이션만 하고 요청 본문을 바꾸고 싶지 않다면 경로를 `/aichat2/conversations`로 바꾸면 되고, 기존 `references` 사용법은 그대로 작동합니다. -더 세밀한 제어가 필요하다면(예: 여러 이미지를 텍스트 사이에 배치하거나 순서가 중요한 경우) 직접 `message` 배열을 사용하세요. +더 정밀한 제어가 필요하다면(예: 여러 이미지를 텍스트 사이에 배치하거나 순서가 중요한 경우) 직접 `message` 배열을 사용하세요. ## 도구 호출 및 MCP -v2의 핵심 강화점은 모델이 도구를 자율적으로 호출하여 여러 단계의 작업을 완료할 수 있다는 것이며, **이는 기본적으로 활성화되어** 있으므로 클라이언트가 요청에서 추가 설정을 할 필요가 없습니다. 일반적인 시나리오: +v2의 핵심 강화점은 모델이 도구를 자율적으로 호출하여 다단계 작업을 완료할 수 있다는 것이며, **이는 기본적으로 활성화되어 있습니다**. 클라이언트가 요청에서 별도의 추가 설정을 할 필요가 없습니다. 일반적인 시나리오: -- 사용자가 「최근 상하이에 어떤 새 전시가 있는지 찾아줘」라고 질문 → 모델이 내장 web search 호출 → 결과를 정리하여 답변. +- 사용자가 「최근 상하이에서 새 전시가 무엇이 있는지 찾아줘」라고 질문 → 모델이 내장 web search 호출 → 결과를 정리하여 답변. - 사용자가 「이 PDF를 읽고 요약을 작성해줘」라고 질문 → 모델이 file_read 호출 → 요약 작성. -- 사용자가 이미 [Connections](https://platform.acedata.cloud/connections)에서 Google Drive / GitHub / Notion 등을 승인함 → 모델이 해당 MCP 도구를 호출하여 데이터를 읽고 쓸 수 있음. +- 사용자가 [Connections](https://platform.acedata.cloud/connections)에서 Google Drive / GitHub / Notion 등을 이미 인증함 → 모델이 해당 MCP 도구를 호출하여 데이터를 읽고 쓸 수 있음. -NDJSON / SSE 스트림에서 도구 호출은 `tool_use` 및 `tool_result` 두 유형의 이벤트로 표시됩니다. 예: +NDJSON / SSE 스트림에서 도구 호출은 `tool_use`와 `tool_result` 두 유형의 이벤트로 표시됩니다. 예: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,19 +301,19 @@ NDJSON / SSE 스트림에서 도구 호출은 `tool_use` 및 `tool_result` 두 ... ``` -프런트엔드에서 도구 호출 세부 정보를 표시하고 싶지 않다면, `tool_use` / `tool_result` / `card` / `citation` 유형의 이벤트를 무시하면 됩니다. 모델의 최종 출력은 여전히 `text_delta`를 통해 스트리밍됩니다. +프런트엔드에서 도구 호출 세부 정보를 표시하고 싶지 않다면 `tool_use` / `tool_result` / `card` / `citation` 유형의 이벤트를 무시하면 됩니다. 모델의 최종 출력은 여전히 `text_delta`를 통해 스트리밍됩니다. -`max_turns`는 이번 요청에서 모델이 도구를 자체 호출할 수 있는 최대 횟수를 제한할 수 있으며, 기본 상한은 플랫폼에서 결정합니다. 이를 작게 설정하면(예: `max_turns: 1`) 단일 답변만 강제하고 어떠한 도구 호출도 허용하지 않을 수 있습니다. +`max_turns`는 이번 요청에서 모델이 도구를 자가 호출할 수 있는 최대 라운드 수를 제한할 수 있으며, 범위는 1–500이고 생략 시 기본값은 500입니다. 이를 작게 설정하면(예: `max_turns: 1`) 단일 답변을 강제하고 어떠한 도구 호출도 허용하지 않을 수 있습니다. ## 비동기 실행 및 무인 승인 -호출이 알림 Webhook, CI/CD, 모니터링 시스템 또는 기타 백그라운드 작업에서 온 경우, `async: true`를 설정하여 인터페이스가 즉시 작업 ID를 반환하고 백그라운드에서 계속 실행되도록 할 수 있습니다: +호출이 경고 Webhook, CI/CD, 모니터링 시스템 또는 기타 백그라운드 작업에서 오는 경우 `async: true`를 설정하여 인터페이스가 즉시 작업 ID를 반환하고 백그라운드에서 계속 실행되도록 할 수 있습니다: ```json { "model": "gpt-5.5", "async": true, - "question": "내 서비스에 알림이 발생했어, 개인 위챗으로 위챗 그룹 「AceDataCloud团队」에 알려줘……" + "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" } ``` @@ -328,9 +328,9 @@ NDJSON / SSE 스트림에서 도구 호출은 `tool_use` 및 `tool_result` 두 } ``` -이후 `action: retrieve` + `id`로 대화 결과를 조회할 수 있습니다; 또는 `callback_url`을 제공할 수도 있으며, 작업 완료 후 플랫폼이 `{ status, answer, usage, error }`를 콜백 주소로 POST합니다. `callback_url`은 반드시 `http` / `https`를 사용해야 하며, `localhost` 또는 사설 IP 리터럴 주소를 직접 입력할 수 없습니다. +이후 `action: retrieve` + `id`를 사용하여 대화 결과를 조회할 수 있습니다. 또는 `callback_url`을 제공할 수도 있으며, 작업 완료 후 플랫폼이 `{ status, answer, usage, error }`를 사용자의 콜백 주소로 POST합니다. `callback_url`은 반드시 `http` / `https`를 사용해야 하며, `localhost` 또는 사설 IP 리터럴 주소를 직접 입력할 수 없습니다. -백그라운드 작업에서는 일반적으로 누군가 확인을 클릭할 수 없습니다. 특정 Skill 또는 MCP Server가 무인 모드에서 전송, 게시, 쓰기 등의 작업을 수행하도록 하려면 요청 본문에 사전 승인 목록을 명시적으로 전달하세요: +백그라운드 작업에는 일반적으로 확인을 클릭할 사람이 없습니다. 특정 Skill 또는 MCP Server가 무인 모드에서 전송, 게시, 쓰기 등의 동작을 수행하도록 하려면 요청 본문에 사전 승인 목록을 명시적으로 전달하세요: ```json { @@ -338,13 +338,13 @@ NDJSON / SSE 스트림에서 도구 호출은 `tool_use` 및 `tool_result` 두 "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "내 서비스에 알림이 발생했어, 개인 위챗으로 위챗 그룹 「AceDataCloud团队」에 알려줘……" + "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" } ``` -`allowed_skills`의 값은 연결된 Skill의 slug입니다; `allowed_mcp_servers`의 값은 연결된 MCP Server의 slug입니다. 사전 승인 목록에 포함되지 않은 Skill / MCP Server는 무인 모드에서 여전히 미리보기, dry-run 또는 쓰기 작업 실행 거부만 할 수 있습니다. +`allowed_skills`의 값은 연결된 Skill의 slug입니다. `allowed_mcp_servers`의 값은 연결된 MCP Server의 slug입니다. 사전 승인 목록에 포함되지 않은 Skill / MCP Server는 무인 모드에서 여전히 미리보기, dry-run 또는 쓰기 작업 실행 거부만 가능합니다. -더 세부적인 제어가 필요하다면 동등한 `unattended_policy` 객체를 사용할 수도 있습니다: +더 세밀한 제어가 필요하다면 동등한 `unattended_policy` 객체를 사용할 수도 있습니다: ```json { @@ -356,21 +356,21 @@ NDJSON / SSE 스트림에서 도구 호출은 `tool_use` 및 `tool_result` 두 } ``` -사전 승인은 이 두 목록 자체입니다: 목록이 비어 있으면 어떠한 기능도 승인하지 않는 것이며, 별도의 스위치 필드는 필요하지 않습니다. +사전 승인은 바로 이 두 목록 자체입니다. 목록이 비어 있으면 어떠한 기능도 승인하지 않는 것이며, 별도의 스위치 필드는 필요하지 않습니다. -주의: 사전 승인은 「이번 요청에서 이러한 기능이 무인 모드로 인간의 확인을 건너뛰도록 허용한다」는 의미일 뿐입니다. 구체적인 Skill은 여전히 `--unattended-confirm` 또는 해당 보안 메커니즘을 지원해야 합니다; 그렇지 않으면 계속 dry-run 상태로 유지되며, 쓰기 작업을 직접 실행하지 않습니다. +주의: 사전 승인은 단지 「이번 요청에서 이러한 기능이 무인 모드에서 수동 확인을 건너뛸 수 있도록 허용한다」는 의미입니다. 구체적인 Skill은 여전히 `--unattended-confirm` 또는 해당 보안 메커니즘을 지원해야 합니다. 그렇지 않으면 계속 dry-run으로 실행되며 쓰기 작업을 직접 수행하지 않습니다. ## 일시 중지된 대화 재개 -일부 도구는 모델이 「사용자에게 되묻게」 하며, 이때 모델은 `ask_user_question` 이벤트를 발행하고 대화는 `awaiting_user_input` 상태로 동결됩니다: +일부 도구는 모델이 「사용자에게 되물을」 수 있게 하며, 이때 모델은 `ask_user_question` 이벤트를 내보내고 대화는 `awaiting_user_input` 상태로 동결됩니다: ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "생성하려는 보고서는 중국어인가요, 영어인가요?", - "options": ["중국어", "영어"], + "question": "你希望生成的报告是中文还是英文？", + "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -요청 본문의 `tool_use_id`는 일시 중지 시의 `tool_id`와 **반드시** 완전히 일치해야 합니다; 일치하지 않으면 400이 반환됩니다. 요청에 `tool_results`가 동시에 존재할 경우, `question` / `message` / `references`는 모두 무시됩니다. +요청 본문의 `tool_use_id`는 일시 중지 시의 `tool_id`와 **반드시** 완전히 일치해야 합니다. 일치하지 않으면 400이 반환됩니다. 요청에 `tool_results`가 동시에 존재할 경우 `question` / `message` / `references`는 모두 무시됩니다. -사용자가 이 질문을 포기하기로 한 경우, 새로운 `question` / `message`를 직접 전달하면 됩니다. 플랫폼은 자동으로 일시 중지된 도구 호출을 「사용자가 건너뜀」으로 표시합니다. +사용자가 이 질문을 포기하기로 했다면, 새로운 `question` / `message`를 직접 전달하면 됩니다. 플랫폼은 일시 중지된 도구 호출을 자동으로 「사용자가 건너뜀」으로 표시합니다. ## 대화 관리(CRUD) v2는 동일한 endpoint에서 `action` 필드를 통해 경량 대화 관리를 제공하므로 별도의 API를 열 필요가 없습니다. - ### `action: retrieve` —— 하나의 대화 가져오기 + ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -완전한 대화 문서(`messages` 기록, `model`, `title`, `tools_used` 등을 포함)를 반환합니다. +완전한 대화 문서를 반환합니다(`messages` 히스토리, `model`, `title`, `tools_used` 등 포함). -### `action: retrieve_batch` —— 대화 요약 나열 +### `action: retrieve_batch` —— 대화 요약 나열하기 ```json { @@ -428,11 +428,11 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -`{ items: [...], total }`을 반환합니다. **요약에는 `messages`가 포함되지 않으므로**, 사이드바 목록에 적합합니다. 사용자가 특정 대화를 열면 `action: retrieve`를 사용하여 해당 대화의 전체 메시지를 별도로 가져옵니다. +`{ items: [...], total }`을 반환합니다. **요약에는 `messages`가 포함되지 않으며**, 사이드바 목록에 적합합니다. 사용자가 특정 대화를 열면 `action: retrieve`를 사용하여 해당 대화의 전체 메시지를 별도로 가져옵니다. -선택적 필터 매개변수: `user_id`, `application_id`, `model_group`, `model`. +선택적 필터 파라미터: `user_id`, `application_id`, `model_group`, `model`. -### `action: update` —— 제목 변경 또는 기록 다시 작성 +### `action: update` —— 제목 변경 또는 히스토리 다시 쓰기 ```json { @@ -442,9 +442,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -`messages`도 전달할 수 있지만, 서버에서 엄격한 schema 검증을 수행합니다(반드시 접힌 `ToolUseContent` 형태여야 함). 조건에 맞지 않으면 400을 반환합니다. 일반적으로는 `title` 변경에만 사용하는 것이 좋습니다. +`messages`도 전달할 수 있지만, 서버는 엄격한 schema 검증을 수행합니다(접힌 `ToolUseContent` 형태여야 함). 조건에 맞지 않으면 400을 반환합니다. 일반적으로는 `title` 변경에만 사용하는 것을 권장합니다. -### `action: delete` —— 대화 하나 삭제 +### `action: delete` —— 하나의 대화 삭제하기 ```json { @@ -453,21 +453,21 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -`{ id, success: true }`를 반환합니다. 삭제 후에는 복구할 수 없으므로, 확인한 후 호출하십시오. +`{ id, success: true }`를 반환합니다. 삭제 후에는 복구할 수 없으므로 확인한 후 호출하세요. ## v1에서 원활하게 마이그레이션하기 -이미 [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations)를 사용하고 있다면, v2로 마이그레이션하는 데는 거의 코드 변경이 필요하지 않습니다. +이미 [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations)를 사용하고 있다면, v2로 마이그레이션하는 데는 거의 코드 수정이 필요하지 않습니다: 1. URL을 `https://api.acedata.cloud/aichat/conversations`에서 `https://api.acedata.cloud/aichat2/conversations`로 변경합니다. -2. 이전에 v1 모델 이름(예: `gpt-3.5`, `gpt-4-browsing` 등)을 전달했다면, v2로 전환할 때 최신 모델(예: `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` 등)로 업그레이드하는 것을 권장합니다. -3. NDJSON 스트림의 필드는 하위 호환성을 유지합니다. 각 `text_delta` 이벤트는 여전히 `delta_answer`와 `id`를 포함하므로, 기존에 줄 단위로 `delta_answer`를 파싱하던 클라이언트는 변경할 필요가 없습니다. +2. 이전에 v1 모델명(예: `gpt-3.5`, `gpt-4-browsing` 등)을 전달했다면, v2로 전환할 때 최신 모델(예: `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` 등)로 업그레이드하는 것을 권장합니다. +3. NDJSON 스트림의 필드는 이전 버전과 호환됩니다. 각 `text_delta` 이벤트는 여전히 `delta_answer`와 `id`를 포함하므로, 기존에 줄 단위로 `delta_answer`를 파싱하던 클라이언트는 수정할 필요가 없습니다. -마이그레이션 후에는 필요에 따라 v2의 새로운 기능(멀티모달 `message`, SSE, 도구 호출, `action` CRUD)을 활성화할 수 있으며, 일정에 맞춰 진행하면 됩니다. +마이그레이션 후에는 필요에 따라 v2의 새로운 기능(멀티모달 `message`, SSE, 도구 호출, `action` CRUD)을 활성화하면 되며, 일정에 맞춰 진행하면 됩니다. ## 오류 처리 -오류 응답은 다음 형식으로 통일됩니다. +오류 응답은 다음 형식으로 통일됩니다: ```json { @@ -481,14 +481,14 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ 일반적인 오류: -- `400 bad_request`: 필수 필드 누락, `tool_use_id` 불일치, `messages` schema 오류 등. -- `401 invalid_token`: `authorization` 헤더가 올바르지 않음. -- `404 not_found`: `action: retrieve / update / delete` 시 `id`에 해당하는 대화가 존재하지 않음. -- `429 too_many_requests`: 속도 제한이 발생함. -- `500 chat_error`: 업스트림 LLM 오류 또는 이번 라운드에서 `completion_tokens=0`(미사용으로 처리되며 비용이 차감되지 않음). +- `400 bad_request`: 필수 필드 누락, `tool_use_id` 불일치, `messages` schema가 유효하지 않은 경우 등. +- `401 invalid_token`: `authorization` 헤더가 올바르지 않은 경우. +- `404 not_found`: `action: retrieve / update / delete` 시 `id`에 해당하는 대화가 존재하지 않는 경우. +- `429 too_many_requests`: 속도 제한이 트리거된 경우. +- `500 chat_error`: 업스트림 LLM 오류 또는 이번 라운드의 `completion_tokens=0`(미사용으로 처리되며 비용이 청구되지 않음). -스트리밍 응답에서는 오류가 `{"type":"error","message":"..."}` 이벤트로 전송되며, 이어서 스트림이 종료됩니다. +스트리밍 응답에서 오류는 `{"type":"error","message":"..."}` 이벤트로 전송되며, 이어서 스트림이 종료됩니다. ## 결론 -AI Chat v2 API는 v1과의 하위 호환성을 유지하면서 대화를 「단일 턴 / 다중 턴 질의응답」에서 「Agent화된 관측 가능한 대화」로 업그레이드합니다. 멀티모달 입력, 도구 호출, 일시 중지 / 재개, 스트리밍 구조화 이벤트, 내장 CRUD를 제공합니다. 새로 연동하는 경우 v2를 바로 사용하는 것을 권장합니다. 기존 v1 통합은 단계적으로 원활하게 마이그레이션할 수 있습니다. 문의 사항이 있으면 언제든지 기술 지원 팀에 연락해 주십시오. +AI Chat v2 API는 v1과의 하위 호환성을 유지하면서 대화를 「단일 라운드 / 다중 라운드 질의응답」에서 「Agent화된 관측 가능한 대화」로 업그레이드합니다: 멀티모달 입력, 도구 호출, 일시 정지 / 재개, 스트리밍 구조화 이벤트, 내장 CRUD. 새로 연동하는 경우 v2를 직접 사용하는 것을 권장합니다. 기존 v1 연동은 단계적으로 원활하게 마이그레이션할 수 있습니다. 문의 사항이 있으시면 언제든지 기술 지원 팀에 연락해 주세요. diff --git a/ko/guides/platform/hermes_managed.mdx b/ko/guides/platform/hermes_managed.mdx index 39477375b..e0e10fc91 100644 --- a/ko/guides/platform/hermes_managed.mdx +++ b/ko/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent 개인 배포" +title: "Hermes 배포" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud는 Hermes Agent 개인 배포 진입점을 제공합니다. 이 진입점은 제어된 서비스로, 사용 가능 여부 및 선택 가능한 리소스는 콘솔 현재 표시를 기준으로 합니다. +각 Application에 대해 독립적인 Hermes 컨테이너 인스턴스를 생성합니다. 기본적으로 고정 릴리스 버전의 기본 이미지를 사용하며, 네이티브 기능을 유지합니다. 플랫폼은 구매, 갱신, 영구 스토리지 및 배포 관리를 제공합니다. -## 사용 단계 +## 생성 및 구매 -1. 플랫폼에서 **Hermes Agent 개인 배포**를 찾습니다. -2. 페이지의 안내에 따라 사용 가능한 구성을 선택하고 서비스를 생성합니다. -3. 플랫폼이 준비 상태를 표시할 때까지 기다립니다. -4. 페이지에서 제공된 진입점과 자격 증명을 사용하여 인스턴스에 접근합니다. -5. 먼저 `Reply only OK`를 전송한 후 실제 작업을 시작합니다. +1. [Hermes 배포](https://platform.acedata.cloud/services/hermes)를 열고 Application을 생성합니다. +2. 구매 페이지에서 기간 패키지를 선택하고 결제를 완료합니다. +3. 구성 페이지로 돌아가 드롭다운 목록에서 플랫폼 채팅 모델을 선택하고, 현재 모델 가격을 확인할 수 있습니다. 플랫폼은 이 인스턴스를 위해 독립적인 API 자격 증명을 생성합니다. 플랫폼 연동을 끄고 네이티브 콘솔에서 직접 구성할 수도 있습니다. +4. 자동 생성 액세스 자격 증명을 선택하거나 자신의 강력한 비밀번호/Token을 설정한 후, 확인하면 배포가 시작됩니다. 액세스 자격 증명과 모델 API 자격 증명은 서로 독립적입니다. +5. 인스턴스가 준비되면 관리 페이지에서 액세스 주소와 로그인 자격 증명을 가져옵니다. +6. 네이티브 콘솔에 로그인하여 자신의 모델 제공업체, 키 및 채널을 구성합니다. -모델, 자격 증명, 저장 및 삭제 행동은 생성 페이지 및 확인 팝업을 기준으로 하며; 로컬 Hermes 튜토리얼의 YAML을 플랫폼 배포 계약으로 직접 사용하지 마십시오. 삭제하기 전에 보존할 데이터를 먼저 내보내십시오. +배포 요금은 패키지 기간에 따라 청구되며, 구체적인 미국 달러 가격과 기간은 구매 페이지를 기준으로 합니다. 모델 호출 요금은 별도이며, 배포 기간을 구매해도 모델 크레딧은 제공되지 않습니다. 플랫폼 연동을 활성화하면 전용 API 자격 증명은 선택한 모델에 해당하는 채팅 인터페이스만 제공하며, 호출은 플랫폼 잔액에서 별도로 청구됩니다. 각 Application은 각각 구매, 갱신 및 관리합니다. -콘솔에 생성 진입점이 표시되지 않으면 현재 계정에서 해당 서비스가 열리지 않은 것이므로 [Hermes 인터랙티브 가이드](https://platform.acedata.cloud/documents/hermes-wizard-integration) 또는 [수동 구성](https://platform.acedata.cloud/documents/hermes-manual-integration)을 사용하십시오. +## 비밀번호, 자격 증명 및 후속 구성 + +액세스 자격 증명은 최초 시작 전에 설정됩니다. 자동 생성 방식은 무작위 자격 증명을 사용하며, 사용자 지정 비밀번호는 최소 16자, OpenClaw Token은 최소 32자여야 합니다. 초안에는 비밀번호가 저장되지 않으며, 페이지를 전환한 후 다시 입력해야 할 수 있습니다. 배포 후에는 Application 소유자와 관리자만 액세스 자격 증명을 확인할 수 있습니다. + +각 인스턴스의 모델 API 자격 증명은 서로 재사용되지 않으며, 배포 갱신에 따라 유효 기간이 연장되고 인스턴스 삭제 시 폐기됩니다. 배포 초기화 후 네이티브 콘솔에서 모델과 채널을 변경하십시오. 다른 서비스의 모델로 변경하는 경우, 먼저 플랫폼 자격 증명 관리에서 해당 인터페이스 권한을 조정하거나 적절한 자격 증명을 사용하십시오. 일반 재배포는 네이티브 설정을 덮어쓰지 않습니다. 게시 검증을 통과하지 않은 배포 환경은 새 배포를 일시적으로 거부하므로 지원팀에 문의하십시오. + +## 버전 및 데이터 + +구성 페이지에는 현재 게시된 이미지 버전이 표시됩니다. 새 인스턴스는 서비스의 현재 게시 버전을 사용하며, 기존 인스턴스는 카탈로그 업데이트에 따라 자동으로 교체되지 않습니다. 재배포하면 현재 서비스 버전이 적용되므로, 먼저 백업하고 사용하는 버전의 업그레이드 요구 사항을 확인하십시오. + +각 인스턴스는 기본적으로 1 CPU, 2 GiB 메모리 제한 및 10 GiB 영구 스토리지를 제공합니다. 재시작해도 인스턴스 데이터는 유지됩니다. 배포를 직접 삭제하거나 만료 후 회수되면 스토리지가 삭제되므로, 보관해야 하는 데이터는 미리 내보내십시오. + +## 갱신 및 만료 + +현재 Application의 구매 페이지에서 갱신하면 유효 기간이 플랫폼의 기존 기간 규칙에 따라 연장됩니다. 만료 후 액세스 진입점이 일시 중지되며, 유예 기간 내에 갱신하면 액세스가 복구됩니다. 유예 기간을 초과하면 인스턴스와 데이터가 회수됩니다. 관리 페이지의 만료 시간, 청구 상태 및 삭제 안내를 기준으로 합니다. + +## 관리 인터페이스 로그인 + +배포 관리 페이지에서 Dashboard 주소, 사용자 이름 `admin` 및 비밀번호를 복사한 후 열어서 로그인합니다. 로그인 정보는 해당 Application의 소유자와 플랫폼 관리자에게만 제공됩니다. 모델, 스킬 및 채널은 Hermes 네이티브 인터페이스에서 구성합니다. + +## 자주 묻는 질문 + +- **왜 새 인스턴스는 아직 응답하지 않나요?** 배포 완료는 컨테이너가 준비되었음을 의미합니다. 사용을 시작하려면 네이티브 인터페이스에서 모델과 자격 증명을 구성해야 합니다. +- **추가 플러그인 또는 모델 fallback이 사전 설치되어 있나요?** 기본적으로 추가하지 않으며, 필요에 따라 네이티브 인터페이스에서 구성합니다. +- **기존 인스턴스는 어떻게 업데이트하나요?** 기존 Application과 주문은 유지되며, 재배포 시 현재 서비스 버전을 사용합니다. 업그레이드 전에 데이터를 백업하고 버전 호환성을 확인하십시오. +- **시작에 실패하면 어떻게 하나요?** 먼저 배포 로그와 이벤트를 확인하고, 인스턴스가 준비된 후 모델을 구성하십시오. 공개 댓글이나 스크린샷에 인스턴스 비밀번호와 키를 노출하지 마십시오. diff --git a/ko/guides/platform/wework_bot.mdx b/ko/guides/platform/wework_bot.mdx deleted file mode 100644 index 5996dcdec..000000000 --- a/ko/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/pl/guides/aichat/aichat2_conversations.mdx b/pl/guides/aichat/aichat2_conversations.mdx index 83a301e30..b08a05f8c 100644 --- a/pl/guides/aichat/aichat2_conversations.mdx +++ b/pl/guides/aichat/aichat2_conversations.mdx @@ -3,28 +3,28 @@ title: "Instrukcja integracji AI Chat v2 API" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API (`/aichat2/conversations`) to interfejs dialogowy nowej generacji oraz kompleksowo ulepszona wersja [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Na bazie zwięzłości v1 i hostowanej obsługi wieloturowych rozmów rozszerza on: +AI Chat v2 API (`/aichat2/conversations`) to interfejs konwersacyjny nowej generacji, będący kompleksowo ulepszoną wersją [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Na bazie prostoty i hostowanej obsługi wieloturowych rozmów v1 rozszerza on: -- **Wielomodalne dane wejściowe użytkownika**: bezpośrednie przekazywanie tekstu + obrazów + bloków plików przez ustrukturyzowane pole `message`, bez konieczności uprzedniego pośredniego dołączania za pomocą `references`. -- **Wywoływanie narzędzi w stylu Agent**: wbudowany zestaw narzędzi do wyszukiwania w sieci, pobierania stron internetowych, odczytu plików itp., z możliwością podłączenia autoryzowanych przez użytkownika serwerów MCP (Google Drive, Notion, Slack, GitHub itd.); model może w ramach jednego żądania autonomicznie wielokrotnie wywoływać narzędzia, aby realizować złożone zadania. -- **Ustrukturyzowane zdarzenia strumieniowe**: za pomocą `accept: text/event-stream` lub `application/x-ndjson` można otrzymywać zdarzenia takie jak `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` itp. dla każdego tokenu, co ułatwia osobne renderowanie ich według odpowiednich typów w interfejsie frontendowym. -- **Możliwość przerwania / wznowienia**: gdy model potrzebuje od użytkownika dodatkowych informacji, wysyła zdarzenie `ask_user_question` i wstrzymuje działanie; przy następnym wywołaniu wystarczy uzupełnić odpowiedź przez `tool_results`, aby kontynuować. -- **Nowe działania CRUD**: na tym samym endpointcie można realizować `retrieve` / `retrieve_batch` / `update` / `delete` za pomocą pola `action`, bez potrzeby dodatkowego API do zarządzania rozmowami. -- **Stale aktualizowana lista modeli**: domyślnie obsługiwane są współczesne modele, takie jak GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 i inne. +- **Wielomodalne dane wejściowe użytkownika**: bezpośrednie przekazywanie tekstu + obrazów + bloków plików za pomocą ustrukturyzowanego pola `message`, bez potrzeby wcześniejszego pośredniego dołączania przez `references`. +- **Wywoływanie narzędzi w stylu Agent**: wbudowany zestaw narzędzi do wyszukiwania w Internecie, pobierania stron internetowych, odczytu plików itp., z możliwością podłączenia autoryzowanych przez użytkownika serwerów MCP (Google Drive, Notion, Slack, GitHub itd.), dzięki czemu model może autonomicznie wielokrotnie wywoływać narzędzia w ramach jednego żądania, aby wykonywać złożone zadania. +- **Ustrukturyzowane zdarzenia strumieniowe**: za pomocą `accept: text/event-stream` lub `application/x-ndjson` można otrzymywać zdarzenia takie jak `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` itd. dla każdego tokenu, co ułatwia ich osobne renderowanie na froncie według odpowiednich typów. +- **Możliwość przerwania / wznowienia**: gdy model potrzebuje, aby użytkownik uzupełnił informacje, wyśle zdarzenie `ask_user_question` i wstrzyma działanie; przy następnym wywołaniu wystarczy uzupełnić odpowiedź przez `tool_results`, aby kontynuować. +- **Nowe akcje CRUD**: w tym samym endpointcie można wykonywać `retrieve` / `retrieve_batch` / `update` / `delete` za pomocą pola `action`, bez potrzeby dodatkowego API zarządzania rozmowami. +- **Stale aktualizowana lista modeli**: domyślnie dostępne są współczesne modele, takie jak GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 itd. -Jednocześnie na poziomie body żądania jest on **w pełni wstecznie kompatybilny z v1**: wystarczy przekazać `model` + `question` (+ opcjonalnie `stateful` / `id` / `references` / `preset`), aby otrzymać równoważną z v1 odpowiedź JSON `{answer, id}`. Dlatego migracja z `/aichat/conversations` nie wymaga przepisywania klienta — wystarczy zmienić ścieżkę na `/aichat2/conversations`. +Jednocześnie na poziomie treści żądania jest on **w pełni wstecznie kompatybilny z v1**: wystarczy przekazać `model` + `question` (+ opcjonalnie `stateful` / `id` / `references` / `preset`), aby otrzymać odpowiedź JSON `{answer, id}` równoważną v1, więc migracja z `/aichat/conversations` nie wymaga przepisywania klienta — wystarczy zmienić ścieżkę na `/aichat2/conversations`. -> Jeśli obecnie używasz `/aichat/conversations`, stary interfejs nadal będzie dostępny, więc możesz migrować we własnym tempie. +> Jeśli obecnie używasz `/aichat/conversations`, stary interfejs nadal będzie obsługiwany i możesz przeprowadzić migrację we własnym tempie. -## Proces aplikacji +## Proces składania wniosku -Aby korzystać z AI Chat v2 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 korzystać z AI Chat v2 API, najpierw pobierz swój API Token w [konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications) i zachowaj go do późniejszego użycia. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi Cię do rejestracji i zalogowania się; po zakończeniu automatycznie wrócisz na bieżącą stronę. -**Jeden API Token umożliwia wywoływanie wszystkich usług platformy — nie musisz składać osobnego wniosku dla każdej usługi.** Przy pierwszym wniosku otrzymasz bezpłatne środki, aby korzystać z usługi za darmo; gdy środki będą niewystarczające, możesz doładować wspólne saldo w [konsoli](https://platform.acedata.cloud/console/coin). +**Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności osobnego wnioskowania dla każdej usługi.** Przy pierwszym wniosku otrzymasz darmowy limit, który pozwoli na bezpłatne wypróbowanie usługi; gdy limit będzie niewystarczający, możesz doładować uniwersalne saldo w [konsoli](https://platform.acedata.cloud/console/coin). > 📘 Pełna dokumentacja: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Dostępne wartości `model` można bezpośrednio zobaczyć na liście rozwijanej panelu Try po prawej stronie, a często używane kategorie obejmują: +Dostępne wartości `model` można zobaczyć bezpośrednio na liście rozwijanej panelu Try po prawej stronie; popularne kategorie obejmują: - OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` itd. - Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` itd. @@ -86,11 +86,11 @@ Dostępne wartości `model` można bezpośrednio zobaczyć na liście rozwijanej - Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` itd. - Zhipu: `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` itd. -Szczegółowe zasady rozliczeń znajdziesz na karcie Pricing na stronie usługi. +Szczegółowe zasady rozliczeń znajdują się na karcie Pricing strony usługi. -## Wieloturowe rozmowy +## Wieloturowa rozmowa -Tak jak w v1, przekaż `stateful: true`, aby włączyć zapisywanie rozmowy; API zwróci `id`; w kolejnych żądaniach wystarczy przekazać z powrotem `id`, aby kontynuować rozmowę, bez konieczności samodzielnego utrzymywania historii messages. +Tak jak w v1, przekaż `stateful: true`, aby włączyć zapisywanie rozmowy; API zwróci `id`; w kolejnych żądaniach wystarczy przekazywać z powrotem `id`, aby kontynuować rozmowę, bez konieczności samodzielnego utrzymywania historii messages. Pierwsze żądanie: @@ -106,7 +106,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Zwracane: +Zwraca: ```json { @@ -138,14 +138,14 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ > Domyślnie `stateful` ma wartość `true`; pominięcie go jest równoważne jawnemu przekazaniu `true`. Jeśli nie chcesz, aby serwer zapisywał tę turę rozmowy, możesz jawnie ustawić `stateful: false`. -## Odpowiedź strumieniowa +## Odpowiedzi strumieniowe v2 obsługuje dwa formaty strumieniowe, wybierane zgodnie z nagłówkiem `accept`: | Scenariusz | `accept` | Format danych | | --------------------- | ---------------------- | ------------------------------------------ | -| Frontend Web / EventSource | `text/event-stream` | `data: {json}\n\n`, ostatni wiersz: `data: [DONE]\n\n` | -| Serwer / CLI / analiza strumieniowa Node | `application/x-ndjson` | Jeden obiekt JSON w każdym wierszu | +| Frontend Web / EventSource | `text/event-stream` | `data: {json}\n\n`, ostatnia linia `data: [DONE]\n\n` | +| Serwer / CLI / analiza strumieniowa Node | `application/x-ndjson` | Jeden obiekt JSON na linię | | Strumieniowanie nie jest potrzebne | `application/json`（domyślnie） | Jednorazowo zwraca `{answer, id}` | ### Przykład NDJSON @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -Każdy wiersz NDJSON jest ustrukturyzowanym zdarzeniem, najczęściej występującym jest `text_delta`: +Każda linia NDJSON jest ustrukturyzowanym zdarzeniem, a najczęstszym jest `text_delta`: ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +195,7 @@ Każdy wiersz NDJSON jest ustrukturyzowanym zdarzeniem, najczęściej występuj ### Przykład SSE -`EventSource` po stronie przeglądarki nie obsługuje niestandardowego ciała żądania; zaleca się użycie `fetch` + ręcznego parsowania przez dzielenie według `\n\n`: +Użycie `EventSource` po stronie przeglądarki nie obsługuje niestandardowego ciała żądania; zaleca się użycie `fetch` + ręczne analizowanie przez podział na `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,22 +236,22 @@ while (true) { | `type` | Znaczenie | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Przyrostowy fragment tekstu odpowiedzi asystenta. `content` zawiera nową treść; dla zgodności z v1 to samo zdarzenie zawiera również `delta_answer` (równe `content`) oraz `id`. | -| `thinking` | Proces myślenia modelu (pojawia się tylko wtedy, gdy wybrany model ujawnia reasoning). | +| `text_delta` | Przyrostowy fragment tekstu odpowiedzi asystenta. `content` to nowa treść; dla zgodności z v1 to samo zdarzenie zawiera także `delta_answer` (równe `content`) oraz `id`. | +| `thinking` | Proces rozumowania modelu (pojawia się tylko wtedy, gdy wybrany model udostępnia reasoning). | | `tool_use` | Model decyduje się wywołać narzędzie; zdarzenie zawiera `tool_id`, `tool_name`, `input`. | -| `tool_result` | Wynik wykonania narzędzia, sparowany z poprzednim `tool_use` za pomocą `tool_id`; `is_error` wskazuje, czy wystąpił błąd. | +| `tool_result` | Wynik wykonania narzędzia, sparowany z poprzednim `tool_use` przez `tool_id`; `is_error` wskazuje, czy wystąpił błąd. | | `card` | Ustrukturyzowana karta wygenerowana przez narzędzie (np. obraz, podgląd linku), odpowiednia do bezpośredniego renderowania. | -| `citation` | Źródłowy URL używany do uzupełnienia cytowań dla odpowiednich fragmentów tekstu. | -| `ask_user_question` | Wysyłane, gdy model potrzebuje, aby użytkownik uzupełnił informacje; rozmowa przechodzi do stanu `awaiting_user_input`, szczegóły poniżej w sekcji [wznawianie wstrzymanej rozmowy](#恢复暂停的对话)。 | +| `citation` | Źródłowy URL używany do uzupełnienia cytowania odpowiedniego fragmentu tekstu. | +| `ask_user_question` | Wysyłane, gdy model potrzebuje, aby użytkownik uzupełnił informacje; rozmowa przechodzi w stan `awaiting_user_input`, szczegóły poniżej w sekcji [wznawianie wstrzymanej rozmowy](#恢复暂停的对话). | | `artifact` | Niezależny artefakt wygenerowany przez model (np. blok kodu, dokument), który można zapisać lub pobrać. | -| `system_message` | Komunikat systemowy (niebędący treścią użytkownika ani asystenta), używany wyłącznie jako wskazówka dla UI. | -| `compact` | Zdarzenie informujące o skompresowaniu wewnętrznego kontekstu, niewymagające specjalnej obsługi. | -| `error` | W tej turze wystąpił błąd; `message` opisuje jego treść. | +| `system_message` | Informacja systemowa (nie jest treścią użytkownika ani asystenta), używana wyłącznie jako komunikat UI. | +| `compact` | Zdarzenie, w którym wewnętrzny kontekst został skompresowany; nie wymaga specjalnej obsługi. | +| `error` | W tej turze wystąpił błąd; `message` opisuje treść błędu. | | `done` | Odpowiedź strumieniowa została zakończona; zawiera `usage` (w tym `prompt_tokens` / `completion_tokens` / `total_tokens`) oraz `terminal_reason`. | -W przypadku klientów, którym zależy wyłącznie na końcowej odpowiedzi, połączenie wszystkich wartości `content` ze zdarzeń `text_delta` jest równoważne wartości `answer` w trybie `application/json`. +W przypadku klientów, którym zależy tylko na końcowej odpowiedzi, połączenie `content` ze wszystkich `text_delta` jest równoważne `answer` w trybie `application/json`. -## Wejście multimodalne +## Dane wejściowe multimodalne Jeśli dane wejściowe użytkownika zawierają obrazy lub pliki, przekaż `message` (tablicę) zamiast `question`. Każdy element tablicy jest blokiem treści: @@ -270,26 +270,26 @@ Obsługiwane typy bloków: - `text` — zwykły tekst, wymagane pole `text`. - `image_url` — obraz, wymagane `image_url.url`. -- `file_url` — plik (PDF, CSV, TXT itp.), wymagane `file_url.url`. +- `file_url` — plik (PDF, CSV, TXT itd.), wymagane `file_url.url`. ### Relacja z `references` w v1 Aby zachować zgodność ze starszymi klientami, v2 nadal rozpoznaje pole `references: ["https://...", ...]`: -- Jeśli rozszerzenie URL to `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatycznie przekształca się w blok `image_url`; -- Inne rozszerzenia są przekształcane w blok `file_url`; -- Jeśli jednocześnie podano `question`, jest ono umieszczane na początku jako blok `text`. +- Jeśli rozszerzenie URL to `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, jest automatycznie konwertowane na blok `image_url`; +- Inne rozszerzenia są konwertowane na blok `file_url`; +- Jeśli jednocześnie podano `question`, jest ono umieszczane z przodu jako blok `text`. -Dlatego jeśli chcesz tylko przejść z v1 i nie chcesz zmieniać treści żądania, wystarczy zmienić ścieżkę na `/aichat2/conversations`, a pierwotne użycie `references` nadal działa jak zwykle. +Dlatego jeśli chcesz tylko zmigrować z v1 i nie chcesz zmieniać body żądania, wystarczy zmienić ścieżkę na `/aichat2/conversations`, a dotychczasowe użycie `references` nadal działa. -Jeśli potrzebujesz bardziej szczegółowej kontroli (na przykład umieszczenia wielu obrazów między tekstem albo gdy kolejność jest ważna), użyj bezpośrednio tablicy `message`. +Jeśli potrzebujesz bardziej szczegółowej kontroli (na przykład umieszczenia wielu obrazów pomiędzy tekstem albo gdy kolejność jest bardzo ważna), użyj bezpośrednio tablicy `message`. ## Wywoływanie narzędzi i MCP -Kluczowym ulepszeniem v2 jest to, że model może samodzielnie wywoływać narzędzia w celu realizacji zadań wieloetapowych, **jest to domyślnie włączone** i nie wymaga żadnej dodatkowej konfiguracji po stronie klienta w żądaniu. Typowe scenariusze: +Kluczowym ulepszeniem v2 jest możliwość samodzielnego wywoływania przez model narzędzi w celu wykonania zadań wieloetapowych, **jest to domyślnie włączone** i nie wymaga żadnej dodatkowej konfiguracji po stronie klienta w żądaniu. Typowe scenariusze: -- Użytkownik pyta „Pomóż mi sprawdzić, jakie nowe wystawy są ostatnio w Szanghaju” → model wywołuje wbudowane web search → porządkuje wyniki w odpowiedź. -- Użytkownik pyta „Przeczytaj ten PDF, a następnie napisz podsumowanie” → model wywołuje file_read → pisze podsumowanie. -- Użytkownik autoryzował Google Drive / GitHub / Notion itd. w [Connections](https://platform.acedata.cloud/connections) → model może wywoływać odpowiednie narzędzia MCP, aby odczytywać i zapisywać ich dane. +- Użytkownik pyta: „Pomóż mi wyszukać, jakie nowe wystawy są ostatnio w Szanghaju” → model wywołuje wbudowane web search → porządkuje wyniki w odpowiedź. +- Użytkownik pyta: „Przeczytaj ten PDF, a potem napisz podsumowanie” → model wywołuje file_read → pisze podsumowanie. +- Użytkownik autoryzował już Google Drive / GitHub / Notion itd. w [Connections](https://platform.acedata.cloud/connections) → model może wywoływać odpowiednie narzędzia MCP do odczytu i zapisu ich danych. W strumieniu NDJSON / SSE wywołania narzędzi są prezentowane za pomocą dwóch typów zdarzeń: `tool_use` i `tool_result`, na przykład: @@ -301,19 +301,19 @@ W strumieniu NDJSON / SSE wywołania narzędzi są prezentowane za pomocą dwóc ... ``` -Jeśli nie chcesz wyświetlać szczegółów wywołań narzędzi w frontendzie, po prostu zignoruj zdarzenia typu `tool_use` / `tool_result` / `card` / `citation`; końcowe wyjście modelu nadal będzie przesyłane strumieniowo przez `text_delta`. +Jeśli nie chcesz wyświetlać na froncie szczegółów wywołań narzędzi, wystarczy zignorować zdarzenia typu `tool_use` / `tool_result` / `card` / `citation`, a końcowy wynik modelu nadal będzie przesyłany strumieniowo przez `text_delta`. -`max_turns` może ograniczyć maksymalną liczbę rund samowywołań narzędzi przez model w tym żądaniu, a domyślny limit jest określany przez platformę. Ustawienie małej wartości (na przykład `max_turns: 1`) może wymusić pojedynczą odpowiedź i nie pozwolić na żadne wywołania narzędzi. +`max_turns` może ograniczyć maksymalną liczbę rund samodzielnego wywoływania narzędzi przez model w tym żądaniu; zakres wynosi 1–500, a domyślnie, jeśli parametr zostanie pominięty, wynosi 500. Ustawienie małej wartości (na przykład `max_turns: 1`) może wymusić pojedynczą odpowiedź i nie zezwalać na żadne wywołania narzędzi. -## Wykonywanie asynchroniczne i autoryzacja bez nadzoru +## Wykonanie asynchroniczne i autoryzacja bez nadzoru -Jeśli Twoje wywołanie pochodzi z alertowego Webhooka, CI/CD, systemu monitorowania lub innego zadania działającego w tle, możesz ustawić `async: true`, aby interfejs natychmiast zwrócił ID zadania, a wykonywanie było kontynuowane w tle: +Jeśli Twoje wywołanie pochodzi z webhooka alertów, CI/CD, systemu monitorowania lub innych zadań backendowych, możesz ustawić `async: true`, aby interfejs natychmiast zwrócił ID zadania, a wykonanie było kontynuowane w tle: ```json { "model": "gpt-5.5", "async": true, - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Moja usługa zgłosiła alarm, powiadom grupę WeChat „AceDataCloud团队” przez osobisty WeChat……" } ``` @@ -328,9 +328,9 @@ Przykład odpowiedzi: } ``` -Następnie możesz użyć `action: retrieve` + `id`, aby sprawdzić wynik konwersacji; możesz też podać `callback_url`, a po zakończeniu zadania platforma wyśle `{ status, answer, usage, error }` metodą POST na Twój adres zwrotny. `callback_url` musi używać `http` / `https` i nie może bezpośrednio wskazywać `localhost` ani literałowego adresu prywatnego IP. +Następnie można użyć `action: retrieve` + `id`, aby sprawdzić wynik rozmowy; można również podać `callback_url`, a po zakończeniu zadania platforma wykona POST z `{ status, answer, usage, error }` na Twój adres zwrotny. `callback_url` musi używać `http` / `https` i nie może bezpośrednio wskazywać `localhost` ani literałowego adresu prywatnego IP. -Zwykle nie ma nikogo, kto mógłby kliknąć potwierdzenie dla zadań działających w tle. Jeśli chcesz, aby określone Skill lub MCP Server wykonywały działania takie jak wysyłanie, publikowanie lub zapisywanie w trybie bez nadzoru, jawnie przekaż listę wstępnej autoryzacji w treści żądania: +W zadaniach backendowych zwykle nie ma nikogo, kto mógłby kliknąć potwierdzenie. Jeśli chcesz, aby określone Skill lub MCP Server wykonywały w trybie bez nadzoru działania takie jak wysyłanie, publikowanie lub zapisywanie, jawnie przekaż listę preautoryzacji w body żądania: ```json { @@ -338,13 +338,13 @@ Zwykle nie ma nikogo, kto mógłby kliknąć potwierdzenie dla zadań działają "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Moja usługa zgłosiła alarm, powiadom grupę WeChat „AceDataCloud团队” przez osobisty WeChat……" } ``` -Wartości w `allowed_skills` są slugami połączonych Skill; wartości w `allowed_mcp_servers` są slugami połączonych MCP Server. Skill / MCP Server, które nie zostały uwzględnione we wstępnej autoryzacji, w trybie bez nadzoru nadal mogą jedynie wyświetlać podgląd, wykonywać dry-run lub odmówić wykonania operacji zapisu. +Wartości w `allowed_skills` to slugi połączonych Skill; wartości w `allowed_mcp_servers` to slugi połączonych MCP Server. Skill / MCP Server niewymienione w preautoryzacji w trybie bez nadzoru nadal mogą jedynie wyświetlać podgląd, wykonywać dry-run lub odmawiać wykonania operacji zapisu. -Jeśli potrzebujesz bardziej szczegółowej kontroli, możesz także użyć równoważnego obiektu `unattended_policy`: +Jeśli potrzebujesz bardziej szczegółowej kontroli, możesz również użyć równoważnego obiektu `unattended_policy`: ```json { @@ -356,26 +356,26 @@ Jeśli potrzebujesz bardziej szczegółowej kontroli, możesz także użyć rów } ``` -Wstępna autoryzacja to właśnie te dwie listy: pusta lista oznacza brak autoryzacji dla jakichkolwiek możliwości, bez potrzeby stosowania dodatkowego pola przełącznika. +Preautoryzacja to same te dwie listy: pusta lista oznacza brak autoryzacji jakichkolwiek możliwości, bez potrzeby stosowania dodatkowego pola przełącznika. -Uwaga: wstępna autoryzacja oznacza jedynie, że „to żądanie pozwala tym możliwościom pominąć ręczne potwierdzenie w trybie bez nadzoru”. Konkretny Skill nadal musi obsługiwać `--unattended-confirm` lub odpowiedni mechanizm bezpieczeństwa; w przeciwnym razie nadal wykona dry-run i nie przeprowadzi bezpośrednio operacji zapisu. +Uwaga: preautoryzacja oznacza jedynie, że „to żądanie zezwala tym możliwościom na pominięcie ręcznego potwierdzenia w trybie bez nadzoru”. Konkretny Skill nadal musi obsługiwać `--unattended-confirm` lub odpowiadający mu mechanizm bezpieczeństwa; w przeciwnym razie nadal będzie działać w trybie dry-run i nie wykona bezpośrednio operacji zapisu. -## Wznawianie wstrzymanych konwersacji +## Wznawianie wstrzymanych rozmów -Niektóre narzędzia powodują, że model „zadaje użytkownikowi pytanie zwrotne”; model emituje wtedy zdarzenie `ask_user_question`, a konwersacja zostaje zamrożona w stanie `awaiting_user_input`: +Niektóre narzędzia powodują, że model „zadaje użytkownikowi pytanie zwrotne”; w tym momencie model emituje zdarzenie `ask_user_question`, a rozmowa zostaje zamrożona w stanie `awaiting_user_input`: ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "你希望生成的报告是中文还是英文？", - "options": ["中文", "英文"], + "question": "Czy chcesz, aby wygenerowany raport był po chińsku czy po angielsku?", + "options": ["chiński", "angielski"], "id": "f2f4b3e8-..." } ``` -W frontendzie wyrenderuj to zdarzenie jako kartę, aby użytkownik mógł wybrać odpowiedź, a następnie rozpocznij kolejne żądanie z tym samym `id`, przekazując odpowiedź zwrotnie przez `tool_results`: +Na froncie wyrenderuj to zdarzenie jako kartę, aby użytkownik mógł wybrać odpowiedź, a następnie użyj tego samego `id`, aby wysłać kolejne żądanie i uzupełnić odpowiedź przez `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -`tool_use_id` w treści żądania **musi** być całkowicie zgodne z `tool_id` z momentu wstrzymania; niezgodność zwróci 400. Gdy w żądaniu jednocześnie występuje `tool_results`, `question` / `message` / `references` zostaną wszystkie zignorowane. +`tool_use_id` w body żądania **musi** być dokładnie zgodne z `tool_id` z momentu wstrzymania; w przeciwnym razie zwracany jest błąd 400. Gdy w żądaniu jednocześnie występuje `tool_results`, `question` / `message` / `references` są ignorowane. Jeśli użytkownik zdecyduje się porzucić to pytanie, wystarczy bezpośrednio przekazać nowe `question` / `message`, a platforma automatycznie oznaczy wstrzymane wywołanie narzędzia jako „pominięte przez użytkownika”. -## Zarządzanie konwersacjami (CRUD) +## Zarządzanie rozmowami (CRUD) -v2 zapewnia lekkie zarządzanie konwersacjami przez pole `action` w tym samym endpointcie, bez potrzeby uruchamiania dodatkowego API. +v2 zapewnia lekkie zarządzanie rozmowami na tym samym endpointzie za pomocą pola `action`, bez potrzeby uruchamiania dodatkowego API. +### `action: retrieve` —— pobierz rozmowę -### `action: retrieve` —— pobieranie konwersacji ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Zwraca kompletny dokument rozmowy (w tym historię `messages`, `model`, `title`, `tools_used` itd.). +Zwraca pełny dokument rozmowy (w tym historię `messages`, `model`, `title`, `tools_used` itd.). -### `action: retrieve_batch` —— Wyświetlanie listy podsumowań rozmów +### `action: retrieve_batch` —— wyświetl podsumowania rozmów ```json { @@ -428,23 +428,23 @@ Zwraca kompletny dokument rozmowy (w tym historię `messages`, `model`, `title`, } ``` -Zwraca `{ items: [...], total }`. **Podsumowania nie zawierają `messages`**, więc nadają się do listy na pasku bocznym; jeśli użytkownik otworzy konkretną rozmowę, użyj następnie `action: retrieve`, aby osobno pobrać jej pełne wiadomości. +Zwraca `{ items: [...], total }`. **Podsumowania nie zawierają `messages`**, co jest odpowiednie dla listy na pasku bocznym; jeśli użytkownik otworzy daną rozmowę, użyj następnie `action: retrieve`, aby osobno pobrać jej pełne wiadomości. Opcjonalne parametry filtrowania: `user_id`, `application_id`, `model_group`, `model`. -### `action: update` —— Zmiana tytułu lub nadpisanie historii +### `action: update` —— zmień tytuł lub nadpisz historię ```json { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "title": "Plan podróży do Hangzhou" + "title": "杭州旅行计划" } ``` -Można również przekazać `messages`, ale serwer przeprowadzi rygorystyczną walidację schematu (musi mieć zwiniętą postać `ToolUseContent`); w przypadku niezgodności zwróci 400. Zazwyczaj zaleca się używanie tego wyłącznie do zmiany `title`. +Można również przekazać `messages`, ale serwer przeprowadzi ścisłą walidację schema (musi to być zwinięta forma `ToolUseContent`); w przypadku niezgodności zwróci 400. Zazwyczaj zaleca się używanie tego wyłącznie do zmiany `title`. -### `action: delete` —— Usuwanie rozmowy +### `action: delete` —— usuń rozmowę ```json { @@ -453,17 +453,17 @@ Można również przekazać `messages`, ale serwer przeprowadzi rygorystyczną w } ``` -Zwraca `{ id, success: true }`. Po usunięciu nie można odzyskać rozmowy, dlatego przed wywołaniem upewnij się. +Zwraca `{ id, success: true }`. Po usunięciu nie można przywrócić, dlatego przed wywołaniem upewnij się. ## Płynna migracja z v1 -Jeśli już używasz [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), migracja do v2 prawie nie wymaga zmian w kodzie: +Jeśli korzystasz już z [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), migracja do v2 prawie nie wymaga zmian w kodzie: 1. Zmień URL z `https://api.acedata.cloud/aichat/conversations` na `https://api.acedata.cloud/aichat2/conversations`. 2. Jeśli wcześniej przekazywałeś nazwy modeli v1 (takie jak `gpt-3.5`, `gpt-4-browsing` itd.), podczas przejścia na v2 zaleca się aktualizację do współczesnych modeli (takich jak `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` itd.). -3. Pola strumienia NDJSON pozostają wstecznie kompatybilne: każde zdarzenie `text_delta` nadal zawiera `delta_answer` oraz `id`, dlatego klient, który wcześniej analizował wiersz po wierszu `delta_answer`, nie wymaga zmian. +3. Pola strumienia NDJSON zachowują kompatybilność wsteczną: każde zdarzenie `text_delta` nadal zawiera `delta_answer` i `id`, dlatego klienci, którzy wcześniej analizowali `delta_answer` wiersz po wierszu, nie wymagają zmian. -Po migracji możesz w razie potrzeby włączyć nowe możliwości v2 (multimodalne `message`, SSE, wywoływanie narzędzi, `action` CRUD), wdrażając je w odpowiednim tempie. +Po migracji można w razie potrzeby włączać nowe możliwości v2 (multimodalne `message`, SSE, wywoływanie narzędzi, CRUD `action`), wdrażając je we własnym tempie. ## Obsługa błędów @@ -481,14 +481,14 @@ Odpowiedzi błędów mają ujednoliconą postać: Typowe błędy: -- `400 bad_request`: brak wymaganych pól, niezgodność `tool_use_id`, nieprawidłowy schemat `messages` itd. -- `401 invalid_token`: nagłówek `authorization` jest nieprawidłowy. -- `404 not_found`: rozmowa odpowiadająca `id` nie istnieje podczas `action: retrieve / update / delete`. -- `429 too_many_requests`: został uruchomiony limit szybkości. -- `500 chat_error`: błąd nadrzędnego LLM lub `completion_tokens=0` w tej turze (traktowane jako niezużyte, opłata nie zostanie naliczona). +- `400 bad_request`: brakuje wymaganego pola, `tool_use_id` nie pasuje, schema `messages` jest nieprawidłowe itd. +- `401 invalid_token`: nagłówek `authorization` jest niepoprawny. +- `404 not_found`: podczas `action: retrieve / update / delete` rozmowa odpowiadająca `id` nie istnieje. +- `429 too_many_requests`: uruchomiono limit szybkości żądań. +- `500 chat_error`: błąd nadrzędnego LLM lub `completion_tokens=0` w tej rundzie (traktowane jako niezużyte, opłata nie zostanie naliczona). -W odpowiedzi strumieniowej błędy są wysyłane jako zdarzenia `{"type":"error","message":"..."}`, po czym strumień natychmiast się kończy. +W odpowiedzi strumieniowej błędy są wysyłane jako zdarzenie `{"type":"error","message":"..."}`, po czym strumień natychmiast się zakończy. ## Wnioski -AI Chat v2 API, zachowując wsteczną kompatybilność z v1, podnosi rozmowy z poziomu „pytań i odpowiedzi jednokrotnych / wielokrotnych” do „obserwowalnych rozmów opartych na Agentach”: wejście multimodalne, wywoływanie narzędzi, możliwość wstrzymywania / wznawiania, strumieniowe ustrukturyzowane zdarzenia, wbudowane CRUD. Zaleca się, aby nowe integracje od razu korzystały z v2; istniejące integracje v1 mogą migrować płynnie etapami. W razie jakichkolwiek pytań skontaktuj się w dowolnym momencie z naszym zespołem wsparcia technicznego. +API AI Chat v2, zachowując kompatybilność wsteczną z v1, podnosi rozmowy z „pytań i odpowiedzi jednokrotnych / wielokrotnych” do „obserwowalnych rozmów opartych na Agentach”: wejście multimodalne, wywoływanie narzędzi, możliwość wstrzymania / wznowienia, strumieniowe ustrukturyzowane zdarzenia, wbudowany CRUD. Zaleca się, aby nowe integracje bezpośrednio korzystały z v2; istniejące integracje v1 mogą przeprowadzić płynną migrację etapami. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego. diff --git a/pl/guides/platform/hermes_managed.mdx b/pl/guides/platform/hermes_managed.mdx index 5d62e013f..8d4fd77e1 100644 --- a/pl/guides/platform/hermes_managed.mdx +++ b/pl/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Prywatne Wdrożenie" +title: "Wdrożenie Hermes" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud oferuje wejście do prywatnego wdrożenia Hermes Agent. To wejście jest kontrolowaną usługą, dostępność oraz opcjonalne zasoby są zgodne z aktualnym wyświetleniem w konsoli. +Dla każdej Application tworzona jest niezależna instancja kontenera Hermes. Domyślnie używany jest obraz bazowy o stałej wersji wydania, z zachowaniem natywnych funkcji; platforma zapewnia zakup, odnowienie, trwałą pamięć masową i zarządzanie wdrożeniem. -## Kroki użycia +## Tworzenie i zakup -1. Znajdź **Hermes Agent Prywatne Wdrożenie** na platformie. -2. Wybierz dostępne konfiguracje i utwórz usługę zgodnie z wskazówkami na stronie. -3. Poczekaj, aż platforma wyświetli status gotowości. -4. Użyj podanego na stronie wejścia i poświadczeń, aby uzyskać dostęp do instancji. -5. Najpierw wyślij `Reply only OK`, a następnie rozpocznij rzeczywiste zadanie. +1. Otwórz [Wdrożenie Hermes](https://platform.acedata.cloud/services/hermes) i utwórz Application. +2. Na stronie zakupu wybierz pakiet czasowy i dokończ płatność. +3. Wróć na stronę konfiguracji, wybierz model czatu platformy z listy rozwijanej i sprawdź bieżącą cenę modelu. Platforma utworzy niezależne poświadczenia API dla tej instancji; możesz również wyłączyć dostęp przez platformę i samodzielnie skonfigurować go w natywnej konsoli. +4. Wybierz automatyczne generowanie poświadczeń dostępu albo ustaw własne silne hasło/Token, a następnie potwierdź, aby rozpocząć wdrożenie. Poświadczenia dostępu i poświadczenia API modelu są od siebie niezależne. +5. Gdy instancja będzie gotowa, pobierz adres dostępu i poświadczenia logowania ze strony zarządzania. +6. Zaloguj się do natywnej konsoli i skonfiguruj własnych dostawców modeli, klucze i kanały. -Modele, poświadczenia, przechowywanie i działania usuwania są zgodne z stroną tworzenia oraz oknem potwierdzenia; nie traktuj lokalnych samouczków Hermes w formacie YAML jako umowy wdrożeniowej platformy. Przed usunięciem najpierw wyeksportuj dane, które chcesz zachować. +Opłata za wdrożenie jest naliczana według czasu trwania pakietu; szczegółowa cena w USD i czas trwania są określone na stronie zakupu. Opłaty za wywołania modelu są naliczane osobno; zakup czasu wdrożenia nie zapewnia limitu modelu. Gdy dostęp przez platformę jest włączony, dedykowane poświadczenia API udostępniają wyłącznie interfejs czatu odpowiadający wybranemu modelowi, a wywołania są dodatkowo rozliczane z salda platformy. Każda Application jest kupowana, odnawiana i zarządzana oddzielnie. -Jeśli konsola nie wyświetla wejścia do tworzenia, oznacza to, że bieżące konto nie ma jeszcze dostępu do tej usługi, możesz skorzystać z [Hermes interaktywnego przewodnika](https://platform.acedata.cloud/documents/hermes-wizard-integration) lub [ręcznej konfiguracji](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Hasła, poświadczenia i późniejsza konfiguracja + +Poświadczenia dostępu są ustawiane przed pierwszym uruchomieniem. Metoda automatycznego generowania używa losowych poświadczeń, niestandardowe hasło musi mieć co najmniej 16 znaków, a OpenClaw Token co najmniej 32 znaki. Szkic nie zapisuje hasła; po przejściu na inną stronę może być konieczne ponowne jego wprowadzenie. Po wdrożeniu tylko właściciel Application i administratorzy mogą wyświetlać poświadczenia dostępu. + +Poświadczenia API modelu dla każdej instancji nie są współdzielone, ich ważność jest przedłużana wraz z odnowieniem wdrożenia, a przy usunięciu instancji są unieważniane. Po inicjalizacji wdrożenia zmodyfikuj modele i kanały w natywnej konsoli; jeśli zmieniasz wybór na model innej usługi, najpierw dostosuj autoryzację odpowiedniego interfejsu w zarządzaniu poświadczeniami platformy lub użyj odpowiednich poświadczeń. Zwykłe ponowne wdrożenie nie nadpisze ustawień natywnych. Środowiska wdrożeniowe, które nie przeszły weryfikacji publikacji, będą tymczasowo odrzucać nowe wdrożenia; skontaktuj się z pomocą techniczną. + +## Wersje i dane + +Strona konfiguracji wyświetla aktualnie opublikowaną wersję obrazu. Nowe instancje używają aktualnie opublikowanej wersji usługi; istniejące instancje nie są automatycznie zastępowane wraz z aktualizacjami katalogu. Ponowne wdrożenie zastosuje aktualną wersję usługi; najpierw wykonaj kopię zapasową i potwierdź wymagania aktualizacji używanej wersji. + +Każda instancja domyślnie zapewnia 1 CPU, limit 2 GiB pamięci i 10 GiB trwałej pamięci masowej. Ponowne uruchomienie zachowuje dane instancji. Aktywne usunięcie wdrożenia lub odzyskanie po wygaśnięciu usunie pamięć masową, dlatego wcześniej wyeksportuj dane, które chcesz zachować. + +## Odnowienie i wygaśnięcie + +Odnów subskrypcję na stronie zakupu bieżącej Application, a okres ważności zostanie przedłużony zgodnie z obecnymi zasadami czasu trwania platformy. Po wygaśnięciu punkt dostępu zostanie wstrzymany, a odnowienie w okresie karencji przywróci dostęp; po przekroczeniu okresu karencji instancja i dane zostaną odzyskane. Obowiązują czas wygaśnięcia, status rozliczeń i komunikaty o usunięciu na stronie zarządzania. + +## Logowanie do interfejsu zarządzania + +Na stronie zarządzania wdrożeniem skopiuj adres Dashboard, nazwę użytkownika `admin` i hasło, a następnie otwórz adres i zaloguj się. Informacje logowania są udostępniane wyłącznie właścicielowi danej Application i administratorom platformy. Modele, umiejętności i kanały są konfigurowane w natywnym interfejsie Hermes. + +## Często zadawane pytania + +- **Dlaczego nowa instancja nadal nie może odpowiadać?** Zakończenie wdrożenia oznacza, że kontener jest gotowy; aby rozpocząć korzystanie, należy skonfigurować model i poświadczenia w natywnym interfejsie. +- **Czy dodatkowe wtyczki lub fallback modelu są preinstalowane?** Domyślnie nie są dodawane; skonfiguruj je według potrzeb w natywnym interfejsie. +- **Jak zaktualizować istniejącą instancję?** Oryginalna Application i zamówienie zostają zachowane, a przy ponownym wdrożeniu używana jest aktualna wersja usługi; przed aktualizacją wykonaj kopię zapasową danych i sprawdź zgodność wersji. +- **Co zrobić w przypadku niepowodzenia uruchomienia?** Najpierw sprawdź dzienniki wdrożenia i zdarzenia, a po potwierdzeniu gotowości instancji skonfiguruj model. Nie ujawniaj hasła instancji ani kluczy w publicznych komentarzach lub zrzutach ekranu. diff --git a/pl/guides/platform/wework_bot.mdx b/pl/guides/platform/wework_bot.mdx deleted file mode 100644 index 98cc5dcb8..000000000 --- a/pl/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/pt/guides/aichat/aichat2_conversations.mdx index 5358ca845..fbb7c4384 100644 --- a/pt/guides/aichat/aichat2_conversations.mdx +++ b/pt/guides/aichat/aichat2_conversations.mdx @@ -3,34 +3,34 @@ title: "Instruções de integração da API AI Chat v2" description: "AI Dialogue API guide - Ace Data Cloud" --- -A API AI Chat v2 (`/aichat2/conversations`) é a interface de conversa de nova geração, uma versão totalmente atualizada da [API AI Chat](https://platform.acedata.cloud/documents/aichat-conversations). Com base na simplicidade e no gerenciamento hospedado de conversas de múltiplas rodadas da v1, ela expandiu: +A API AI Chat v2 (`/aichat2/conversations`) é a interface de conversação de nova geração, uma versão totalmente atualizada da [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Com base na simplicidade e no gerenciamento hospedado de conversas com múltiplas rodadas da v1, ela expandiu: -- **Entrada de usuário multimodal**: envie diretamente blocos de texto + imagem + arquivo através do campo `message` estruturado, sem precisar anexá-los indiretamente primeiro usando `references`. -- **Chamada de ferramentas orientada a Agent**: inclui um conjunto de ferramentas como pesquisa na internet, captura de páginas web e leitura de arquivos, e permite montar servidores MCP autorizados pelo usuário (Google Drive, Notion, Slack, GitHub etc.); o modelo pode chamar ferramentas autonomamente em múltiplas rodadas dentro de uma única solicitação para concluir tarefas complexas. -- **Eventos de streaming estruturados**: através de `accept: text/event-stream` ou `application/x-ndjson`, é possível obter eventos como `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` etc. token por token, facilitando a renderização separada no frontend conforme o tipo correspondente. -- **Interrompível / retomável**: quando o modelo precisa que o usuário complemente informações, ele emite o evento `ask_user_question` e pausa; na próxima chamada, basta preencher a resposta através de `tool_results` para continuar. -- **Novas ações CRUD**: realize `retrieve` / `retrieve_batch` / `update` / `delete` através do campo `action` no mesmo endpoint, sem precisar de uma API adicional de gerenciamento de conversas. +- **Entrada de usuário multimodal**: envia diretamente texto + imagem + blocos de arquivo através do campo estruturado `message`, sem necessidade de anexar indiretamente primeiro usando `references`. +- **Chamada de ferramentas orientada a Agent**: incorpora um conjunto de ferramentas como pesquisa na internet, captura de páginas web, leitura de arquivos etc., e pode montar servidores MCP autorizados pelo usuário (Google Drive, Notion, Slack, GitHub etc.); o modelo pode chamar ferramentas autonomamente em múltiplas rodadas dentro de uma única solicitação para concluir tarefas complexas. +- **Eventos de streaming estruturados**: através de `accept: text/event-stream` ou `application/x-ndjson`, é possível obter eventos como `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` etc. token a token, facilitando a renderização separada no frontend de acordo com o tipo correspondente. +- **Interrompível / recuperável**: quando o modelo precisar que o usuário complemente informações, ele emitirá o evento `ask_user_question` e pausará; na próxima chamada, basta preencher a resposta através de `tool_results` para continuar. +- **Novas ações CRUD**: conclua `retrieve` / `retrieve_batch` / `update` / `delete` no mesmo endpoint através do campo `action`, sem necessidade de uma API adicional de gerenciamento de conversas. - **Lista de modelos continuamente atualizada**: por padrão, integra modelos contemporâneos como GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 etc. -Ao mesmo tempo, ela é **totalmente retrocompatível com a v1** no nível do corpo da solicitação: basta enviar `model` + `question` (+ opcionalmente `stateful` / `id` / `references` / `preset`) para obter uma resposta JSON `{answer, id}` equivalente à v1. Portanto, não é necessário reescrever o cliente ao migrar de `/aichat/conversations`; basta alterar o caminho para `/aichat2/conversations`. +Ao mesmo tempo, ela é **totalmente compatível retroativamente com a v1** no nível do corpo da solicitação: basta enviar `model` + `question` (+ opcionais `stateful` / `id` / `references` / `preset`) para obter uma resposta JSON `{answer, id}` equivalente à v1. Portanto, ao migrar de `/aichat/conversations`, não é necessário reescrever o cliente; basta alterar o caminho para `/aichat2/conversations`. -> Se você estiver usando atualmente `/aichat/conversations`, a interface antiga continuará sendo mantida, e você poderá migrar no seu próprio ritmo. +> Se você estiver usando atualmente `/aichat/conversations`, a interface antiga continuará disponível, e você poderá migrar no seu próprio ritmo. ## Processo de solicitação -Para usar a API AI Chat v2, primeiro obtenha seu API Token no [Console Ace Data Cloud](https://platform.acedata.cloud/console/applications) e guarde-o como reserva. +Para usar a API AI Chat v2, primeiro obtenha seu API Token no [console 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 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 concluir, retornará automaticamente à página atual. +Se você ainda não estiver conectado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e entrar; após a conclusão, retornará automaticamente à página atual. -**Um único API Token permite chamar todos os serviços da plataforma, sem precisar solicitar um separadamente para cada serviço.** A primeira solicitação concede uma cota gratuita, permitindo uma experiência sem custo; quando a cota for insuficiente, você poderá recarregar saldo universal no [console](https://platform.acedata.cloud/console/coin). +**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 experimentação; quando os créditos forem insuficientes, você poderá recarregar o saldo universal no [console](https://platform.acedata.cloud/console/coin). -> 📘 Documentação completa: [API AI Chat v2 →](https://platform.acedata.cloud/documents/aichat2-conversations) +> 📘 Documentação completa: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Uso básico -O uso mais simples é totalmente igual ao da v1: envie `model` + `question` e obtenha `{answer, id}`. +O uso mais simples é completamente igual ao da v1: envie `model` + `question` e obtenha `{answer, id}`. Exemplo CURL: @@ -88,9 +88,9 @@ Os valores disponíveis para `model` podem ser vistos diretamente no menu suspen Para regras específicas de cobrança, consulte o cartão Pricing na página do serviço. -## Conversas de múltiplas rodadas +## Conversas com múltiplas rodadas -Assim como na v1, envie `stateful: true` para ativar o salvamento da conversa; a API retornará um `id`; nas solicitações subsequentes, basta enviar o `id` de volta para continuar a conversa, sem precisar manter o histórico de messages por conta própria. +Assim como na v1, envie `stateful: true` para ativar o salvamento da conversa; a API retornará um `id`; nas solicitações seguintes, basta enviar o `id` de volta para continuar a conversa, sem precisar manter o histórico de messages por conta própria. Primeira solicitação: @@ -115,37 +115,17 @@ Retorno: } ``` -Segunda solicitação, incluindo o mesmo `id`: -```shell -curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ - -H 'accept: application/json' \ - -H 'authorization: Bearer {token}' \ - -H 'content-type: application/json' \ - -d '{ - "model": "gpt-5.4", - "stateful": true, - "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "question": "我刚才让你记住的数字是多少？" - }' -``` - -```json -{ - "answer": "你让我记住的数字是 42。", - "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" -} -``` - -> O padrão de `stateful` é `true`, omiti-lo é equivalente a passar explicitamente `true`. Se você não quiser que o servidor salve esta rodada de conversa, pode definir explicitamente `stateful: false`. +Segunda solicitação, inclua o mesmo `id`: +> `stateful` é `true` por padrão; omiti-lo é equivalente a passar explicitamente `true`. Se você não quiser que o servidor salve esta rodada de conversa, pode definir explicitamente `stateful: false`. ## Resposta em streaming -A v2 suporta dois formatos de streaming, selecionados de acordo com o cabeçalho `accept`: +v2 oferece suporte a dois formatos de streaming, selecionados de acordo com o cabeçalho `accept`: | Cenário | `accept` | Formato dos dados | | --------------------- | ---------------------- | ------------------------------------------ | -| Front-end Web / EventSource | `text/event-stream` | `data: {json}\n\n`, última linha `data: [DONE]\n\n` | -| Servidor / CLI / análise de streaming Node | `application/x-ndjson` | Um objeto JSON por linha | +| Front-end Web / EventSource | `text/event-stream` | `data: {json}\n\n`, com a última linha `data: [DONE]\n\n` | +| Servidor / CLI / análise de streaming em Node | `application/x-ndjson` | Um objeto JSON por linha | | Streaming não necessário | `application/json`（padrão） | Retorna `{answer, id}` de uma só vez | ### Exemplo de NDJSON @@ -183,7 +163,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -Cada linha do NDJSON é um evento estruturado, sendo o mais comum `text_delta`: +Cada linha de NDJSON é um evento estruturado, sendo o mais comum `text_delta`: ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +175,7 @@ Cada linha do NDJSON é um evento estruturado, sendo o mais comum `text_delta`: ### Exemplo de SSE -O uso de `EventSource` no navegador não oferece suporte a um corpo de solicitação personalizado; recomenda-se usar `fetch` + análise manual por fatias de `\n\n`: +O uso de `EventSource` no navegador não oferece suporte a um corpo de solicitação personalizado; recomenda-se usar `fetch` + análise manual em fatias por `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +216,24 @@ while (true) { | `type` | Significado | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Fragmento de texto incremental da resposta do assistente. `content` é o conteúdo novo; para compatibilidade com a v1, o mesmo evento também inclui `delta_answer` (igual a `content`) e `id`. | +| `text_delta` | Fragmento de texto incremental da resposta do assistente. `content` é o conteúdo novo; para compatibilidade com v1, o mesmo evento também inclui `delta_answer` (igual a `content`) e `id`. | | `thinking` | Processo de raciocínio do modelo (aparece apenas quando o modelo selecionado expõe reasoning). | | `tool_use` | O modelo decide chamar uma ferramenta; o evento inclui `tool_id`, `tool_name`, `input`. | | `tool_result` | Resultado da execução da ferramenta, emparelhado com o `tool_use` anterior por meio de `tool_id`; `is_error` indica se falhou. | -| `card` | Cartão estruturado produzido pela ferramenta (como imagens, pré-visualizações de links), adequado para renderização direta. | -| `citation` | URL da fonte usada para complementar a citação do fragmento de texto correspondente. | -| `ask_user_question` | Emitido quando o modelo precisa que o usuário complemente informações; a conversa entra no estado `awaiting_user_input`, veja abaixo [retomar uma conversa pausada](#恢复暂停的对话)。 | -| `artifact` | Produto independente gerado pelo modelo (como blocos de código, documentos), que pode ser salvo ou baixado. | -| `system_message` | Mensagem de aviso do sistema (não é conteúdo do usuário nem do assistente), usada apenas para avisos na UI. | +| `card` | Cartão estruturado produzido pela ferramenta (como imagem, prévia de link), adequado para renderização direta. | +| `citation` | URL da fonte usada para complementar citações do fragmento de texto correspondente. | +| `ask_user_question` | Emitido quando o modelo precisa que o usuário complemente informações; a conversa entra no estado `awaiting_user_input`; consulte abaixo [retomar uma conversa pausada](#恢复暂停的对话). | +| `artifact` | Produto independente gerado pelo modelo (como bloco de código, documento), que pode ser salvo ou baixado. | +| `system_message` | Informação de aviso do sistema (não é conteúdo do usuário ou do assistente), usada apenas para avisos na UI. | | `compact` | Evento em que o contexto interno foi compactado, sem necessidade de tratamento especial. | | `error` | Ocorreu um erro nesta rodada; `message` descreve o conteúdo do erro. | -| `done` | A resposta em streaming termina, incluindo `usage` (com `prompt_tokens` / `completion_tokens` / `total_tokens`) e `terminal_reason`. | +| `done` | A resposta em streaming terminou; inclui `usage` (com `prompt_tokens` / `completion_tokens` / `total_tokens`) e `terminal_reason`. | -Para clientes que se preocupam apenas com a resposta final, concatenar o `content` de todos os `text_delta` é equivalente ao `answer` no modo `application/json`. +Para clientes que se importam apenas com a resposta final, concatenar o `content` de todos os `text_delta` é equivalente a `answer` no modo `application/json`. ## Entrada multimodal -Se a entrada do usuário contiver imagens ou arquivos, passe `message` (uma matriz) em vez de `question`. Cada elemento da matriz é um bloco de conteúdo: +Se a entrada do usuário incluir imagens ou arquivos, passe `message` (array) em vez de `question`. Cada elemento do array é um bloco de conteúdo: ```json { @@ -266,30 +246,30 @@ Se a entrada do usuário contiver imagens ou arquivos, passe `message` (uma matr } ``` -Tipos de blocos suportados: +Tipos de bloco compatíveis: -- `text` — Texto comum, campo `text` obrigatório. -- `image_url` — Imagem, `image_url.url` obrigatório. -- `file_url` — Arquivo (PDF, CSV, TXT etc.), `file_url.url` obrigatório. +- `text` — Texto comum; o campo `text` é obrigatório. +- `image_url` — Imagem; `image_url.url` é obrigatório. +- `file_url` — Arquivo (PDF, CSV, TXT etc.); `file_url.url` é obrigatório. -### Relação com `references` da v1 +### Relação com `references` do v1 -Para compatibilidade com clientes antigos, a v2 ainda reconhece o campo `references: ["https://...", ...]`: -- Se o sufixo da URL for `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, converta automaticamente em um bloco `image_url`; -- Outros tipos de extensão são convertidos em um bloco `file_url`; -- Se `question` também for fornecido, coloque-o antes como um bloco `text`. +Para compatibilidade com clientes antigos, v2 ainda reconhece o campo `references: ["https://...", ...]`: +- Se o sufixo da URL for `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, ela será automaticamente convertida em um bloco `image_url`; +- Outros tipos de extensão serão convertidos em um bloco `file_url`; +- Se `question` também for fornecido, ele será colocado antes como um bloco `text`. -Portanto, se você quiser apenas migrar do v1 sem alterar o corpo da solicitação, basta alterar o caminho para `/aichat2/conversations`, e o uso original de `references` continuará funcionando normalmente. +Portanto, se você quiser apenas migrar do v1 sem alterar o corpo da requisição, basta mudar o caminho para `/aichat2/conversations`; o uso original de `references` continuará funcionando normalmente. -Se precisar de um controle mais refinado (por exemplo, colocar várias imagens entre textos, ou quando a ordem for importante), use diretamente o array `message`. +Se precisar de um controle mais refinado (por exemplo, colocar várias imagens entre textos, ou se a ordem for muito importante), use diretamente o array `message`. ## Chamada de ferramentas e MCP -O principal aprimoramento do v2 é que o modelo pode chamar ferramentas de forma autônoma para concluir tarefas em várias etapas, **isso vem ativado por padrão**, sem necessidade de qualquer configuração adicional do cliente na solicitação. Cenários comuns: +O principal aprimoramento do v2 é que o modelo pode chamar ferramentas autonomamente para concluir tarefas de várias etapas, **isso é ativado por padrão**, sem exigir nenhuma configuração adicional do cliente na requisição. Cenários comuns: -- O usuário pergunta: «Pesquise para mim quais exposições novas há recentemente em Xangai» → O modelo chama a busca web integrada → Organiza os resultados em uma resposta. -- O usuário pergunta: «Leia este PDF e depois escreva um resumo» → O modelo chama file_read → Escreve o resumo. -- O usuário já autorizou Google Drive / GitHub / Notion etc. em [Connections](https://platform.acedata.cloud/connections) → O modelo pode chamar as ferramentas MCP correspondentes para ler e escrever seus dados. +- O usuário pergunta: «Pesquise para mim quais novas exposições há recentemente em Xangai» → o modelo chama a busca web integrada → organiza os resultados em uma resposta. +- O usuário pergunta: «Leia este PDF e depois escreva um resumo» → o modelo chama `file_read` → escreve o resumo. +- O usuário já autorizou Google Drive / GitHub / Notion etc. em [Connections](https://platform.acedata.cloud/connections) → o modelo pode chamar as ferramentas MCP correspondentes para ler e escrever seus dados. No fluxo NDJSON / SSE, as chamadas de ferramentas são apresentadas por meio de dois tipos de eventos, `tool_use` e `tool_result`, por exemplo: @@ -301,13 +281,13 @@ No fluxo NDJSON / SSE, as chamadas de ferramentas são apresentadas por meio de ... ``` -Se não quiser exibir os detalhes da chamada de ferramentas no frontend, basta ignorar os eventos dos tipos `tool_use` / `tool_result` / `card` / `citation`; a saída final do modelo ainda será transmitida por `text_delta`. +Se você não quiser exibir os detalhes das chamadas de ferramentas no frontend, basta ignorar os eventos `tool_use` / `tool_result` / `card` / `citation`; a saída final do modelo continuará sendo transmitida por `text_delta`. -`max_turns` pode limitar o número máximo de rodadas em que o modelo pode chamar ferramentas por conta própria nesta solicitação; o limite padrão é determinado pela plataforma. Defini-lo como um valor baixo (por exemplo, `max_turns: 1`) pode forçar uma resposta única e não permitir nenhuma chamada de ferramenta. +`max_turns` pode limitar o número máximo de rodadas em que o modelo pode chamar ferramentas por conta própria nesta requisição, com intervalo de 1–500 e padrão de 500 quando omitido. Defini-lo como um valor baixo (por exemplo, `max_turns: 1`) pode forçar uma resposta única e não permitir nenhuma chamada de ferramenta. -## Execução assíncrona e autorização não assistida +## Execução assíncrona e autorização não supervisionada -Se sua chamada vier de um Webhook de alerta, CI/CD, sistema de monitoramento ou outra tarefa de backend, você pode definir `async: true` para que a interface retorne imediatamente o ID da tarefa e continue executando em segundo plano: +Se a sua chamada vier de um Webhook de alerta, CI/CD, sistema de monitoramento ou outra tarefa em segundo plano, você pode definir `async: true` para que a interface retorne imediatamente o ID da tarefa e continue a execução em segundo plano: ```json { @@ -328,9 +308,9 @@ Exemplo de retorno: } ``` -Depois, você pode usar `action: retrieve` + `id` para consultar o resultado da conversa; também pode fornecer `callback_url`, e após a conclusão da tarefa a plataforma fará POST de `{ status, answer, usage, error }` para o seu endereço de callback. `callback_url` deve usar `http` / `https` e não pode preencher diretamente `localhost` ou um endereço literal de IP privado. +Depois, você pode usar `action: retrieve` + `id` para consultar o resultado da conversa; também pode fornecer `callback_url`, e a plataforma fará POST de `{ status, answer, usage, error }` para o seu endereço de callback após a conclusão da tarefa. `callback_url` deve usar `http` / `https` e não pode preencher diretamente `localhost` ou um endereço IP privado literal. -Normalmente, não há ninguém que possa clicar para confirmar nas tarefas de backend. Se quiser que determinados Skills ou MCP Servers executem ações como enviar, publicar e gravar no modo não assistido, transmita explicitamente a lista de pré-autorização no corpo da solicitação: +Normalmente, ninguém pode clicar para confirmar tarefas em segundo plano. Se você quiser que determinados Skill ou MCP Server executem ações como enviar, publicar ou gravar no modo não supervisionado, passe explicitamente uma lista de pré-autorização no corpo da requisição: ```json { @@ -342,7 +322,7 @@ Normalmente, não há ninguém que possa clicar para confirmar nas tarefas de ba } ``` -Os valores em `allowed_skills` são os slugs dos Skills conectados; os valores em `allowed_mcp_servers` são os slugs dos MCP Servers conectados. Skills / MCP Servers não incluídos na pré-autorização, no modo não assistido, ainda poderão apenas visualizar, executar dry-run ou recusar a execução de operações de escrita. +Os valores em `allowed_skills` são os slugs dos Skills conectados; os valores em `allowed_mcp_servers` são os slugs dos MCP Servers conectados. Skills / MCP Servers não incluídos na pré-autorização ainda poderão apenas visualizar, executar dry-run ou recusar operações de gravação no modo não supervisionado. Se for necessário um controle mais detalhado, também é possível usar o objeto equivalente `unattended_policy`: @@ -356,13 +336,13 @@ Se for necessário um controle mais detalhado, também é possível usar o objet } ``` -A pré-autorização são essas duas listas em si: uma lista vazia significa não autorizar nenhuma capacidade, sem a necessidade de campos de ativação adicionais. +A pré-autorização consiste nessas duas listas: uma lista vazia significa não autorizar nenhuma capacidade, sem necessidade de campos adicionais de ativação. -Observação: a pré-autorização representa apenas que «esta solicitação permite que essas capacidades ignorem a confirmação humana no modo não assistido». O Skill específico ainda deve suportar `--unattended-confirm` ou o mecanismo de segurança correspondente; caso contrário, continuará em dry-run e não executará diretamente operações de escrita. +Observação: a pré-autorização representa apenas que «esta requisição permite que essas capacidades ignorem a confirmação humana no modo não supervisionado». O Skill específico ainda deve oferecer suporte a `--unattended-confirm` ou ao mecanismo de segurança correspondente; caso contrário, ele continuará em dry-run e não executará diretamente operações de gravação. ## Retomar conversas pausadas -Algumas ferramentas fazem com que o modelo «faça uma pergunta ao usuário». Nesse momento, o modelo emitirá um evento `ask_user_question`, e a conversa ficará congelada no estado `awaiting_user_input`: +Algumas ferramentas fazem o modelo «perguntar de volta ao usuário»; nesse momento, o modelo emitirá um evento `ask_user_question`, e a conversa ficará congelada no estado `awaiting_user_input`: ```json { @@ -375,7 +355,7 @@ Algumas ferramentas fazem com que o modelo «faça uma pergunta ao usuário». N } ``` -No frontend, renderize esse evento como um cartão para que o usuário escolha uma resposta e, em seguida, inicie a próxima solicitação usando o mesmo `id`, preenchendo a resposta por meio de `tool_results`: +No frontend, renderize esse evento como um cartão para que o usuário escolha uma resposta e, em seguida, inicie a próxima requisição usando o mesmo `id`, preenchendo a resposta por meio de `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +375,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -O `tool_use_id` no corpo da solicitação **deve** ser exatamente igual ao `tool_id` no momento da pausa; se for diferente, será retornado 400. Quando `tool_results` existir simultaneamente na solicitação, `question` / `message` / `references` serão todos ignorados. +O `tool_use_id` no corpo da requisição **deve** ser exatamente igual ao `tool_id` no momento da pausa; caso sejam diferentes, será retornado 400. Quando `tool_results` estiver presente na requisição, `question` / `message` / `references` serão todos ignorados. -Se o usuário decidir abandonar esta pergunta, basta transmitir um novo `question` / `message`, e a plataforma marcará automaticamente a chamada de ferramenta pausada como «ignorada pelo usuário». +Se o usuário decidir abandonar esta pergunta, basta passar um novo `question` / `message`, e a plataforma marcará automaticamente a chamada de ferramenta pausada como «ignorada pelo usuário». ## Gerenciamento de conversas (CRUD) -O v2 fornece gerenciamento leve de conversas por meio do campo `action` no mesmo endpoint, sem necessidade de criar outra API. +O v2 fornece gerenciamento leve de conversas no mesmo endpoint por meio do campo `action`, sem necessidade de abrir outra API. +### `action: retrieve` —— Recuperar uma conversa -### `action: retrieve` —— Buscar uma conversa ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -417,7 +397,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ Retorna o documento completo da conversa (incluindo o histórico de `messages`, `model`, `title`, `tools_used` etc.). -### `action: retrieve_batch` —— listar resumos de conversas +### `action: retrieve_batch` —— Listar resumos de conversas ```json { @@ -428,23 +408,23 @@ Retorna o documento completo da conversa (incluindo o histórico de `messages`, } ``` -Retorna `{ items: [...], total }`. **Os resumos não incluem `messages`**, sendo adequados para listas na barra lateral; se o usuário abrir uma conversa, use então `action: retrieve` para buscar separadamente suas mensagens completas. +Retorna `{ items: [...], total }`. **Os resumos não contêm `messages`**, sendo adequados para listas de barra lateral; se o usuário abrir uma conversa, use então `action: retrieve` para recuperar separadamente suas mensagens completas. -Parâmetros de filtro opcionais: `user_id`, `application_id`, `model_group`, `model`. +Parâmetros opcionais de filtragem: `user_id`, `application_id`, `model_group`, `model`. -### `action: update` —— alterar o título ou reescrever o histórico +### `action: update` —— Alterar o título ou reescrever o histórico ```json { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "title": "Plano de viagem para Hangzhou" + "title": "杭州旅行计划" } ``` -`messages` também pode ser enviado, mas o servidor realizará uma validação rigorosa do schema (deve estar no formato `ToolUseContent` recolhido), e retornará 400 caso não esteja em conformidade. Em geral, recomenda-se usá-lo apenas para alterar o `title`. +`messages` também pode ser enviado, mas o servidor realizará uma validação rigorosa de schema (deve estar na forma `ToolUseContent` recolhida); caso não esteja em conformidade, retornará 400. Em geral, recomenda-se usá-lo apenas para alterar `title`. -### `action: delete` —— excluir uma conversa +### `action: delete` —— Excluir uma conversa ```json { @@ -453,21 +433,21 @@ Parâmetros de filtro opcionais: `user_id`, `application_id`, `model_group`, `mo } ``` -Retorna `{ id, success: true }`. Após a exclusão, não será possível recuperar, portanto confirme antes de chamar. +Retorna `{ id, success: true }`. Após a exclusão, não é possível recuperar, portanto confirme antes de chamar. -## Migração tranquila da v1 +## Migração suave a partir da v1 -Se você já estiver usando [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), a migração para a v2 quase não exige alterações de código: +Se você já estiver usando [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), quase não será necessário alterar código para migrar para a v2: 1. Altere a URL de `https://api.acedata.cloud/aichat/conversations` para `https://api.acedata.cloud/aichat2/conversations`. -2. Se você anteriormente utilizava nomes de modelos da v1 (como `gpt-3.5`, `gpt-4-browsing` etc.), ao mudar para a v2 é recomendável atualizar para modelos contemporâneos (como `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` etc.). -3. Os campos do fluxo NDJSON permanecem compatíveis com versões anteriores: cada evento `text_delta` continua contendo `delta_answer` e `id`, portanto os clientes que originalmente analisam `delta_answer` por linha não precisam de alterações. +2. Se você enviava anteriormente nomes de modelos v1 (como `gpt-3.5`, `gpt-4-browsing` etc.), é recomendável atualizar para modelos contemporâneos ao mudar para a v2 (como `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` etc.). +3. Os campos do fluxo NDJSON permanecem compatíveis com versões anteriores: cada evento `text_delta` continua contendo `delta_answer` e `id`, portanto os clientes que originalmente analisam `delta_answer` linha a linha não precisam ser alterados. -Após a migração, você pode habilitar, conforme necessário, os novos recursos da v2 (como `message` multimodal, SSE, chamadas de ferramentas, CRUD com `action`) e avançar no seu próprio ritmo. +Após a migração, você pode habilitar conforme necessário os novos recursos da v2 (`message` multimodal, SSE, chamadas de ferramentas, CRUD de `action`), avançando no seu próprio ritmo. ## Tratamento de erros -As respostas de erro são unificadas como: +A resposta de erro é uniformemente: ```json { @@ -481,14 +461,14 @@ As respostas de erro são unificadas como: Erros comuns: -- `400 bad_request`: campos obrigatórios ausentes, incompatibilidade de `tool_use_id`, schema de `messages` inválido etc. +- `400 bad_request`: campos obrigatórios ausentes, `tool_use_id` não corresponde, schema de `messages` inválido etc. - `401 invalid_token`: o cabeçalho `authorization` está incorreto. -- `404 not_found`: a conversa correspondente ao `id` não existe ao usar `action: retrieve / update / delete`. +- `404 not_found`: a conversa correspondente ao `id` não existe durante `action: retrieve / update / delete`. - `429 too_many_requests`: o limite de taxa foi acionado. - `500 chat_error`: erro do LLM upstream ou `completion_tokens=0` nesta rodada (tratado como não consumido, sem cobrança). -Em respostas de streaming, os erros são emitidos como eventos `{"type":"error","message":"..."}`, e o fluxo será encerrado em seguida. +Na resposta de streaming, os erros são emitidos como o evento `{"type":"error","message":"..."}`, e o fluxo será encerrado logo em seguida. ## Conclusão -A API AI Chat v2, mantendo compatibilidade com versões anteriores da v1, atualiza as conversas de «perguntas e respostas de turno único / múltiplos turnos» para «conversas observáveis orientadas a agentes»: entrada multimodal, chamadas de ferramentas, pausa / retomada, eventos estruturados de streaming e CRUD integrado. Recomenda-se que novas integrações utilizem diretamente a v2; integrações existentes da v1 podem migrar gradualmente em fases. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento. +A API AI Chat v2, mantendo compatibilidade retroativa com a v1, atualiza a conversa de «perguntas e respostas de turno único / múltiplos turnos» para «conversas observáveis orientadas por Agent»: entrada multimodal, chamadas de ferramentas, pausa / retomada, eventos estruturados de streaming e CRUD integrado. Recomenda-se que novas integrações usem diretamente a v2; integrações v1 existentes podem migrar suavemente em etapas. Se tiver quaisquer dúvidas, entre em contato com nossa equipe de suporte técnico a qualquer momento. diff --git a/pt/guides/platform/hermes_managed.mdx b/pt/guides/platform/hermes_managed.mdx index ce6af4b1c..9a97c22d4 100644 --- a/pt/guides/platform/hermes_managed.mdx +++ b/pt/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Private Deployment" +title: "Implantação do Hermes" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud oferece a entrada para a implantação privada do Hermes Agent. Esta entrada é um serviço controlado, e a disponibilidade e os recursos opcionais estão sujeitos ao que é exibido atualmente no console. +Crie uma instância de contêiner Hermes independente para cada Application. Por padrão, utiliza imagens base de versões de lançamento fixas, preservando as funcionalidades nativas; a plataforma oferece compra, renovação, armazenamento persistente e gerenciamento de implantação. -## Passos para Uso +## Criação e compra -1. Encontre **Hermes Agent Private Deployment** na plataforma. -2. Siga as instruções na página para selecionar a configuração disponível e criar o serviço. -3. Aguarde o status de prontidão exibido pela plataforma. -4. Use a entrada e as credenciais fornecidas na página para acessar a instância. -5. Primeiro envie `Reply only OK`, e então comece a tarefa real. +1. Abra [Implantação do Hermes](https://platform.acedata.cloud/services/hermes) e crie uma Application. +2. Na página de compra, selecione um pacote de duração e conclua o pagamento. +3. Retorne à página de configuração, onde é possível selecionar um modelo de chat da plataforma na lista suspensa e visualizar o preço do modelo atual. A plataforma criará credenciais de API independentes para esta instância; também é possível desativar a integração da plataforma e configurar por conta própria no console nativo. +4. Escolha gerar automaticamente as credenciais de acesso ou defina sua própria senha forte/Token e, após confirmar, inicie a implantação. As credenciais de acesso e as credenciais da API do modelo são independentes entre si. +5. Quando a instância estiver pronta, obtenha o endereço de acesso e as credenciais de login na página de gerenciamento. +6. Faça login no console nativo e configure seus próprios provedores de modelo, chaves e canais. -Modelos, credenciais, armazenamento e comportamentos de exclusão estão sujeitos à página de criação e à janela de confirmação; não trate o YAML do tutorial local do Hermes como um contrato de implantação da plataforma. Exporte os dados que precisam ser mantidos antes de excluir. +A taxa de implantação é cobrada de acordo com a duração do pacote; os preços específicos em dólares americanos e as durações prevalecem conforme a página de compra. As taxas de chamada de modelo são cobradas separadamente; a compra de duração de implantação não concede créditos de modelo. Quando a integração da plataforma está ativada, as credenciais de API exclusivas disponibilizam apenas a interface de chat correspondente ao modelo selecionado, e as chamadas são cobradas separadamente do saldo da sua plataforma. Cada Application é comprada, renovada e gerenciada separadamente. -Se o console não exibir a entrada de criação, isso significa que a conta atual ainda não tem esse serviço disponível, podendo-se usar o [Assistente Interativo do Hermes](https://platform.acedata.cloud/documents/hermes-wizard-integration) ou [Configuração Manual](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Senhas, credenciais e configurações posteriores + +As credenciais de acesso são definidas antes da primeira inicialização. A geração automática utiliza credenciais aleatórias, a senha personalizada deve ter pelo menos 16 caracteres, e o OpenClaw Token deve ter pelo menos 32 caracteres. Rascunhos não salvam senhas; pode ser necessário inseri-las novamente após trocar de página. Após a implantação, apenas o proprietário e os administradores da Application podem visualizar as credenciais de acesso. + +As credenciais de API do modelo de cada instância não são reutilizadas entre si, têm sua validade estendida com a renovação da implantação e são revogadas quando a instância é excluída. Após a inicialização da implantação, modifique os modelos e canais no console nativo; se selecionar modelos de outros serviços, primeiro ajuste a autorização da interface correspondente no gerenciamento de credenciais da plataforma ou utilize as credenciais correspondentes. Uma reimplantação comum não substituirá as configurações nativas. Ambientes de implantação que não passaram pela validação de publicação recusarão temporariamente novas implantações; entre em contato com o suporte. + +## Versões e dados + +A página de configuração exibe a versão da imagem atualmente publicada. Novas instâncias utilizam a versão atualmente publicada do serviço; instâncias existentes não são substituídas automaticamente com as atualizações do catálogo. A reimplantação aplicará a versão atual do serviço; faça backup primeiro e confirme os requisitos de atualização da versão utilizada. + +Cada instância fornece por padrão 1 CPU, limite de 2 GiB de memória e 10 GiB de armazenamento persistente. As reinicializações preservam os dados da instância. A exclusão ativa da implantação ou a recuperação após o vencimento excluirão o armazenamento; exporte antecipadamente os dados que precisam ser preservados. + +## Renovação e vencimento + +Renove na página de compra da Application atual, e a validade será estendida conforme as regras de duração existentes da plataforma. Após o vencimento, o ponto de acesso é suspenso; renovar dentro do período de carência restaura o acesso; após ultrapassar o período de carência, a instância e os dados serão recuperados. Prevalecem o horário de vencimento, o status de cobrança e os avisos de exclusão na página de gerenciamento. + +## Login na interface de gerenciamento + +Na página de gerenciamento da implantação, copie o endereço do Dashboard, o nome de usuário `admin` e a senha, abra-o e faça login. As informações de login são fornecidas apenas ao proprietário da Application e aos administradores da plataforma. Modelos, habilidades e canais são configurados na interface nativa do Hermes. + +## Perguntas frequentes + +- **Por que a nova instância ainda não consegue responder?** A conclusão da implantação indica que o contêiner está pronto; é necessário configurar o modelo e as credenciais na interface nativa antes de começar a usar. +- **Há plugins adicionais ou fallback de modelo pré-instalados?** Por padrão, não são adicionados; configure-os conforme necessário na interface nativa. +- **Como atualizar uma instância existente?** A Application e o pedido originais são mantidos, e a versão atual do serviço é usada ao reimplantar; faça backup dos dados e verifique a compatibilidade da versão antes da atualização. +- **O que fazer se a inicialização falhar?** Primeiro, verifique os logs e eventos da implantação e configure o modelo somente após confirmar que a instância está pronta. Não exponha a senha e as chaves da instância em comentários públicos ou capturas de tela. diff --git a/pt/guides/platform/wework_bot.mdx b/pt/guides/platform/wework_bot.mdx deleted file mode 100644 index 1fadee49e..000000000 --- a/pt/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/ru/guides/aichat/aichat2_conversations.mdx index 7a51c15ba..2001d9dcb 100644 --- a/ru/guides/aichat/aichat2_conversations.mdx +++ b/ru/guides/aichat/aichat2_conversations.mdx @@ -1,30 +1,30 @@ --- -title: "Руководство по интеграции AI Chat v2 API" +title: "Инструкции по интеграции AI Chat v2 API" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API (`/aichat2/conversations`) — это интерфейс диалогов нового поколения и полностью обновлённая версия [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). На основе лаконичного v1 с управляемыми многораундовыми диалогами он расширяет возможности: +AI Chat v2 API (`/aichat2/conversations`) — это интерфейс нового поколения для диалогов, представляющий собой комплексно обновлённую версию [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). На основе лаконичности и хостинга многораундовых диалогов v1 он расширяет: - **Мультимодальный пользовательский ввод**: напрямую передавайте текст + изображения + файловые блоки через структурированное поле `message`, без необходимости предварительно косвенно прикреплять их с помощью `references`. -- **Вызовы инструментов в стиле Agent**: включает набор инструментов для веб-поиска, извлечения веб-страниц, чтения файлов и т. д., а также позволяет подключать авторизованные пользователем MCP-серверы (Google Drive, Notion, Slack, GitHub и т. д.); модель может самостоятельно многократно вызывать инструменты в рамках одного запроса для выполнения сложных задач. -- **Структурированные потоковые события**: через `accept: text/event-stream` или `application/x-ndjson` можно получать события `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` и другие для каждого токена, что упрощает отдельный рендеринг по соответствующим типам на фронтенде. -- **Возможность прерывания / возобновления**: когда модели требуется дополнительная информация от пользователя, она отправляет событие `ask_user_question` и приостанавливается; при следующем вызове можно продолжить, передав ответ обратно через `tool_results`. -- **Новые CRUD-действия**: выполняйте `retrieve` / `retrieve_batch` / `update` / `delete` через поле `action` на том же endpoint, без необходимости в дополнительном API управления диалогами. +- **Вызов инструментов в стиле Agent**: встроенный набор инструментов для поиска в интернете, извлечения веб-страниц, чтения файлов и т. д., с возможностью подключения авторизованных пользователем MCP-серверов (Google Drive, Notion, Slack, GitHub и др.); модель может самостоятельно многократно вызывать инструменты в рамках одного запроса для выполнения сложных задач. +- **Структурированные потоковые события**: через `accept: text/event-stream` или `application/x-ndjson` можно получать события `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` и другие на уровне токенов, что позволяет отдельно рендерить их во фронтенде в соответствии с их типами. +- **Возможность прерывания / возобновления**: когда модели требуется дополнительная информация от пользователя, она отправляет событие `ask_user_question` и приостанавливается; при следующем вызове можно продолжить, передав ответ через `tool_results`. +- **Новые CRUD-действия**: выполняйте `retrieve` / `retrieve_batch` / `update` / `delete` через поле `action` на том же endpoint, без необходимости в дополнительном API для управления диалогами. - **Постоянно обновляемый список моделей**: по умолчанию подключены современные модели, такие как GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 и другие. -При этом на уровне тела запроса он **полностью обратно совместим с v1**: достаточно передать только `model` + `question` (+ опциональные `stateful` / `id` / `references` / `preset`), чтобы получить JSON-ответ `{answer, id}`, эквивалентный v1. Поэтому при миграции с `/aichat/conversations` не нужно переписывать клиент — достаточно заменить путь на `/aichat2/conversations`. +При этом на уровне тела запроса он **полностью обратно совместим с v1**: достаточно передать `model` + `question` (+ необязательные `stateful` / `id` / `references` / `preset`), чтобы получить JSON-ответ `{answer, id}`, эквивалентный v1. Поэтому при миграции с `/aichat/conversations` не нужно переписывать клиент — достаточно заменить путь на `/aichat2/conversations`. -> Если вы сейчас используете `/aichat/conversations`, старый интерфейс продолжит обслуживаться, и вы можете мигрировать в удобном для вас темпе. +> Если вы сейчас используете `/aichat/conversations`, старый интерфейс продолжит работать, и вы можете мигрировать в удобном для себя темпе. -## Процесс получения доступа +## Процесс подачи заявки Чтобы использовать AI Chat v2 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). > 📘 Полная документация: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Доступные значения `model` можно напрямую увидеть в выпадающем списке панели Try справа; часто используемые категории включают: +Доступные значения `model` можно непосредственно увидеть в выпадающем списке панели Try справа; распространённые категории включают: - OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` и другие - Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` и другие @@ -86,7 +86,7 @@ print(response.json()) - Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` и другие - Zhipu: `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` и другие -Конкретные правила тарификации приведены в карточке Pricing на странице сервиса. +Подробные правила тарификации см. в карточке Pricing на странице сервиса. ## Многораундовый диалог @@ -140,12 +140,12 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ ## Потоковый ответ -v2 поддерживает два потоковых формата, выбор осуществляется по заголовку `accept`: +v2 поддерживает два потоковых формата, которые выбираются по заголовку `accept`: | Сценарий | `accept` | Формат данных | | --------------------- | ---------------------- | ------------------------------------------ | -| Web-фронтенд / EventSource | `text/event-stream` | `data: {json}\n\n`, последняя строка `data: [DONE]\n\n` | -| Сервер / CLI / потоковый разбор Node | `application/x-ndjson` | Один объект JSON в каждой строке | +| Web-фронтенд / EventSource | `text/event-stream` | `data: {json}\n\n`, последняя строка — `data: [DONE]\n\n` | +| Сервер / CLI / потоковый парсинг Node | `application/x-ndjson` | Один JSON-объект в каждой строке | | Потоковый режим не требуется | `application/json`（по умолчанию） | Однократно возвращает `{answer, id}` | ### Пример NDJSON @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -Каждая строка NDJSON является структурированным событием, наиболее распространённое — `text_delta`: +Каждая строка NDJSON является структурированным событием, наиболее распространённое из них — `text_delta`: ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -236,24 +236,24 @@ while (true) { | `type` | Значение | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Инкрементальный текстовый фрагмент ответа ассистента. `content` содержит добавленное содержимое; для совместимости с v1 то же событие также содержит `delta_answer` (равный `content`) и `id`. | -| `thinking` | Процесс рассуждений модели (появляется только когда выбранная модель предоставляет reasoning). | +| `text_delta` | Инкрементальный текстовый фрагмент ответа ассистента. `content` содержит новое содержимое; для совместимости с v1 это же событие также содержит `delta_answer` (равный `content`) и `id`. | +| `thinking` | Процесс рассуждения модели (появляется только если выбранная модель раскрывает reasoning). | | `tool_use` | Модель решила вызвать инструмент; событие содержит `tool_id`, `tool_name`, `input`. | -| `tool_result` | Результат выполнения инструмента; сопоставляется с предыдущим `tool_use` через `tool_id`, `is_error` указывает, произошла ли ошибка. | +| `tool_result` | Результат выполнения инструмента, сопоставляется с предыдущим `tool_use` через `tool_id`; `is_error` указывает, произошла ли ошибка. | | `card` | Структурированная карточка, созданная инструментом (например, изображение, предпросмотр ссылки), подходит для прямого рендеринга. | -| `citation` | Используется для дополнения URL источника цитирования соответствующего текстового фрагмента. | -| `ask_user_question` | Отправляется, когда модели нужна дополнительная информация от пользователя; диалог переходит в состояние `awaiting_user_input`, подробнее см. ниже в разделе [Возобновление приостановленного диалога](#恢复暂停的对话). | -| `artifact` | Независимый результат, созданный моделью (например, блок кода, документ), который можно сохранить или скачать. | -| `system_message` | Системное информационное сообщение (не содержимое пользователя или ассистента), используется только для подсказок UI. | -| `compact` | Событие сжатия внутреннего контекста, не требует специальной обработки. | -| `error` | В этом раунде произошла ошибка; `message` описывает содержимое ошибки. | +| `citation` | URL источника, используемый для дополнения цитаты к соответствующему текстовому фрагменту. | +| `ask_user_question` | Отправляется, когда модели требуется, чтобы пользователь дополнил информацию; диалог переходит в состояние `awaiting_user_input`, подробнее ниже в разделе [Возобновление приостановленного диалога](#恢复暂停的对话). | +| `artifact` | Самостоятельный артефакт, созданный моделью (например, блок кода, документ), который можно сохранить или скачать. | +| `system_message` | Системное информационное сообщение (не содержимое пользователя или ассистента), используется только для подсказок в UI. | +| `compact` | Событие, при котором внутренний контекст был сжат; специальная обработка не требуется. | +| `error` | В этом раунде произошла ошибка; `message` описывает её содержимое. | | `done` | Потоковый ответ завершён; содержит `usage` (включая `prompt_tokens` / `completion_tokens` / `total_tokens`) и `terminal_reason`. | -Для клиентов, которых интересует только окончательный ответ, объединение `content` всех `text_delta` эквивалентно `answer` в режиме `application/json`. +Для клиентов, которым важен только окончательный ответ, объединение `content` всех `text_delta` эквивалентно `answer` в режиме `application/json`. ## Мультимодальный ввод -Если ввод пользователя содержит изображения или файлы, передавайте `message` (массив) вместо `question`. Каждый элемент массива является блоком содержимого: +Если пользовательский ввод содержит изображения или файлы, передавайте `message` (массив) вместо `question`. Каждый элемент массива — это блок содержимого: ```json { @@ -275,23 +275,23 @@ while (true) { ### Связь с `references` v1 Для совместимости со старыми клиентами v2 по-прежнему распознаёт поле `references: ["https://...", ...]`: -- Если суффикс URL — `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, автоматически преобразовывать в блок `image_url`; -- Другие расширения преобразовывать в блок `file_url`; -- Если одновременно также предоставлен `question`, то помещать его впереди как блок `text`. +- Если URL имеет расширение `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, он автоматически преобразуется в блок `image_url`; +- Другие расширения преобразуются в блок `file_url`; +- Если одновременно предоставлен `question`, он добавляется в начало как блок `text`. -Поэтому, если вы хотите только перейти с v1 и не хотите менять тело запроса, достаточно заменить путь на `/aichat2/conversations`, исходное использование `references` продолжит работать как обычно. +Поэтому, если вы хотите лишь мигрировать с v1 и не хотите менять тело запроса, достаточно изменить путь на `/aichat2/conversations`, и исходное использование `references` будет работать как обычно. -Если нужен более точный контроль (например, размещать несколько изображений между текстами или если порядок очень важен), напрямую используйте массив `message`. +Если нужен более точный контроль (например, разместить несколько изображений между текстом или если важен порядок), напрямую используйте массив `message`. -## Вызов инструментов и MCP +## Вызовы инструментов и MCP -Ключевое улучшение v2 состоит в том, что модель может самостоятельно вызывать инструменты для выполнения многошаговых задач, **это включено по умолчанию**, и клиенту не нужно выполнять какую-либо дополнительную настройку в запросе. Типичные сценарии: +Ключевое улучшение v2 заключается в том, что модель может самостоятельно вызывать инструменты для выполнения многошаговых задач, **это включено по умолчанию**, и клиенту не требуется выполнять какую-либо дополнительную настройку в запросе. Типичные сценарии: -- Пользователь спрашивает: «Помоги мне поискать, какие новые выставки недавно проходят в Шанхае» → модель вызывает встроенный web search → упорядочивает результаты в ответ. -- Пользователь спрашивает: «Прочитай этот PDF, а затем напиши краткое содержание» → модель вызывает file_read → пишет краткое содержание. -- Пользователь уже авторизовал Google Drive / GitHub / Notion и т. д. в [Connections](https://platform.acedata.cloud/connections) → модель может вызывать соответствующие MCP-инструменты для чтения и записи их данных. +- Пользователь спрашивает: «Помоги мне найти, какие новые выставки недавно проходят в Шанхае» → модель вызывает встроенный web search → организует результаты в ответ. +- Пользователь спрашивает: «Прочитай этот PDF и затем напиши краткое содержание» → модель вызывает file_read → пишет краткое содержание. +- Пользователь уже авторизовал Google Drive / GitHub / Notion и т. д. в [Connections](https://platform.acedata.cloud/connections) → модель может вызывать соответствующие инструменты MCP для чтения и записи их данных. -В потоках NDJSON / SSE вызовы инструментов представлены двумя типами событий: `tool_use` и `tool_result`, например: +В потоке NDJSON / SSE вызовы инструментов представлены двумя типами событий: `tool_use` и `tool_result`, например: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,13 +301,13 @@ while (true) { ... ``` -Если вы не хотите отображать на фронтенде детали вызовов инструментов, достаточно игнорировать события типов `tool_use` / `tool_result` / `card` / `citation`, итоговый вывод модели всё равно передаётся через поток `text_delta`. +Если вы не хотите отображать во фронтенде детали вызовов инструментов, достаточно игнорировать события типов `tool_use` / `tool_result` / `card` / `citation`; итоговый вывод модели по-прежнему передаётся через `text_delta`. -`max_turns` может ограничивать, сколько раундов модель может самостоятельно вызывать инструменты в данном запросе, верхний предел по умолчанию определяется платформой. Установив небольшое значение (например, `max_turns: 1`), можно принудительно ограничить ответ одним разом и не разрешать никакие вызовы инструментов. +`max_turns` может ограничить максимальное количество раундов самостоятельных вызовов инструментов моделью в этом запросе, диапазон — 1–500, по умолчанию при пропуске — 500. Если установить небольшое значение (например, `max_turns: 1`), можно принудительно задать однократный ответ и запретить любые вызовы инструментов. -## Асинхронное выполнение и авторизация без присмотра +## Асинхронное выполнение и авторизация без участия пользователя -Если ваш вызов поступает из Webhook оповещений, CI/CD, системы мониторинга или других фоновых задач, можно установить `async: true`, чтобы интерфейс немедленно вернул ID задачи, а выполнение продолжилось в фоне: +Если ваш вызов поступает из webhook оповещений, CI/CD, системы мониторинга или других фоновых задач, можно установить `async: true`, чтобы интерфейс немедленно вернул ID задачи, а выполнение продолжилось в фоне: ```json { @@ -328,9 +328,9 @@ while (true) { } ``` -После этого можно использовать `action: retrieve` + `id` для запроса результата беседы; также можно предоставить `callback_url`, и после завершения задачи платформа выполнит POST `{ status, answer, usage, error }` на ваш адрес обратного вызова. `callback_url` должен использовать `http` / `https` и не может напрямую содержать `localhost` или литеральный адрес частного IP. +После этого можно использовать `action: retrieve` + `id` для запроса результата беседы; также можно указать `callback_url`, и после завершения задачи платформа отправит `{ status, answer, usage, error }` методом POST на ваш адрес обратного вызова. `callback_url` должен использовать `http` / `https` и не может непосредственно содержать `localhost` или литеральный адрес частного IP. -Для фоновых задач обычно некому нажать подтверждение. Если вы хотите, чтобы определённые Skill или MCP Server выполняли действия отправки, публикации, записи и т. д. в режиме без присмотра, явно передайте в теле запроса список предварительных разрешений: +Для фоновых задач обычно нет человека, который может нажать подтверждение. Если вы хотите, чтобы определённые Skill или MCP Server выполняли действия отправки, публикации, записи и т. п. в режиме без участия пользователя, явно передайте список предварительной авторизации в теле запроса: ```json { @@ -342,7 +342,7 @@ while (true) { } ``` -Значения в `allowed_skills` — это slug подключённых Skill; значения в `allowed_mcp_servers` — это slug подключённых MCP Server. Skill / MCP Server, не включённые в предварительную авторизацию, в режиме без присмотра по-прежнему могут только предварительно просматривать, выполнять dry-run или отказываться выполнять операции записи. +Значения в `allowed_skills` — это slug подключённых Skill; значения в `allowed_mcp_servers` — это slug подключённых MCP Server. Skill / MCP Server, не включённые в предварительную авторизацию, в режиме без участия пользователя по-прежнему могут только выполнять предварительный просмотр, dry-run или отказываться от выполнения операций записи. Если требуется более детальный контроль, также можно использовать эквивалентный объект `unattended_policy`: @@ -356,13 +356,13 @@ while (true) { } ``` -Предварительная авторизация — это сами эти два списка: пустой список означает, что никакие возможности не авторизованы, дополнительные поля-переключатели не требуются. +Предварительная авторизация — это сами эти два списка: пустой список означает отсутствие авторизации для любых возможностей, дополнительные поля-переключатели не требуются. -Обратите внимание: предварительная авторизация означает только «в этом запросе этим возможностям разрешено пропустить ручное подтверждение в режиме без присмотра». Конкретный Skill всё равно должен поддерживать `--unattended-confirm` или соответствующий механизм безопасности; иначе он продолжит выполнять dry-run и не будет напрямую выполнять операции записи. +Обратите внимание: предварительная авторизация означает только «этому запросу разрешено пропускать ручное подтверждение для этих возможностей в режиме без участия пользователя». Конкретный Skill всё равно должен поддерживать `--unattended-confirm` или соответствующий механизм безопасности; иначе он продолжит выполнять dry-run и не будет напрямую выполнять операции записи. -## Возобновление приостановленного диалога +## Возобновление приостановленных бесед -Некоторые инструменты заставляют модель «задавать пользователю встречный вопрос», в этот момент модель отправляет событие `ask_user_question`, а диалог замораживается в состоянии `awaiting_user_input`: +Некоторые инструменты могут заставить модель «задать пользователю встречный вопрос»; в этот момент модель отправляет событие `ask_user_question`, а беседа замораживается в состоянии `awaiting_user_input`: ```json { @@ -375,7 +375,7 @@ while (true) { } ``` -На фронтенде отрисуйте это событие как карточку, чтобы пользователь выбрал ответ, затем выполните следующий запрос с тем же `id`, передав ответ обратно через `tool_results`: +Во фронтенде отобразите это событие в виде карточки, чтобы пользователь выбрал ответ, затем отправьте следующий запрос с тем же `id`, передав ответ обратно через `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -`tool_use_id` в теле запроса **должен** полностью совпадать с `tool_id` на момент приостановки; при несовпадении будет возвращён 400. Когда в запросе одновременно присутствует `tool_results`, `question` / `message` / `references` будут проигнорированы. +`tool_use_id` в теле запроса **обязательно** должен полностью совпадать с `tool_id` во время приостановки; при несовпадении будет возвращён 400. Когда в запросе одновременно присутствует `tool_results`, `question` / `message` / `references` будут проигнорированы. -Если пользователь решит отказаться от этого вопроса, достаточно напрямую передать новый `question` / `message`, платформа автоматически пометит приостановленный вызов инструмента как «пропущен пользователем». +Если пользователь решит отказаться от этого вопроса, достаточно напрямую передать новый `question` / `message`, и платформа автоматически отметит приостановленный вызов инструмента как «пропущен пользователем». -## Управление диалогами (CRUD) +## Управление беседами (CRUD) -v2 предоставляет лёгкое управление диалогами на том же endpoint через поле `action`, без необходимости открывать отдельный API. +v2 предоставляет облегчённое управление беседами через поле `action` на том же endpoint, без необходимости создавать отдельный API. +### `action: retrieve` —— получить один диалог -### `action: retrieve` —— Получить диалог ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Возвращает полный документ беседы (включая историю `messages`, `model`, `title`, `tools_used` и т. д.). +Возвращает полный документ диалога (включая историю `messages`, `model`, `title`, `tools_used` и т. д.). -### `action: retrieve_batch` —— вывод сводок бесед +### `action: retrieve_batch` —— вывести список сводок диалогов ```json { @@ -428,7 +428,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -Возвращает `{ items: [...], total }`. **Сводки не содержат `messages`**, что подходит для списка на боковой панели; если пользователь открывает определённую беседу, затем используйте `action: retrieve`, чтобы отдельно получить её полные сообщения. +Возвращает `{ items: [...], total }`. **Сводки не содержат `messages`**, что подходит для списка на боковой панели; если пользователь открывает определённый диалог, затем используйте `action: retrieve`, чтобы отдельно получить его полные сообщения. Необязательные параметры фильтрации: `user_id`, `application_id`, `model_group`, `model`. @@ -438,13 +438,13 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "title": "杭州旅行计划" + "title": "План поездки в Ханчжоу" } ``` -Также можно передать `messages`, но сервер выполнит строгую проверку schema (обязательно должна быть свёрнутая форма `ToolUseContent`); при несоответствии будет возвращён код 400. Обычно рекомендуется использовать это только для изменения `title`. +Также можно передать `messages`, но сервер выполнит строгую проверку schema (должна быть форма свёрнутого `ToolUseContent`); при несоответствии будет возвращён 400. Как правило, рекомендуется использовать это только для изменения `title`. -### `action: delete` —— удалить одну беседу +### `action: delete` —— удалить один диалог ```json { @@ -453,21 +453,21 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -Возвращает `{ id, success: true }`. После удаления восстановление невозможно, пожалуйста, подтвердите перед вызовом. +Возвращает `{ id, success: true }`. После удаления восстановление невозможно, подтвердите действие перед вызовом. ## Плавная миграция с v1 -Если вы уже используете [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), миграция на v2 практически не требует изменений кода: +Если вы уже используете [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), миграция на v2 почти не требует изменений в коде: 1. Измените URL с `https://api.acedata.cloud/aichat/conversations` на `https://api.acedata.cloud/aichat2/conversations`. -2. Если ранее вы передавали имена моделей v1 (например, `gpt-3.5`, `gpt-4-browsing` и т. д.), при переходе на v2 рекомендуется обновиться до современных моделей (например, `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` и т. д.). -3. Поля NDJSON-потока сохраняют обратную совместимость: каждое событие `text_delta` по-прежнему содержит `delta_answer` и `id`, поэтому клиентам, которые исходно построчно разбирают `delta_answer`, не требуется вносить изменения. +2. Если ранее вы передавали имя модели v1 (например, `gpt-3.5`, `gpt-4-browsing` и т. д.), при переходе на v2 рекомендуется обновиться до современных моделей (например, `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` и т. д.). +3. Поля потока NDJSON сохраняют обратную совместимость: каждое событие `text_delta` по-прежнему содержит `delta_answer` и `id`, поэтому клиентам, которые ранее построчно разбирали `delta_answer`, не требуется вносить изменения. После миграции вы можете по мере необходимости включать новые возможности v2 (мультимодальные `message`, SSE, вызовы инструментов, CRUD через `action`) и внедрять их в удобном темпе. ## Обработка ошибок -Ответ об ошибке имеет единый формат: +Ответы с ошибками имеют единый формат: ```json { @@ -481,14 +481,14 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ Распространённые ошибки: -- `400 bad_request`: отсутствуют обязательные поля, `tool_use_id` не совпадает, schema `messages` недопустима и т. д. +- `400 bad_request`: отсутствуют обязательные поля, не совпадает `tool_use_id`, недопустимая schema `messages` и т. д. - `401 invalid_token`: заголовок `authorization` указан неверно. -- `404 not_found`: при `action: retrieve / update / delete` беседа, соответствующая `id`, не существует. +- `404 not_found`: при `action: retrieve / update / delete` диалог, соответствующий `id`, не существует. - `429 too_many_requests`: сработало ограничение частоты запросов. -- `500 chat_error`: ошибка вышестоящей LLM или в текущем запросе `completion_tokens=0` (обрабатывается как отсутствие потребления, плата не взимается). +- `500 chat_error`: ошибка вышестоящей LLM или в текущем запросе `completion_tokens=0` (обрабатывается как неиспользованный запрос, плата не взимается). -В потоковом ответе ошибка отправляется в виде события `{"type":"error","message":"..."}`, после чего поток сразу завершается. +В потоковом ответе ошибка отправляется событием `{"type":"error","message":"..."}`, после чего поток немедленно завершается. ## Заключение -AI Chat v2 API, сохраняя обратную совместимость с v1, повышает уровень диалогов с «однораундовых / многораундовых вопросов и ответов» до «наблюдаемых Agent-диалогов»: мультимодальный ввод, вызовы инструментов, возможность приостановки / возобновления, потоковые структурированные события, встроенный CRUD. Для новых интеграций рекомендуется сразу использовать v2; существующие интеграции v1 можно плавно переносить поэтапно. Если у вас возникнут какие-либо вопросы, пожалуйста, в любое время свяжитесь с нашей командой технической поддержки. +AI Chat v2 API, сохраняя обратную совместимость с v1, обновляет диалоги от «одиночных / многораундовых вопросов и ответов» до «наблюдаемых диалогов с агентной архитектурой»: мультимодальный ввод, вызовы инструментов, возможность приостановки / возобновления, потоковые структурированные события, встроенный CRUD. Для новых интеграций рекомендуется сразу использовать v2; существующие интеграции v1 можно плавно мигрировать поэтапно. Если у вас возникнут какие-либо вопросы, пожалуйста, в любое время свяжитесь с нашей службой технической поддержки. diff --git a/ru/guides/platform/hermes_managed.mdx b/ru/guides/platform/hermes_managed.mdx index 43ee11d5e..9d0327840 100644 --- a/ru/guides/platform/hermes_managed.mdx +++ b/ru/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Частное развертывание" +title: "Развертывание Hermes" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud предоставляет вход для частного развертывания Hermes Agent. Этот вход является контролируемым сервисом, доступность и доступные ресурсы определяются текущим отображением в консоли. +Для каждого Application создаётся отдельный экземпляр контейнера Hermes. По умолчанию используется базовый образ с фиксированной версией релиза с сохранением нативных функций; платформа предоставляет покупку, продление, постоянное хранилище и управление развертыванием. -## Шаги использования +## Создание и покупка -1. Найдите на платформе **Частное развертывание Hermes Agent**. -2. Выберите доступные конфигурации и создайте сервис в соответствии с подсказками на странице. -3. Дождитесь отображения статуса готовности на платформе. -4. Используйте предоставленный на странице вход и учетные данные для доступа к экземпляру. -5. Сначала отправьте `Reply only OK`, затем начните реальную задачу. +1. Откройте [Развертывание Hermes](https://platform.acedata.cloud/services/hermes) и создайте Application. +2. На странице покупки выберите пакет по сроку, завершите оплату. +3. Вернитесь на страницу конфигурации, выберите модель чата платформы из выпадающего списка и просмотрите текущую цену модели. Платформа создаст независимые API-учётные данные для этого экземпляра; также можно отключить доступ через платформу и выполнить настройку самостоятельно в нативной консоли. +4. Выберите автоматическое создание учётных данных доступа или задайте собственный надёжный пароль/Token, после подтверждения начнётся развертывание. Учётные данные доступа и API-учётные данные модели независимы друг от друга. +5. После готовности экземпляра получите адрес доступа и учётные данные для входа на странице управления. +6. Войдите в нативную консоль и настройте собственных поставщиков моделей, ключи и каналы. -Модель, учетные данные, хранение и действия по удалению определяются страницей создания и подтверждающим окном; не используйте YAML из локального руководства Hermes как контракт для развертывания на платформе. Перед удалением сначала экспортируйте данные, которые необходимо сохранить. +Стоимость развертывания рассчитывается по сроку пакета; конкретная цена в долларах США и срок указаны на странице покупки. Стоимость вызовов моделей оплачивается отдельно; покупка срока развертывания не предоставляет квоту модели. При включённом доступе через платформу выделенные API-учётные данные предоставляют только интерфейс чата для выбранной модели, а вызовы дополнительно списываются с вашего баланса на платформе. Каждый Application приобретается, продлевается и управляется отдельно. -Если консоль не отображает вход для создания, это означает, что текущая учетная запись еще не открыла этот сервис, можно использовать [Интерактивный помощник Hermes](https://platform.acedata.cloud/documents/hermes-wizard-integration) или [Ручную настройку](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Пароли, учётные данные и последующая конфигурация + +Учётные данные доступа задаются до первого запуска. При автоматическом создании используются случайные учётные данные, пользовательский пароль должен содержать не менее 16 символов, а OpenClaw Token — не менее 32 символов. Черновики не сохраняют пароли; после переключения страницы может потребоваться повторный ввод. После развертывания только владелец Application и администраторы могут просматривать учётные данные доступа. + +API-учётные данные модели каждого экземпляра не используются совместно, их срок действия продлевается при продлении развертывания, а при удалении экземпляра они отзываются. После инициализации развертывания изменяйте модели и каналы в нативной консоли; если выбираете модели других сервисов, сначала настройте авторизацию соответствующего интерфейса в управлении учётными данными платформы или используйте соответствующие учётные данные. Обычное повторное развертывание не перезаписывает нативные настройки. Среды развертывания, не прошедшие проверку публикации, временно отклоняют новые развертывания; обратитесь в поддержку. + +## Версии и данные + +На странице конфигурации отображается версия текущего опубликованного образа. Новые экземпляры используют текущую опубликованную версию сервиса; существующие экземпляры не заменяются автоматически при обновлении каталога. Повторное развертывание применит текущую версию сервиса; сначала создайте резервную копию и подтвердите требования к обновлению используемой версии. + +Каждый экземпляр по умолчанию предоставляет 1 CPU, лимит памяти 2 GiB и 10 GiB постоянного хранилища. При перезапуске данные экземпляра сохраняются. При ручном удалении развертывания или освобождении после истечения срока хранилище будет удалено; заранее экспортируйте данные, которые необходимо сохранить. + +## Продление и истечение срока + +Продлите срок на странице покупки текущего Application, и срок действия будет продлён согласно действующим правилам платформы. После истечения срока точка доступа приостанавливается, а продление в течение льготного периода восстанавливает доступ; после окончания льготного периода экземпляр и данные будут освобождены. Ориентируйтесь на время истечения срока, статус оплаты и уведомления об удалении на странице управления. + +## Вход в интерфейс управления + +На странице управления развертыванием скопируйте адрес Dashboard, имя пользователя `admin` и пароль, затем откройте адрес и войдите. Информация для входа предоставляется только владельцу данного Application и администраторам платформы. Модели, навыки и каналы настраиваются в нативном интерфейсе Hermes. + +## Часто задаваемые вопросы + +- **Почему новый экземпляр ещё не может отвечать?** Завершение развертывания означает, что контейнер готов; перед началом использования необходимо настроить модель и учётные данные в нативном интерфейсе. +- **Предустановлены ли дополнительные плагины или fallback моделей?** По умолчанию ничего не добавляется, настройте по необходимости в нативном интерфейсе. +- **Как обновить существующий экземпляр?** Исходные Application и заказ сохраняются, при повторном развертывании используется текущая версия сервиса; перед обновлением сначала создайте резервную копию данных и проверьте совместимость версий. +- **Что делать при ошибке запуска?** Сначала проверьте журналы и события развертывания, затем настройте модель после подтверждения готовности экземпляра. Не раскрывайте пароль экземпляра и ключи в публичных комментариях или снимках экрана. diff --git a/ru/guides/platform/wework_bot.mdx b/ru/guides/platform/wework_bot.mdx deleted file mode 100644 index 10a6e65a5..000000000 --- a/ru/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/sr/guides/aichat/aichat2_conversations.mdx index 3a4c8583e..aa0005a17 100644 --- a/sr/guides/aichat/aichat2_conversations.mdx +++ b/sr/guides/aichat/aichat2_conversations.mdx @@ -3,18 +3,18 @@ title: "Uputstvo za integraciju AI Chat v2 API-ja" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API (`/aichat2/conversations`) je nova generacija interfejsa za razgovor i potpuno unapređena verzija [AI Chat API-ja](https://platform.acedata.cloud/documents/aichat-conversations). Na osnovu jednostavnosti i upravljanih višekružnih razgovora v1, proširen je sledećim mogućnostima: +AI Chat v2 API (`/aichat2/conversations`) je nova generacija interfejsa za razgovor i predstavlja sveobuhvatno unapređenu verziju [AI Chat API-ja](https://platform.acedata.cloud/documents/aichat-conversations). Na osnovu jednostavnosti v1 i hostovanih višekružnih razgovora, proširuje: -- **Multimodalni korisnički unos**: Direktno šaljite tekst + slike + blokove datoteka putem strukturisanog polja `message`, bez potrebe da ih prethodno indirektno prilažete pomoću `references`. -- **Agentizovano pozivanje alata**: Ugrađen je skup alata za internet pretragu, preuzimanje web stranica, čitanje datoteka i drugo, a mogu se priključiti i MCP serveri koje je korisnik ovlastio (Google Drive, Notion, Slack, GitHub itd.); model može autonomno pozivati alate u više krugova unutar jednog zahteva kako bi završio složene zadatke. -- **Strukturisani striming događaji**: Putem `accept: text/event-stream` ili `application/x-ndjson` možete dobiti događaje kao što su `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` itd. token po token, što olakšava odvojeno renderovanje prema odgovarajućem tipu na frontendu. -- **Mogućnost prekida / nastavka**: Kada modelu budu potrebne dodatne informacije od korisnika, emitovaće događaj `ask_user_question` i pauzirati; pri sledećem pozivu dovoljno je popuniti odgovor putem `tool_results` da bi se nastavilo. -- **Nove CRUD radnje**: Na istom endpoint-u, putem polja `action`, moguće je izvršiti `retrieve` / `retrieve_batch` / `update` / `delete`, bez potrebe za dodatnim API-jem za upravljanje razgovorima. -- **Kontinuirano ažurirana lista modela**: Podrazumevano uključuje savremene modele kao što su GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 i drugi. +- **Multimodalni korisnički unos**: direktno šaljite tekst + slike + blokove fajlova putem strukturiranog polja `message`, bez potrebe da ih prethodno indirektno prilažete pomoću `references`. +- **Pozivanje alata u Agent režimu**: ugrađen je skup alata za pretragu interneta, preuzimanje veb stranica, čitanje fajlova itd., a mogu se priključiti i MCP serveri za koje je korisnik dao ovlašćenje (Google Drive, Notion, Slack, GitHub itd.); model može autonomno pozivati alate više puta unutar jednog zahteva kako bi završio složene zadatke. +- **Strukturirani strimovani događaji**: putem `accept: text/event-stream` ili `application/x-ndjson` mogu se dobiti događaji kao što su `text_delta` po tokenu, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` itd., što olakšava njihovo zasebno prikazivanje prema odgovarajućem tipu na frontendu. +- **Mogućnost prekida / nastavka**: kada model treba da korisnik dopuni informacije, emitovaće događaj `ask_user_question` i pauzirati; pri sledećem pozivu, dovoljno je popuniti odgovor kroz `tool_results` da bi se nastavilo. +- **Nove CRUD radnje**: na istom endpoint-u, putem polja `action`, mogu se izvršiti `retrieve` / `retrieve_batch` / `update` / `delete`, bez potrebe za dodatnim API-jem za upravljanje razgovorima. +- **Lista modela koja se kontinuirano ažurira**: podrazumevano uključuje savremene modele kao što su GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 itd. -Istovremeno je na nivou tela zahteva **u potpunosti unazad kompatibilan sa v1**: dovoljno je poslati `model` + `question` (+ opciono `stateful` / `id` / `references` / `preset`) da biste dobili JSON odgovor `{answer, id}` ekvivalentan v1, tako da pri migraciji sa `/aichat/conversations` nije potrebno prepisivati klijenta — potrebno je samo promeniti putanju u `/aichat2/conversations`. +Istovremeno je na nivou tela zahteva **u potpunosti unazad kompatibilan sa v1**: dovoljno je poslati `model` + `question` (+ opciono `stateful` / `id` / `references` / `preset`) da biste dobili JSON odgovor `{answer, id}` ekvivalentan v1, tako da pri migraciji sa `/aichat/conversations` nije potrebno prepisivati klijent; potrebno je samo promeniti putanju u `/aichat2/conversations`. -> Ako trenutno koristite `/aichat/conversations`, stari interfejs će i dalje ostati dostupan, pa možete migrirati sopstvenim tempom. +> Ako trenutno koristite `/aichat/conversations`, stari interfejs će i dalje ostati dostupan, pa možete migrirati svojim tempom. ## Proces prijave @@ -22,15 +22,15 @@ Da biste koristili AI Chat v2 API, prvo preuzmite svoj API Token u [Ace Data Clo ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Ako još niste prijavljeni ili registrovani, automatski ćete biti preusmereni na stranicu za prijavu, gde ćete biti pozvani da se registrujete i prijavite; nakon završetka automatski ćete se vratiti na trenutnu stranicu. +Ako još niste prijavljeni ili registrovani, automatski ćete biti 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 pozivati sve usluge platforme, bez potrebe da se posebno prijavljujete za svaku uslugu.** Pri prvoj prijavi dobijate besplatan kredit za besplatno isprobavanje; kada kredit nije dovoljan, možete dopuniti opšti saldo u [konzoli](https://platform.acedata.cloud/console/coin). +**Jedan API Token može pozivati sve usluge platforme; nije potrebno posebno se prijavljivati za svaku uslugu.** Pri prvoj prijavi dobićete besplatni kredit za besplatno isprobavanje; kada kredit nije dovoljan, možete dopuniti opšti saldo u [konzoli](https://platform.acedata.cloud/console/coin). > 📘 Kompletna dokumentacija: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Osnovna upotreba -Najjednostavniji način korišćenja je potpuno isti kao u v1: pošaljite `model` + `question`, i dobićete `{answer, id}`. +Najjednostavnija upotreba je potpuno ista kao u v1: pošaljite `model` + `question` i dobijte `{answer, id}`. CURL primer: @@ -76,7 +76,7 @@ response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -Dostupne vrednosti za `model` možete direktno videti u padajućem meniju Try panela sa desne strane, a uobičajene kategorije uključuju: +Dostupne vrednosti za `model` možete direktno videti u padajućem meniju Try panela sa desne strane, a često korišćene kategorije uključuju: - OpenAI: `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.2-pro`, `gpt-5.1-all`, `gpt-5-all`, `gpt-4.1`, `gpt-4o`, `gpt-4o-image`, `o3`, `o4-mini` itd. - Anthropic: `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5-20251101`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001` itd. @@ -90,7 +90,7 @@ Za konkretna pravila naplate pogledajte karticu Pricing na stranici usluge. ## Višekružni razgovor -Kao i u v1, pošaljite `stateful: true` da biste uključili čuvanje razgovora; API će vratiti `id`; u narednim zahtevima dovoljno je vratiti `id` da biste nastavili razgovor, bez potrebe da sami održavate istoriju messages. +Kao i u v1, pošaljite `stateful: true` da omogućite čuvanje razgovora; API će vratiti `id`; u narednim zahtevima dovoljno je vratiti `id` da biste nastavili razgovor, bez potrebe da sami održavate istoriju messages. Prvi zahtev: @@ -106,7 +106,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Povratna vrednost: +Povratak: ```json { @@ -115,7 +115,7 @@ Povratna vrednost: } ``` -Drugi zahtev, uz isti `id`: +Drugi zahtev, sa istim `id`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -136,17 +136,17 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> Podrazumevana vrednost za `stateful` je `true`; izostavljanje je ekvivalentno eksplicitnom prosleđivanju `true`. Ako ne želite da server sačuva ovaj krug razgovora, možete eksplicitno postaviti `stateful: false`. +> Podrazumevana vrednost za `stateful` je `true`, izostavljanje i eksplicitno prosleđivanje `true` su ekvivalentni. Ako ne želite da server sačuva ovaj krug razgovora, možete eksplicitno postaviti `stateful: false`. -## Strimovani odgovor +## Striming odgovor -v2 podržava dva formata strimovanja, koji se biraju prema `accept` zaglavlju: +v2 podržava dva formata striminga, koji se biraju prema zaglavlju `accept`: -| Scenario | `accept` | Oblik podataka | +| Scenario | `accept` | Oblik podataka | | --------------------- | ---------------------- | ------------------------------------------ | | Web frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, poslednji red je `data: [DONE]\n\n` | -| Serverska strana / CLI / Node parsiranje strima | `application/x-ndjson` | Jedan JSON objekat po redu | -| Strimovanje nije potrebno | `application/json`（podrazumevano） | Jednokratno vraća `{answer, id}` | +| Server / CLI / Node analiza striminga | `application/x-ndjson` | Jedan JSON objekat po redu | +| Striming nije potreban | `application/json`（podrazumevano） | Jednokratno vraća `{answer, id}` | ### NDJSON primer @@ -195,7 +195,7 @@ Svaki red NDJSON-a je strukturisani događaj, a najčešći je `text_delta`: ### SSE primer -Upotreba `EventSource` u pregledaču ne podržava prilagođeno telo zahteva; preporučuje se korišćenje `fetch` + ručno parsiranje po isečcima `\n\n`: +Korišćenje `EventSource` u pregledaču ne podržava prilagođeno telo zahteva, preporučuje se korišćenje `fetch` + ručna analiza po isečcima `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -232,28 +232,28 @@ while (true) { } ``` -### Tipovi strimovanih događaja +### Tipovi striming događaja | `type` | Značenje | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Inkrementalni tekstualni segment odgovora asistenta. `content` je novi sadržaj; radi kompatibilnosti sa v1, isti događaj takođe nosi `delta_answer` (jednak `content`) i `id`. | +| `text_delta` | Inkrementalni tekstualni segment odgovora asistenta. `content` je novi sadržaj; radi kompatibilnosti sa v1, isti događaj nosi i `delta_answer` (jednako `content`) i `id`. | | `thinking` | Proces razmišljanja modela (pojavljuje se samo kada izabrani model izlaže reasoning). | -| `tool_use` | Model odlučuje da pozove alat; događaj nosi `tool_id`, `tool_name`, `input`. | -| `tool_result` | Rezultat izvršavanja alata, uparen sa prethodnim `tool_use` preko `tool_id`; `is_error` označava da li je došlo do neuspeha. | -| `card` | Strukturisana kartica koju proizvodi alat (kao što su slike, pregledi linkova), pogodna za direktno renderovanje. | -| `citation` | URL izvora koji se koristi za dopunu citata odgovarajućeg tekstualnog segmenta. | -| `ask_user_question` | Šalje se kada modelu trebaju dodatne informacije od korisnika; razgovor prelazi u stanje `awaiting_user_input`, detalje pogledajte u nastavku [nastavljanje pauziranog razgovora](#恢复暂停的对话). | -| `artifact` | Nezavisan proizvod koji generiše model (kao što su blokovi koda, dokumenti), koji se može sačuvati ili preuzeti. | +| `tool_use` | Model odlučuje da pozove alat, događaj nosi `tool_id`, `tool_name`, `input`. | +| `tool_result` | Rezultat izvršavanja alata, uparen sa prethodnim `tool_use` putem `tool_id`, `is_error` označava da li je neuspešan. | +| `card` | Strukturisana kartica koju alat generiše (kao što su slike, pregledi linkova), pogodna za direktno renderovanje. | +| `citation` | URL izvora koji se koristi za dopunjavanje citata odgovarajućeg tekstualnog segmenta. | +| `ask_user_question` | Šalje se kada modelu treba da korisnik dopuni informacije, razgovor ulazi u stanje `awaiting_user_input`; detalje pogledajte u nastavku [nastavljanje pauziranog razgovora](#nastavljanje-pauziranog-razgovora). | +| `artifact` | Nezavisan artefakt koji model generiše (kao što su blokovi koda, dokumenti), koji se može sačuvati ili preuzeti. | | `system_message` | Informacija sistemske poruke (nije sadržaj korisnika ni asistenta), koristi se samo za UI obaveštenja. | -| `compact` | Događaj pri kojem je interni kontekst sažet, nije potrebna posebna obrada. | -| `error` | U ovom krugu se pojavila greška; `message` opisuje sadržaj greške. | -| `done` | Strimovani odgovor je završen; nosi `usage` (uključujući `prompt_tokens` / `completion_tokens` / `total_tokens`) i `terminal_reason`. | +| `compact` | Događaj u kojem je interni kontekst sažet, nije potrebna posebna obrada. | +| `error` | Došlo je do greške u ovom krugu, `message` opisuje sadržaj greške. | +| `done` | Striming odgovor je završen, nosi `usage` (uključujući `prompt_tokens` / `completion_tokens` / `total_tokens`) i `terminal_reason`. | -Za klijente kojima je važan samo konačni odgovor, spajanje `content` svih `text_delta` događaja ekvivalentno je vrednosti `answer` u režimu `application/json`. +Za klijente kojima je stalo samo do konačnog odgovora, spajanje `content` iz svih `text_delta` događaja ekvivalentno je vrednosti `answer` u režimu `application/json`. ## Multimodalni unos -Ako korisnički unos sadrži sliku ili datoteku, prosledite `message` (niz) umesto `question`. Svaki element niza je blok sadržaja: +Ako korisnički unos sadrži slike ili datoteke, prosledite `message` (niz) umesto `question`. Svaki element niza je blok sadržaja: ```json { @@ -268,30 +268,30 @@ Ako korisnički unos sadrži sliku ili datoteku, prosledite `message` (niz) umes Podržani tipovi blokova: -- `text` — običan tekst, obavezno polje `text`. -- `image_url` — slika, obavezno `image_url.url`. -- `file_url` — datoteka (PDF, CSV, TXT itd.), obavezno `file_url.url`. +- `text` — običan tekst, polje `text` je obavezno. +- `image_url` — slika, `image_url.url` je obavezno. +- `file_url` — datoteka (PDF, CSV, TXT itd.), `file_url.url` je obavezno. ### Odnos sa v1 `references` Radi kompatibilnosti sa starim klijentima, v2 i dalje prepoznaje polje `references: ["https://...", ...]`: -- URL sufiks je `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatski se pretvara u blok `image_url`; -- Ostale ekstenzije se pretvaraju u blok `file_url`; -- Ako je istovremeno dostavljen i `question`, onda se on postavlja unapred kao blok `text`. +- URL sufiks je `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, automatski se pretvara u `image_url` blok; +- Ostale ekstenzije se pretvaraju u `file_url` blok; +- Ako je istovremeno naveden i `question`, onda se on postavlja na početak kao `text` blok. -Stoga, ako samo želite da migrirate sa v1 i ne želite da menjate telo zahteva, dovoljno je da promenite putanju u `/aichat2/conversations`, a originalni način korišćenja `references` nastavlja da radi kao i obično. +Stoga, ako samo želite da migrirate sa v1 i ne želite da menjate telo zahteva, dovoljno je da putanju zamenite sa `/aichat2/conversations`, a originalna upotreba `references` nastavlja da radi kao i obično. -Ako je potrebna preciznija kontrola (na primer, postavljanje više slika između teksta ili kada je redosled veoma važan), direktno koristite niz `message`. +Ako vam je potrebna preciznija kontrola (na primer, postavljanje više slika između teksta ili kada je redosled veoma važan), direktno koristite niz `message`. ## Pozivanje alata i MCP -Ključno unapređenje v2 je to što model može samostalno pozivati alate kako bi završio zadatke u više koraka, **ovo je podrazumevano uključeno**, bez potrebe da klijent vrši bilo kakvu dodatnu konfiguraciju u zahtevu. Uobičajeni scenariji: +Ključno unapređenje v2 je to što model može samostalno da poziva alate za izvršavanje zadataka u više koraka, **ovo je podrazumevano uključeno**, i ne zahteva nikakvu dodatnu konfiguraciju od klijenta u zahtevu. Uobičajeni scenariji: -- Korisnik pita „Pomozi mi da pretražim koje nove izložbe nedavno ima u Šangaju“ → model poziva ugrađeni web search → organizuje rezultate u odgovor. +- Korisnik pita „Pomozi mi da potražim koje su nove izložbe nedavno u Šangaju“ → model poziva ugrađeni web search → organizuje rezultate u odgovor. - Korisnik pita „Pročitaj ovaj PDF, a zatim napiši sažetak“ → model poziva file_read → piše sažetak. -- Korisnik je već autorizovao Google Drive / GitHub / Notion itd. u [Connections](https://platform.acedata.cloud/connections) → model može pozivati odgovarajuće MCP alate za čitanje i pisanje njihovih podataka. +- Korisnik je već autorizovao Google Drive / GitHub / Notion itd. u [Connections](https://platform.acedata.cloud/connections) → model može da poziva odgovarajuće MCP alate za čitanje i pisanje njihovih podataka. -U NDJSON / SSE toku, pozivi alata se prikazuju kroz dve vrste događaja, `tool_use` i `tool_result`, na primer: +U NDJSON / SSE toku, pozivi alata se prikazuju putem dve vrste događaja, `tool_use` i `tool_result`, na primer: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,9 +301,9 @@ U NDJSON / SSE toku, pozivi alata se prikazuju kroz dve vrste događaja, `tool_u ... ``` -Ako ne želite da prikazujete detalje pozivanja alata na frontendu, dovoljno je da ignorišete događaje `tool_use` / `tool_result` / `card` / `citation`; konačni izlaz modela se i dalje šalje kroz `text_delta`. +Ako ne želite da prikazujete detalje pozivanja alata na frontendu, dovoljno je da ignorišete događaje `tool_use` / `tool_result` / `card` / `citation`; konačni izlaz modela i dalje teče kroz `text_delta`. -`max_turns` može ograničiti koliko najviše krugova model može sam da poziva alate u ovom zahtevu, a podrazumevanu gornju granicu određuje platforma. Postavljanjem na manju vrednost (na primer `max_turns: 1`) može se prisiliti jednokratni odgovor, bez dozvole za bilo kakvo pozivanje alata. +`max_turns` može da ograniči maksimalan broj krugova u kojima model može sam da poziva alate u ovom zahtevu, opseg je 1–500, a podrazumevana vrednost kada se izostavi je 500. Ako ga postavite na manju vrednost (na primer `max_turns: 1`), možete prinuditi jednokratan odgovor i ne dozvoliti nikakve pozive alata. ## Asinhrono izvršavanje i autorizacija bez nadzora @@ -328,9 +328,9 @@ Primer odgovora: } ``` -Nakon toga možete koristiti `action: retrieve` + `id` za upit rezultata razgovora; možete takođe dostaviti `callback_url`, a platforma će nakon završetka zadatka poslati `{ status, answer, usage, error }` putem POST zahteva na vašu adresu za povratni poziv. `callback_url` mora koristiti `http` / `https` i ne može direktno navoditi `localhost` ili literalnu adresu privatnog IP-a. +Nakon toga možete koristiti `action: retrieve` + `id` za upit rezultata razgovora; možete navesti i `callback_url`, a platforma će po završetku zadatka POST metodom poslati `{ status, answer, usage, error }` na vašu adresu povratnog poziva. `callback_url` mora koristiti `http` / `https` i ne može direktno navesti `localhost` ili literalnu adresu privatnog IP-a. -Za pozadinske zadatke obično nema nikoga ko može da klikne na potvrdu. Ako želite da određeni Skill ili MCP Server izvrši radnje kao što su slanje, objavljivanje, pisanje i slično u režimu bez nadzora, eksplicitno prosledite listu prethodnih ovlašćenja u telu zahteva: +Za pozadinske zadatke obično nema nikoga ko može da klikne potvrdu. Ako želite da određeni Skill ili MCP Server izvršava radnje poput slanja, objavljivanja i upisivanja u režimu bez nadzora, eksplicitno prosledite listu prethodnog odobrenja u telu zahteva: ```json { @@ -342,9 +342,9 @@ Za pozadinske zadatke obično nema nikoga ko može da klikne na potvrdu. Ako že } ``` -Vrednosti u `allowed_skills` su slug-ovi povezanih Skill-ova; vrednosti u `allowed_mcp_servers` su slug-ovi povezanih MCP Server-a. Skill / MCP Server koji nije naveden u prethodnom ovlašćenju u režimu bez nadzora i dalje može samo da pregleda, izvrši dry-run ili odbije izvršavanje operacija pisanja. +Vrednosti u `allowed_skills` su slug-ovi povezanih Skill-ova; vrednosti u `allowed_mcp_servers` su slug-ovi povezanih MCP Servera. Skill / MCP Server koji nije naveden u prethodnom odobrenju u režimu bez nadzora i dalje može samo da pregleda, izvrši dry-run ili odbije izvršavanje operacija pisanja. -Ako je potrebna detaljnija kontrola, može se koristiti i ekvivalentni objekat `unattended_policy`: +Ako je potrebna detaljnija kontrola, možete koristiti i ekvivalentni objekat `unattended_policy`: ```json { @@ -356,13 +356,13 @@ Ako je potrebna detaljnija kontrola, može se koristiti i ekvivalentni objekat ` } ``` -Prethodno ovlašćenje su upravo ove dve liste: prazna lista znači da nije ovlašćena nijedna mogućnost, bez potrebe za dodatnim poljem prekidača. +Prethodno odobrenje su same ove dve liste: prazne liste ne odobravaju nijednu mogućnost i nije potrebno dodatno polje prekidača. -Napomena: prethodno ovlašćenje samo znači „ovaj zahtev dozvoljava da ove mogućnosti preskoče ljudsku potvrdu u režimu bez nadzora“. Konkretan Skill i dalje mora podržavati `--unattended-confirm` ili odgovarajući bezbednosni mehanizam; u suprotnom će nastaviti sa dry-run i neće direktno izvršiti operaciju pisanja. +Napomena: prethodno odobrenje samo znači „ovaj zahtev dozvoljava ovim mogućnostima da preskoče ljudsku potvrdu u režimu bez nadzora“. Konkretni Skill i dalje mora podržavati `--unattended-confirm` ili odgovarajući bezbednosni mehanizam; u suprotnom će nastaviti sa dry-run režimom i neće direktno izvršiti operacije pisanja. ## Nastavljanje pauziranog razgovora -Neki alati mogu navesti model da „postavi protivpitanje korisniku“, pri čemu model šalje događaj `ask_user_question`, a razgovor se zamrzava u stanju `awaiting_user_input`: +Neki alati mogu navesti model da „postavi protivpitanje korisniku“, pri čemu model emituje događaj `ask_user_question`, a razgovor se zamrzava u stanju `awaiting_user_input`: ```json { @@ -375,7 +375,7 @@ Neki alati mogu navesti model da „postavi protivpitanje korisniku“, pri čem } ``` -Na frontendu prikažite ovaj događaj kao karticu kako bi korisnik izabrao odgovor, a zatim pokrenite sledeći zahtev sa istim `id`, popunjavajući odgovor kroz `tool_results`: +Na frontendu prikažite ovaj događaj kao karticu kako bi korisnik izabrao odgovor, a zatim pokrenite sledeći zahtev sa istim `id`, popunjavajući odgovor putem `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -`tool_use_id` u telu zahteva **mora** biti potpuno isti kao `tool_id` u trenutku pauziranja; u suprotnom će biti vraćen 400. Kada `tool_results` istovremeno postoji u zahtevu, `question` / `message` / `references` će svi biti ignorisani. +`tool_use_id` u telu zahteva **mora** u potpunosti odgovarati `tool_id` u trenutku pauziranja; nepodudaranje vraća 400. Kada u zahtevu istovremeno postoji `tool_results`, `question` / `message` / `references` će svi biti ignorisani. Ako korisnik odluči da odustane od ovog pitanja, dovoljno je direktno proslediti novi `question` / `message`, a platforma će automatski označiti pauzirani poziv alata kao „korisnik je preskočio“. ## Upravljanje razgovorima (CRUD) -v2 pruža lagano upravljanje razgovorima kroz polje `action` na istom endpoint-u, bez potrebe za dodatnim API-jem. +v2 pruža lagano upravljanje razgovorima putem polja `action` na istom endpoint-u, bez potrebe za dodatnim API-jem. +### `action: retrieve` —— preuzimanje jedne konverzacije -### `action: retrieve` —— Preuzimanje razgovora ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -428,7 +428,7 @@ Vraća kompletan dokument konverzacije (uključujući istoriju `messages`, `mode } ``` -Vraća `{ items: [...], total }`. **Sažeci ne sadrže `messages`**, pogodni su za listu u bočnoj traci; ako korisnik otvori određenu konverzaciju, zatim koristite `action: retrieve` da zasebno preuzmete njene kompletne poruke. +Vraća `{ items: [...], total }`. **Sažeci ne sadrže `messages`**, pogodni su za listu na bočnoj traci; ako korisnik otvori određenu konverzaciju, zatim upotrebite `action: retrieve` da zasebno preuzmete njene kompletne poruke. Opcioni parametri filtriranja: `user_id`, `application_id`, `model_group`, `model`. @@ -442,7 +442,7 @@ Opcioni parametri filtriranja: `user_id`, `application_id`, `model_group`, `mode } ``` -Može se proslediti i `messages`, ali server će izvršiti strogu schema validaciju (mora biti u sažetom obliku `ToolUseContent`), a ako ne odgovara, vratiće 400. Generalno se preporučuje da se koristi samo za promenu `title`. +`messages` se takođe može proslediti, ali će server vršiti strogu schema validaciju (mora biti u sažetom obliku `ToolUseContent`), a u slučaju neusaglašenosti vratiće 400. Generalno se preporučuje da se koristi samo za promenu `title`. ### `action: delete` —— brisanje jedne konverzacije @@ -453,21 +453,21 @@ Može se proslediti i `messages`, ali server će izvršiti strogu schema validac } ``` -Vraća `{ id, success: true }`. Nakon brisanja nije moguće vraćanje, potvrdite pre pozivanja. +Vraća `{ id, success: true }`. Nakon brisanja nije moguće vraćanje, potvrdite pre poziva. ## Glatka migracija sa v1 Ako već koristite [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), migracija na v2 gotovo da ne zahteva izmene koda: 1. Promenite URL sa `https://api.acedata.cloud/aichat/conversations` na `https://api.acedata.cloud/aichat2/conversations`. -2. Ako ste ranije prosleđivali nazive v1 modela (kao što su `gpt-3.5`, `gpt-4-browsing` itd.), pri prelasku na v2 preporučuje se nadogradnja na savremene modele (kao što su `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` itd.). -3. Polja NDJSON toka ostaju kompatibilna unazad: svaki događaj `text_delta` i dalje sadrži `delta_answer` i `id`, tako da klijent koji je prethodno parsirao `delta_answer` red po red ne zahteva izmene. +2. Ako ste prethodno prosleđivali v1 nazive modela (kao što su `gpt-3.5`, `gpt-4-browsing` itd.), preporučuje se da pri prelasku na v2 nadogradite na savremene modele (kao što su `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` itd.). +3. Polja NDJSON toka ostaju kompatibilna unazad: svaki `text_delta` događaj i dalje sadrži `delta_answer` i `id`, stoga klijenti koji su prvobitno parsirali `delta_answer` red po red ne zahtevaju izmene. Nakon migracije možete po potrebi omogućiti nove mogućnosti v2 (multimodalni `message`, SSE, pozivanje alata, `action` CRUD) i napredovati sopstvenim tempom. ## Obrada grešaka -Odgovori na greške su ujednačeni kao: +Odgovori na greške imaju jedinstveni format: ```json { @@ -479,16 +479,16 @@ Odgovori na greške su ujednačeni kao: } ``` -Česte greške: +Uobičajene greške: -- `400 bad_request`: nedostaju obavezna polja, `tool_use_id` se ne podudara, `messages` schema je neispravna itd. +- `400 bad_request`: nedostaju obavezna polja, `tool_use_id` se ne podudara, schema za `messages` je neispravna itd. - `401 invalid_token`: zaglavlje `authorization` nije ispravno. - `404 not_found`: konverzacija koja odgovara `id` ne postoji pri `action: retrieve / update / delete`. - `429 too_many_requests`: aktivirano je ograničenje brzine zahteva. -- `500 chat_error`: greška uzvodnog LLM-a ili `completion_tokens=0` u ovoj rundi (obrađuje se kao nepotrošeno, naplata se ne vrši). +- `500 chat_error`: uzvodni LLM je prijavio grešku ili je u ovoj rundi `completion_tokens=0` (tretira se kao nepotrošeno i neće biti naplaćeno). -U striming odgovoru, greška se šalje kao događaj `{"type":"error","message":"..."}`, nakon čega se tok odmah završava. +U strimovanom odgovoru, greška se šalje kao događaj `{"type":"error","message":"..."}`, nakon čega se tok odmah završava. ## Zaključak -AI Chat v2 API, uz zadržavanje kompatibilnosti unazad sa v1, nadograđuje konverzacije sa „jednokratnih / višekratnih pitanja i odgovora” na „Agentizovane, opservabilne konverzacije”: multimodalni unos, pozivanje alata, mogućnost pauziranja / nastavljanja, striming strukturiranih događaja, ugrađeni CRUD. Preporučuje se da nove integracije direktno koriste v2; postojeće v1 integracije mogu se glatko migrirati u fazama. Ako imate bilo kakvih pitanja, slobodno kontaktirajte naš tim tehničke podrške. +AI Chat v2 API, uz zadržavanje kompatibilnosti unazad sa v1, unapređuje razgovore od „jednokratnih / višekratnih pitanja i odgovora“ do „Agentizovanih, posmatranih konverzacija“: multimodalni unos, pozivanje alata, mogućnost pauziranja / nastavljanja, strimovani strukturirani događaji, ugrađeni CRUD. Preporučuje se da nove integracije direktno koriste v2; postojeće v1 integracije mogu glatko migrirati u fazama. Ako imate bilo kakvih pitanja, slobodno kontaktirajte naš tim tehničke podrške. diff --git a/sr/guides/platform/hermes_managed.mdx b/sr/guides/platform/hermes_managed.mdx index 450125e59..ff664276c 100644 --- a/sr/guides/platform/hermes_managed.mdx +++ b/sr/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Privatna Implementacija" +title: "Hermes implementacija" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud pruža ulaz za privatnu implementaciju Hermes Agenta. Ovaj ulaz je kontrolisana usluga, a dostupnost i opcioni resursi su u skladu sa trenutnim prikazom na konzoli. +Kreirajte nezavisnu instancu Hermes kontejnera za svaku Application. Podrazumevano se koristi osnovna slika sa fiksnom izdanom verzijom, uz zadržavanje izvornih funkcija; platforma pruža kupovinu, obnovu, trajno skladištenje i upravljanje implementacijom. -## Koraci za korišćenje +## Kreiranje i kupovina -1. Na platformi pronađite **Hermes Agent Privatna Implementacija**. -2. Pratite uputstva na stranici da izaberete dostupne konfiguracije i kreirate uslugu. -3. Sačekajte da platforma prikaže status spremnosti. -4. Koristite ulaz i akreditive koje pruža stranica za pristup instanci. -5. Prvo pošaljite `Reply only OK`, a zatim započnite pravi zadatak. +1. Otvorite [Hermes implementaciju](https://platform.acedata.cloud/services/hermes) i kreirajte Application. +2. Na stranici za kupovinu izaberite paket trajanja i završite plaćanje. +3. Vratite se na stranicu konfiguracije, gde možete iz padajuće liste izabrati model za ćaskanje platforme i pregledati trenutnu cenu modela. Platforma će za ovu instancu kreirati nezavisne API akreditive; takođe možete isključiti pristup preko platforme i sami izvršiti konfiguraciju u izvornom kontrolnom panelu. +4. Izaberite automatsko generisanje pristupnih akreditiva ili postavite sopstvenu jaku lozinku/Token, a nakon potvrde implementacija počinje. Pristupni akreditivi i API akreditivi modela su međusobno nezavisni. +5. Kada instanca bude spremna, preuzmite adresu za pristup i akreditive za prijavu sa stranice za upravljanje. +6. Prijavite se u izvorni kontrolni panel i konfigurišite sopstvenog pružaoca modela, ključeve i kanale. -Modeli, akreditivi, skladištenje i ponašanje brisanja su u skladu sa stranicom za kreiranje i potvrdom dijaloga; ne tretirajte YAML iz lokalnog Hermes vodiča kao ugovor za implementaciju na platformi. Pre brisanja prvo izvezite podatke koje želite da sačuvate. +Naknada za implementaciju obračunava se prema trajanju paketa, a konkretne cene u američkim dolarima i trajanja zavise od stranice za kupovinu. Troškovi pozivanja modela obračunavaju se posebno; kupovina trajanja implementacije ne daje kredit za model. Kada je pristup preko platforme omogućen, namenski API akreditivi otvaraju samo interfejs za ćaskanje koji odgovara izabranom modelu, a pozivi se dodatno naplaćuju iz vašeg salda na platformi. Svaka Application se zasebno kupuje, obnavlja i upravlja. -Ako konzola ne prikazuje ulaz za kreiranje, to znači da trenutni nalog još uvek nema pristup ovoj usluzi, možete koristiti [Hermes interaktivnog vodiča](https://platform.acedata.cloud/documents/hermes-wizard-integration) ili [ručno konfiguraciju](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Lozinke, akreditivi i naknadna konfiguracija + +Pristupni akreditivi se postavljaju pre prvog pokretanja. Automatski generisana metoda koristi nasumične akreditive, prilagođena lozinka ima najmanje 16 znakova, a OpenClaw Token najmanje 32 znaka. Nacrt ne čuva lozinku; nakon promene stranice možda ćete morati ponovo da je unesete. Nakon implementacije, samo vlasnik i administratori Application mogu da vide pristupne akreditive. + +API akreditivi modela za svaku instancu se ne koriste zajednički, važenje im se produžava sa obnovom implementacije i opozivaju se kada se instanca izbriše. Nakon inicijalizacije implementacije, izmenite modele i kanale u izvornom kontrolnom panelu; ako pređete na model druge usluge, prvo prilagodite ovlašćenje za odgovarajući interfejs u upravljanju akreditivima platforme ili koristite odgovarajuće akreditive. Obična ponovna implementacija neće prepisati izvorna podešavanja. Okruženja za implementaciju koja nisu prošla verifikaciju objavljivanja privremeno će odbijati nove implementacije, obratite se podršci. + +## Verzije i podaci + +Stranica konfiguracije prikazuje trenutno objavljenu verziju slike. Nove instance koriste trenutno objavljenu verziju usluge; postojeće instance neće biti automatski zamenjene ažuriranjima kataloga. Ponovna implementacija će primeniti trenutnu verziju usluge, zato prvo napravite rezervnu kopiju i potvrdite zahteve za nadogradnju korišćene verzije. + +Svaka instanca podrazumevano pruža 1 CPU, ograničenje memorije od 2 GiB i 10 GiB trajnog skladišta. Ponovno pokretanje zadržava podatke instance. Aktivno brisanje implementacije ili povlačenje po isteku će izbrisati skladište, zato unapred izvezite podatke koje treba sačuvati. + +## Obnova i istek + +Obnovite na stranici za kupovinu trenutne Application, a period važenja se produžava prema postojećim pravilima trajanja platforme. Nakon isteka, pristupni ulaz se pauzira, a obnova tokom perioda odgode vraća pristup; nakon perioda odgode instanca i podaci će biti povučeni. Merodavni su vreme isteka, status naplate i obaveštenja o brisanju na stranici za upravljanje. + +## Prijava u upravljački interfejs + +Na stranici za upravljanje implementacijom kopirajte Dashboard adresu, korisničko ime `admin` i lozinku, a zatim otvorite i prijavite se. Informacije za prijavu dostupne su samo vlasniku te Application i administratorima platforme. Modeli, veštine i kanali se konfigurišu u izvornom Hermes interfejsu. + +## Često postavljana pitanja + +- **Zašto nova instanca još ne može da odgovara?** Završena implementacija znači da je kontejner spreman; potrebno je konfigurisati model i akreditive u izvornom interfejsu pre početka korišćenja. +- **Da li su unapred instalirani dodatni dodaci ili fallback modela?** Podrazumevano se ne dodaju, konfigurišite ih prema potrebi u izvornom interfejsu. +- **Kako ažurirati postojeću instancu?** Originalna Application i porudžbina se zadržavaju, a pri ponovnoj implementaciji koristi se trenutna verzija usluge; pre nadogradnje prvo napravite rezervnu kopiju podataka i proverite kompatibilnost verzije. +- **Šta učiniti ako pokretanje ne uspe?** Prvo proverite dnevnike implementacije i događaje, a modele konfigurišite tek nakon potvrde da je instanca spremna. Ne otkrivajte lozinke instance i ključeve u javnim komentarima ili snimcima ekrana. diff --git a/sr/guides/platform/wework_bot.mdx b/sr/guides/platform/wework_bot.mdx deleted file mode 100644 index e04ed871b..000000000 --- a/sr/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/sv/guides/aichat/aichat2_conversations.mdx index da180d60f..f32fd4ff6 100644 --- a/sv/guides/aichat/aichat2_conversations.mdx +++ b/sv/guides/aichat/aichat2_conversations.mdx @@ -1,36 +1,36 @@ --- -title: "AI Chat v2 API-integrationsinstruktioner" +title: "AI Chat v2 API-integrationsanvisning" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API (`/aichat2/conversations`) är den nya generationens konversationsgränssnitt och en omfattande uppgraderad version av [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Utifrån v1:s enkla, hanterade flerrundskonversationer har det utökats med: +AI Chat v2 API (`/aichat2/conversations`) är den nya generationens konversationsgränssnitt och en fullständig uppgraderingsversion av [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). Utöver v1:s enkla, hanterade flerrundskonversationer utökar den med: -- **Multimodala användarinmatningar**: Skicka text + bild + filblock direkt via det strukturerade `message`-fältet, utan att först indirekt bifoga dem med `references`. -- **Agentbaserade verktygsanrop**: Inbyggd uppsättning verktyg för internetsökning, webbsideshämtning, filläsning med mera, samt möjlighet att ansluta MCP-servrar som användaren har auktoriserat (Google Drive, Notion, Slack, GitHub med flera). Modellen kan självständigt anropa verktyg flera gånger i en och samma begäran för att slutföra komplexa uppgifter. -- **Strukturerade strömmande händelser**: Via `accept: text/event-stream` eller `application/x-ndjson` kan du få händelser såsom `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card` och `artifact` token för token, vilket underlättar separat rendering i frontend enligt respektive typ. -- **Avbrytbar / återupptagbar**: När modellen behöver att användaren kompletterar information skickar den händelsen `ask_user_question` och pausas. Vid nästa anrop kan du fylla i svaret via `tool_results` för att fortsätta. +- **Multimodala användarinmatningar**: Skicka text + bild- + filblock direkt via det strukturerade fältet `message`, utan att först behöva bifoga dem indirekt med `references`. +- **Agentbaserade verktygsanrop**: Har en inbyggd uppsättning verktyg för webbsökning, hämtning av webbsidor, filläsning med mera, och kan ansluta MCP-servrar som användaren har auktoriserat (Google Drive, Notion, Slack, GitHub etc.). Modellen kan självständigt anropa verktyg i flera omgångar inom en enda begäran för att slutföra komplexa uppgifter. +- **Strukturerade strömmande händelser**: Via `accept: text/event-stream` eller `application/x-ndjson` kan du få händelser som `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` med flera, token för token, vilket underlättar separat rendering av respektive typ i frontend. +- **Kan avbrytas / återupptas**: När modellen behöver att användaren kompletterar information skickar den händelsen `ask_user_question` och pausar. Vid nästa anrop kan du fortsätta genom att fylla i svaret via `tool_results`. - **Nya CRUD-åtgärder**: Utför `retrieve` / `retrieve_batch` / `update` / `delete` via fältet `action` på samma endpoint, utan behov av ytterligare API:er för konversationshantering. -- **Kontinuerligt uppdaterad modellista**: Ansluter som standard till moderna modeller såsom GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4 och Kimi K3. +- **Kontinuerligt uppdaterad modellista**: Har som standard stöd för moderna modeller såsom GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 med flera. -Samtidigt är den på begärandekroppsnivå **helt bakåtkompatibel med v1**: skicka endast `model` + `question` (+ valfria `stateful` / `id` / `references` / `preset`) för att få ett JSON-svar `{answer, id}` som motsvarar v1. Därför behöver klienten inte skrivas om vid migrering från `/aichat/conversations`; byt bara sökvägen till `/aichat2/conversations`. +Samtidigt är den på begäranivå **helt bakåtkompatibel med v1**: skicka endast `model` + `question` (+ valfritt `stateful` / `id` / `references` / `preset`) för att få ett JSON-svar `{answer, id}` som motsvarar v1. Därför behöver du inte skriva om klienten när du migrerar från `/aichat/conversations`; byt bara sökvägen till `/aichat2/conversations`. -> Om du för närvarande använder `/aichat/conversations` kommer det gamla gränssnittet fortfarande att vara i drift, och du kan migrera i din egen takt. +> Om du för närvarande använder `/aichat/conversations` kommer det gamla gränssnittet fortfarande att behållas, och du kan migrera i din egen takt. ## Ansökningsprocess -För att använda AI Chat v2 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 som reserv. +För att använda AI Chat v2 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 framtida bruk. ![](https://cdn.acedata.cloud/dvc3cg.jpg) -Om du ännu inte har loggat in eller registrerat dig omdirigeras du automatiskt till inloggningssidan för att registrera dig och logga in. När detta är klart återvänder 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 du behöver 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 fylla på det allmänna saldot i [konsolen](https://platform.acedata.cloud/console/coin). +**En API-token kan anropa alla tjänster på plattformen; du behöver inte ansöka separat för varje tjänst.** Vid första ansökan får du kostnadsfria krediter för en gratis testperiod; om krediterna inte räcker kan du fylla på det gemensamma saldot i [konsolen](https://platform.acedata.cloud/console/coin). > 📘 Fullständig dokumentation: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Grundläggande användning -Den enklaste användningen är helt identisk med v1: skicka `model` + `question` och få `{answer, id}`. +Den enklaste användningen är exakt densamma som v1: skicka `model` + `question` och få `{answer, id}`. CURL-exempel: @@ -90,7 +90,7 @@ Se Pricing-kortet på tjänstesidan för specifika prisregler. ## Flerrundskonversation -Precis som i v1 skickar du `stateful: true` för att aktivera konversationssparning, och API:t returnerar ett `id`; i efterföljande begäranden räcker det att skicka tillbaka `id` för att fortsätta konversationen, utan att själv behöva underhålla historiken för messages. +Precis som i v1 skickar du `stateful: true` för att aktivera konversationslagring. API:t returnerar ett `id`; inkludera sedan `id` i efterföljande begäranden för att fortsätta konversationen, utan att själv behöva underhålla historiken för messages. Första begäran: @@ -106,7 +106,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Retur: +Svar: ```json { @@ -115,7 +115,7 @@ Retur: } ``` -Andra begäran, med samma `id`: +Andra begäran, inkludera samma `id`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -136,16 +136,16 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful` är som standard `true`; att utelämna det är likvärdigt med att uttryckligen skicka `true`. Om du inte vill att servern ska spara denna samtalsrunda kan du uttryckligen ange `stateful: false`. +> `stateful` är som standard `true`; att utelämna det är likvärdigt med att uttryckligen skicka `true`. Om du inte vill att servern sparar denna samtalsrunda kan du uttryckligen ange `stateful: false`. ## Strömmande svar -v2 stöder två strömmande format, som väljs enligt `accept`-huvudet: +v2 stöder två strömmande format, som väljs utifrån `accept`-huvudet: | Scenario | `accept` | Dataformat | | --------------------- | ---------------------- | ------------------------------------------ | -| Webbfrontend / EventSource | `text/event-stream` | `data: {json}\n\n`, sista raden är `data: [DONE]\n\n` | -| Server / CLI / Node-strömmande analys | `application/x-ndjson` | Ett JSON-objekt per rad | +| Webbsidans frontend / EventSource | `text/event-stream` | `data: {json}\n\n`, sista raden `data: [DONE]\n\n` | +| Serversida / CLI / Node-strömmande tolkning | `application/x-ndjson` | Ett JSON-objekt per rad | | Strömning behövs inte | `application/json`（standard） | Returnerar `{answer, id}` på en gång | ### NDJSON-exempel @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -Varje rad i NDJSON är en strukturerad händelse, där den vanligaste är `text_delta`: +Varje rad i NDJSON är en strukturerad händelse, den vanligaste är `text_delta`: ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +195,7 @@ Varje rad i NDJSON är en strukturerad händelse, där den vanligaste är `text_ ### SSE-exempel -`EventSource` i webbläsaren stöder inte anpassade förfrågningskroppar; det rekommenderas att använda `fetch` + manuell segmentanalys med `\n\n`: +`EventSource` på klientsidan i webbläsaren stöder inte anpassade begärandekroppar; det rekommenderas att använda `fetch` + manuell tolkning genom segmentering vid `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +236,24 @@ while (true) { | `type` | Betydelse | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Inkrementellt textfragment i assistentens svar. `content` är det nya innehållet; för kompatibilitet med v1 innehåller samma händelse även `delta_answer` (lika med `content`) och `id`. | -| `thinking` | Modellens tankeprocess (visas endast när den valda modellen exponerar reasoning). | +| `text_delta` | Inkrementellt textsegment i assistentens svar. `content` är nytt innehåll; för kompatibilitet med v1 innehåller samma händelse även `delta_answer` (lika med `content`) och `id`. | +| `thinking` | Modellens tankeprocess (visas endast när den valda modellen exponerar resonemang). | | `tool_use` | Modellen beslutar att anropa ett verktyg; händelsen innehåller `tool_id`, `tool_name`, `input`. | -| `tool_result` | Resultatet av verktygskörningen, paras ihop med föregående `tool_use` via `tool_id`; `is_error` anger om det misslyckades. | -| `card` | Strukturerade kort som produceras av verktyg (t.ex. bilder, länkförhandsvisningar), lämpliga för direkt rendering. | -| `citation` | Används för att komplettera käll-URL:er för referenser till motsvarande textfragment. | -| `ask_user_question` | Skickas när modellen behöver att användaren kompletterar information; samtalet går in i tillståndet `awaiting_user_input`, se [återuppta pausade samtal](#återuppta-pausade-samtal) nedan. | -| `artifact` | Ett fristående resultat som genererats av modellen (t.ex. kodblock, dokument), som kan sparas eller laddas ned. | -| `system_message` | Systemmeddelande (inte innehåll från användare eller assistent), används endast för UI-promptar. | -| `compact` | En händelse där den interna kontexten har komprimerats; ingen särskild hantering krävs. | -| `error` | Ett fel inträffade i denna omgång; `message` beskriver felinnehållet. | +| `tool_result` | Verktygets körningsresultat, parat med föregående `tool_use` via `tool_id`; `is_error` anger om det misslyckades. | +| `card` | Strukturerade kort som genereras av verktyg (t.ex. bilder, länkförhandsvisningar), lämpliga för direkt rendering. | +| `citation` | Käll-URL:er som används för att komplettera hänvisningar till motsvarande textsegment. | +| `ask_user_question` | Skickas när modellen behöver att användaren kompletterar information; samtalet går in i tillståndet `awaiting_user_input`, se [Återuppta pausade samtal](#återuppta-pausade-samtal) nedan. | +| `artifact` | Ett fristående resultat som genereras av modellen (t.ex. kodblock, dokument), som kan sparas eller laddas ner. | +| `system_message` | Systemmeddelande (inte innehåll från användaren eller assistenten), används endast för UI-notiser. | +| `compact` | Händelse där intern kontext komprimeras, kräver ingen särskild hantering. | +| `error` | Ett fel uppstod under denna omgång, `message` beskriver felinnehållet. | | `done` | Det strömmande svaret avslutas och innehåller `usage` (inklusive `prompt_tokens` / `completion_tokens` / `total_tokens`) och `terminal_reason`. | -För klienter som endast bryr sig om det slutliga svaret är det likvärdigt med `answer` i läget `application/json` att sammanfoga `content` från alla `text_delta`. +För klienter som endast bryr sig om det slutliga svaret är det likvärdigt att sammanfoga `content` för alla `text_delta` med `answer` i läget `application/json`. ## Multimodal inmatning -Om användarens inmatning innehåller bilder eller filer skickar du `message` (en array) i stället för `question`. Varje element i arrayen är ett innehållsblock: +Om användarens inmatning innehåller bilder eller filer ska `message` (en matris) skickas i stället för `question`. Varje matriselement är ett innehållsblock: ```json { @@ -277,21 +277,21 @@ Blocktyper som stöds: För kompatibilitet med äldre klienter känner v2 fortfarande igen fältet `references: ["https://...", ...]`: - URL-suffixet är `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, konverteras automatiskt till ett `image_url`-block; - Andra filändelser konverteras till ett `file_url`-block; -- Om `question` också tillhandahålls, placeras det som ett `text`-block före. +- Om `question` också tillhandahålls, placeras den först som ett `text`-block. -Om du därför bara vill migrera från v1 och inte vill ändra request body, räcker det att byta sökvägen till `/aichat2/conversations`, så fungerar den ursprungliga användningen av `references` som vanligt. +Om du därför bara vill migrera från v1 utan att ändra request body, räcker det att byta sökvägen till `/aichat2/conversations`, så fungerar den ursprungliga användningen av `references` som vanligt. Om du behöver mer detaljerad kontroll (till exempel att placera flera bilder mellan texter, eller om ordningen är viktig) använder du direkt arrayen `message`. ## Verktygsanrop och MCP -Den centrala förbättringen i v2 är att modellen självständigt kan anropa verktyg för att slutföra uppgifter i flera steg, **detta är aktiverat som standard**, och klienten behöver inte göra någon extra konfiguration i begäran. Vanliga scenarier: +Kärnförbättringen i v2 är att modellen självständigt kan anropa verktyg för att slutföra uppgifter i flera steg, **detta är aktiverat som standard**, och kräver ingen extra konfiguration från klienten i begäran. Vanliga scenarier: -- Användaren frågar ”Hjälp mig att söka efter vilka nya utställningar som nyligen finns i Shanghai” → Modellen anropar inbyggd webbsökning → Organiserar resultaten till ett svar. -- Användaren frågar ”Läs den här PDF:en och skriv sedan en sammanfattning” → Modellen anropar file_read → Skriver en sammanfattning. -- Användaren har redan auktoriserat Google Drive / GitHub / Notion osv. i [Connections](https://platform.acedata.cloud/connections) → Modellen kan anropa motsvarande MCP-verktyg för att läsa och skriva deras data. +- Användaren frågar ”hjälp mig att söka efter vilka nya utställningar som finns i Shanghai nyligen” → modellen anropar inbyggd webbsökning → sammanställer resultaten till ett svar. +- Användaren frågar ”läs denna PDF och skriv sedan en sammanfattning” → modellen anropar file_read → skriver en sammanfattning. +- Användaren har auktoriserat Google Drive / GitHub / Notion med flera i [Connections](https://platform.acedata.cloud/connections) → modellen kan anropa motsvarande MCP-verktyg för att läsa och skriva deras data. -I NDJSON / SSE-strömmen visas verktygsanrop genom två typer av händelser, `tool_use` och `tool_result`, till exempel: +I NDJSON- / SSE-strömmar presenteras verktygsanrop genom två typer av händelser, `tool_use` och `tool_result`, till exempel: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,23 +301,23 @@ I NDJSON / SSE-strömmen visas verktygsanrop genom två typer av händelser, `to ... ``` -Om du inte vill visa detaljer om verktygsanrop i frontend räcker det att ignorera dessa typer av händelser: `tool_use` / `tool_result` / `card` / `citation`; modellens slutliga utdata strömmas fortfarande ut via `text_delta`. +Om du inte vill visa detaljer om verktygsanrop i frontend räcker det att ignorera händelsetyperna `tool_use` / `tool_result` / `card` / `citation`; modellens slutliga utdata strömmas fortfarande ut via `text_delta`. -`max_turns` kan begränsa hur många rundor modellen högst får anropa verktyg själv i denna begäran; standardgränsen bestäms av plattformen. Att sätta det lågt (till exempel `max_turns: 1`) kan tvinga fram ett enstaka svar och inte tillåta några verktygsanrop. +`max_turns` kan begränsa hur många omgångar modellen som mest får anropa verktyg själv i denna begäran, med intervallet 1–500 och standardvärdet 500 om det utelämnas. Om du sätter det lågt (till exempel `max_turns: 1`) kan du tvinga fram ett enstaka svar och förbjuda alla verktygsanrop. -## Asynkron körning och obevakad auktorisering +## Asynkron körning och obemannad auktorisering -Om ditt anrop kommer från en larm-Webhook, CI/CD, ett övervakningssystem eller andra bakgrundsuppgifter kan du ange `async: true` så att gränssnittet omedelbart returnerar ett uppgifts-ID och fortsätter körningen i bakgrunden: +Om ditt anrop kommer från en larm-Webhook, CI/CD, övervakningssystem eller annan bakgrundsuppgift, kan du ange `async: true` så att gränssnittet omedelbart returnerar ett uppgifts-ID och fortsätter körningen i bakgrunden: ```json { "model": "gpt-5.5", "async": true, - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Min tjänst har larmat, meddela WeChat-gruppen ”AceDataCloud团队” via personligt WeChat ……" } ``` -Exempel på svar: +Exempel på returvärde: ```json { @@ -328,9 +328,9 @@ Exempel på svar: } ``` -Därefter kan du använda `action: retrieve` + `id` för att fråga efter konversationsresultatet; du kan också tillhandahålla `callback_url`, och när uppgiften är klar POST:ar plattformen `{ status, answer, usage, error }` till din callback-adress. `callback_url` måste använda `http` / `https` och får inte direkt ange `localhost` eller en literal privat IP-adress. +Därefter kan du använda `action: retrieve` + `id` för att hämta konversationsresultatet; du kan också ange `callback_url`, så POST:ar plattformen `{ status, answer, usage, error }` till din callback-adress när uppgiften är slutförd. `callback_url` måste använda `http` / `https` och får inte direkt ange `localhost` eller en privat IP-literaladress. -För bakgrundsuppgifter finns det vanligtvis ingen som kan klicka för att bekräfta. Om du vill att vissa Skills eller MCP Servers ska utföra åtgärder som att skicka, publicera eller skriva i obevakat läge, ska du uttryckligen skicka en lista över förhandsgodkännanden i request body: +För bakgrundsuppgifter finns det vanligtvis ingen som kan klicka på bekräftelse. Om du vill att vissa Skill eller MCP Server ska utföra åtgärder som att skicka, publicera eller skriva i obemannat läge, ska du uttryckligen skicka en lista över förhandsgodkännanden i request body: ```json { @@ -338,11 +338,11 @@ För bakgrundsuppgifter finns det vanligtvis ingen som kan klicka för att bekr "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "我的服务报警了，用个人微信通知微信群「AceDataCloud团队」……" + "question": "Min tjänst har larmat, meddela WeChat-gruppen ”AceDataCloud团队” via personligt WeChat ……" } ``` -Värdena i `allowed_skills` är sluggar för anslutna Skills; värdena i `allowed_mcp_servers` är sluggar för anslutna MCP Servers. Skills / MCP Servers som inte finns med i förhandsgodkännandet kan i obevakat läge fortfarande bara förhandsgranska, köra dry-run eller nekas att utföra skrivåtgärder. +Värdena i `allowed_skills` är slug för anslutna Skill; värdena i `allowed_mcp_servers` är slug för anslutna MCP Server. Skill / MCP Server som inte listas i förhandsgodkännandet kan i obemannat läge fortfarande bara förhandsgranska, köra dry-run eller nekas att utföra skrivåtgärder. Om mer detaljerad kontroll behövs kan du även använda det likvärdiga objektet `unattended_policy`: @@ -356,26 +356,26 @@ Om mer detaljerad kontroll behövs kan du även använda det likvärdiga objekte } ``` -Förhandsgodkännandet består av just dessa två listor: en tom lista innebär att inga funktioner godkänns och kräver inget extra växlingsfält. +Förhandsgodkännandet består av dessa två listor i sig: en tom lista innebär att inga funktioner godkänns, utan behov av ytterligare växlingsfält. -Observera: förhandsgodkännande innebär endast att ”den här begäran tillåter att dessa funktioner hoppar över manuell bekräftelse i obevakat läge”. Det specifika Skill måste fortfarande stödja `--unattended-confirm` eller motsvarande säkerhetsmekanism; annars fortsätter det med dry-run och utför inte skrivåtgärder direkt. +Observera: förhandsgodkännande betyder endast att ”denna begäran tillåter dessa funktioner att hoppa över manuell bekräftelse i obemannat läge”. Den specifika Skill måste fortfarande stödja `--unattended-confirm` eller motsvarande säkerhetsmekanism; annars fortsätter den som dry-run och utför inte skrivåtgärden direkt. ## Återuppta pausade konversationer -Vissa verktyg får modellen att ”ställa en följdfråga till användaren”. Modellen skickar då en `ask_user_question`-händelse, och konversationen fryses i statusen `awaiting_user_input`: +Vissa verktyg får modellen att ”ställa en motfråga till användaren”; modellen skickar då en `ask_user_question`-händelse och konversationen fryses i tillståndet `awaiting_user_input`: ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "你希望生成的报告是中文还是英文？", + "question": "Vill du att den genererade rapporten ska vara på kinesiska eller engelska?", "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` -Rendera denna händelse som ett kort i frontend så att användaren kan välja ett svar, och initiera sedan nästa begäran med samma `id` genom att återfylla svaret via `tool_results`: +Rendera denna händelse som ett kort i frontend så att användaren kan välja ett svar, och gör sedan nästa begäran med samma `id`, där svaret fylls tillbaka via `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -`tool_use_id` i request body **måste** vara helt identiskt med `tool_id` vid pausen; annars returneras 400. När `tool_results` finns i begäran samtidigt ignoreras `question` / `message` / `references`. +`tool_use_id` i request body **måste** vara helt identiskt med `tool_id` när pausen inträffade; om de inte stämmer överens returneras 400. När `tool_results` finns i begäran samtidigt ignoreras både `question` / `message` / `references`. -Om användaren bestämmer sig för att överge denna fråga räcker det att direkt skicka en ny `question` / `message`; plattformen markerar automatiskt det pausade verktygsanropet som ”hoppades över av användaren”. +Om användaren beslutar sig för att överge denna fråga räcker det att direkt skicka en ny `question` / `message`; plattformen markerar automatiskt det pausade verktygsanropet som ”användaren hoppade över”. ## Konversationshantering (CRUD) -v2 erbjuder lättviktig konversationshantering via fältet `action` på samma endpoint, utan behov av att öppna ett separat API. - +v2 tillhandahåller lättviktig konversationshantering via fältet `action` på samma endpoint, utan att behöva öppna ett separat API. ### `action: retrieve` —— Hämta en konversation + ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,7 +415,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Returnerar det fullständiga konversationsdokumentet (inklusive `messages`-historik, `model`, `title`, `tools_used` osv.). +Returnerar det fullständiga konversationsdokumentet (inklusive historiken `messages`, `model`, `title`, `tools_used` osv.). ### `action: retrieve_batch` —— Lista konversationssammanfattningar @@ -428,21 +428,21 @@ Returnerar det fullständiga konversationsdokumentet (inklusive `messages`-histo } ``` -Returnerar `{ items: [...], total }`. **Sammanfattningar innehåller inte `messages`**, vilket passar för sidofältslistor; om användaren öppnar en konversation använder du sedan `action: retrieve` för att separat hämta dess fullständiga meddelanden. +Returnerar `{ items: [...], total }`. **Sammanfattningar innehåller inte `messages`**, lämpligt för sidofältslistor; om användaren öppnar en konversation använder du sedan `action: retrieve` för att hämta dess fullständiga meddelanden separat. Valfria filterparametrar: `user_id`, `application_id`, `model_group`, `model`. -### `action: update` —— Ändra titel eller skriv om historik +### `action: update` —— Ändra titel eller skriv om historiken ```json { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "title": "Reseplan för Hangzhou" + "title": "杭州旅行计划" } ``` -`messages` kan också skickas, men servern utför strikt schema-validering (det måste vara i den hopfällda `ToolUseContent`-formen), och returnerar 400 om det inte uppfyller kraven. Generellt rekommenderas det endast för att ändra `title`. +`messages` kan också skickas, men servern utför strikt schema-validering (måste vara i den hopfällda formen `ToolUseContent`), och returnerar 400 om det inte uppfyller kraven. Det rekommenderas vanligtvis endast att använda detta för att ändra `title`. ### `action: delete` —— Ta bort en konversation @@ -453,21 +453,21 @@ Valfria filterparametrar: `user_id`, `application_id`, `model_group`, `model`. } ``` -Returnerar `{ id, success: true }`. Efter borttagning kan den inte återställas, bekräfta innan du anropar. +Returnerar `{ id, success: true }`. Det går inte att återställa efter borttagning, bekräfta innan du anropar. -## Migrera smidigt från v1 +## Smidig migrering från v1 -Om du redan använder [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) kräver migreringen till v2 nästan inga kodändringar: +Om du redan använder [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations) kräver migrering till v2 nästan inga kodändringar: 1. Ändra URL:en från `https://api.acedata.cloud/aichat/conversations` till `https://api.acedata.cloud/aichat2/conversations`. -2. Om du tidigare skickade v1-modellnamn (såsom `gpt-3.5`, `gpt-4-browsing` osv.) rekommenderas det att uppgradera till moderna modeller vid byte till v2 (såsom `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` osv.). -3. Fälten i NDJSON-strömmen förblir bakåtkompatibla: varje `text_delta`-händelse innehåller fortfarande `delta_answer` och `id`, så klienter som ursprungligen tolkar `delta_answer` rad för rad behöver inte ändras. +2. Om du tidigare skickade v1-modellnamn (som `gpt-3.5`, `gpt-4-browsing` osv.) rekommenderas du att uppgradera till moderna modeller när du byter till v2 (som `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` osv.). +3. Fälten i NDJSON-strömmen förblir bakåtkompatibla: varje `text_delta`-händelse innehåller fortfarande `delta_answer` och `id`, så klienter som tidigare tolkar `delta_answer` rad för rad behöver inte ändras. -Efter migreringen kan du vid behov aktivera v2:s nya funktioner (multimodala `message`, SSE, verktygsanrop, `action` CRUD) och gå vidare i lämplig takt. +Efter migreringen kan du vid behov aktivera v2:s nya funktioner (multimodalt `message`, SSE, verktygsanrop, `action` CRUD) och gå vidare i din egen takt. ## Felhantering -Felsvar har ett enhetligt format: +Felsvar har en enhetlig form: ```json { @@ -481,14 +481,14 @@ Felsvar har ett enhetligt format: Vanliga fel: -- `400 bad_request`: Saknade obligatoriska fält, `tool_use_id` matchar inte, `messages`-schema är ogiltigt osv. -- `401 invalid_token`: `authorization`-huvudet är felaktigt. +- `400 bad_request`: Obligatoriska fält saknas, `tool_use_id` matchar inte, `messages`-schemat är ogiltigt osv. +- `401 invalid_token`: `authorization`-headern är felaktig. - `404 not_found`: Konversationen som motsvarar `id` finns inte vid `action: retrieve / update / delete`. - `429 too_many_requests`: Hastighetsbegränsningen har utlösts. -- `500 chat_error`: Uppströms-LLM rapporterade ett fel eller `completion_tokens=0` för denna omgång (behandlas som ej förbrukat och debiteras inte). +- `500 chat_error`: Uppströms-LLM rapporterar ett fel eller `completion_tokens=0` i denna omgång (behandlas som ej förbrukat och debiteras inte). -I strömmande svar skickas fel som händelsen `{"type":"error","message":"..."}`, varefter strömmen omedelbart avslutas. +I strömmande svar skickas fel som händelsen `{"type":"error","message":"..."}`, varefter strömmen avslutas direkt. ## Slutsats -AI Chat v2 API uppgraderar, samtidigt som det är bakåtkompatibelt med v1, dialogen från ”enkelrunds- / flerrundsfrågor och svar” till ”observerbara Agent-baserade dialoger”: multimodala indata, verktygsanrop, möjlighet att pausa / återuppta, strömmande strukturerade händelser och inbyggd CRUD. Nya integrationer rekommenderas att använda v2 direkt; befintliga v1-integrationer kan migreras smidigt i etapper. Om du har några frågor, kontakta gärna vårt tekniska supportteam när som helst. +AI Chat v2 API uppgraderar, samtidigt som det är bakåtkompatibelt med v1, konversationer från ”enkelrunds- / flerrundsfrågor och svar” till ”agentifierade observerbara konversationer”: multimodala indata, verktygsanrop, möjlighet att pausa / återuppta, strömmande strukturerade händelser och inbyggd CRUD. Det rekommenderas att nya integrationer använder v2 direkt; befintliga v1-integrationer kan migreras smidigt i etapper. Om du har några frågor, kontakta gärna vårt tekniska supportteam när som helst. diff --git a/sv/guides/platform/hermes_managed.mdx b/sv/guides/platform/hermes_managed.mdx index 8c19fef87..283e33062 100644 --- a/sv/guides/platform/hermes_managed.mdx +++ b/sv/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent Privat Distribution" +title: "Hermes-distribution" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud erbjuder en privat distributionsingång för Hermes Agent. Denna ingång är en kontrollerad tjänst, och tillgänglighet samt valbara resurser baseras på vad som för närvarande visas i konsolen. +Skapa en separat Hermes-containerinstans för varje Application. En basavbildning med en fast utgåveversion används som standard, med ursprungliga funktioner bevarade; plattformen erbjuder köp, förnyelse, beständig lagring och distributionshantering. -## Användningssteg +## Skapa och köpa -1. Hitta **Hermes Agent Privat Distribution** på plattformen. -2. Välj tillgänglig konfiguration och skapa tjänst enligt sidans anvisningar. -3. Vänta på att plattformen visar att den är redo. -4. Använd ingången och autentiseringsuppgifterna som tillhandahålls på sidan för att få åtkomst till instansen. -5. Skicka först `Reply only OK`, och börja sedan med den verkliga uppgiften. +1. Öppna [Hermes-distribution](https://platform.acedata.cloud/services/hermes) och skapa en Application. +2. Välj ett tidspaket på köpsidan och slutför betalningen. +3. Återgå till konfigurationssidan, välj en plattformschattmodell från rullgardinslistan och se det aktuella modellpriset. Plattformen skapar separata API-uppgifter för denna instans; du kan också stänga av plattformsanslutningen och konfigurera den själv i den ursprungliga konsolen. +4. Välj att automatiskt generera åtkomstuppgifter eller ange ditt eget starka lösenord/Token, och starta distributionen efter bekräftelse. Åtkomstuppgifterna och modellens API-uppgifter är oberoende av varandra. +5. När instansen är klar hämtar du åtkomstadressen och inloggningsuppgifterna från hanteringssidan. +6. Logga in i den ursprungliga konsolen och konfigurera dina egna modellleverantörer, nycklar och kanaler. -Modell, autentiseringsuppgifter, lagring och raderingsbeteende baseras på skapelsens sida och bekräftelsepopup; använd inte YAML från den lokala Hermes-handboken som en direkt distributionskontrakt för plattformen. Exportera först de data som behöver bevaras innan du raderar. +Distributionsavgiften debiteras utifrån paketets längd; exakta priser i USD och längder gäller enligt köpsidan. Avgifter för modellanrop tillkommer separat; köp av distributionstid inkluderar inga modellkrediter. När plattformsanslutning är aktiverad öppnar de dedikerade API-uppgifterna endast chattgränssnittet som motsvarar den valda modellen, och anrop debiteras separat från ditt plattformssaldo. Varje Application köps, förnyas och hanteras separat. -Om konsolen inte visar skapelseingången, betyder det att det aktuella kontot för närvarande inte har öppnat denna tjänst, och du kan istället använda [Hermes Interaktiv Guide](https://platform.acedata.cloud/documents/hermes-wizard-integration) eller [Manuell Konfiguration](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Lösenord, uppgifter och efterföljande konfiguration + +Åtkomstuppgifter anges före första uppstarten. Den automatiskt genererade metoden använder slumpmässiga uppgifter, ett anpassat lösenord måste vara minst 16 tecken och en OpenClaw Token minst 32 tecken. Utkast sparar inte lösenord; du kan behöva ange dem igen efter att du har bytt sida. Efter distribution kan endast Application-ägaren och administratörer se åtkomstuppgifterna. + +Varje instans modell-API-uppgifter återanvänds inte, deras giltighet förlängs med distributionsförnyelsen och de återkallas när instansen tas bort. Efter att distributionen har initierats ska du ändra modeller och kanaler i den ursprungliga konsolen; om du väljer en modell från en annan tjänst ska du först justera behörigheten för motsvarande gränssnitt i plattformens uppgiftshantering eller använda motsvarande uppgifter. Vanlig omdistribution skriver inte över ursprungliga inställningar. Distributionsmiljöer som inte har godkänts vid publiceringsvalidering kommer tillfälligt att neka nya distributioner, kontakta supporten. + +## Versioner och data + +Konfigurationssidan visar den aktuellt publicerade avbildningsversionen. Nya instanser använder tjänstens aktuellt publicerade version; befintliga instanser ersätts inte automatiskt när katalogen uppdateras. Omdistribution tillämpar tjänstens aktuella version; säkerhetskopiera först och bekräfta uppgraderingskraven för den version som används. + +Varje instans erbjuder som standard 1 CPU, en minnesgräns på 2 GiB och 10 GiB beständig lagring. Omstart behåller instansdata. Om du aktivt tar bort distributionen eller om den återtas efter utgång tas lagringen bort; exportera data som behöver behållas i förväg. + +## Förnyelse och utgång + +Förnya på köpsidan för den aktuella Application, så förlängs giltighetstiden enligt plattformens befintliga regler för tidslängd. Efter utgång pausas åtkomstpunkten, och förnyelse under respitperioden återställer åtkomsten; efter respitperioden återtas instansen och data. Följ utgångstiden, debiteringsstatusen och borttagningsmeddelandena på hanteringssidan. + +## Logga in i administrationsgränssnittet + +Kopiera Dashboard-adressen, användarnamnet `admin` och lösenordet på distributionshanteringssidan, öppna sedan adressen och logga in. Inloggningsinformation tillhandahålls endast till ägaren av denna Application och plattformsadministratörer. Modeller, färdigheter och kanaler konfigureras i Hermes ursprungliga gränssnitt. + +## Vanliga frågor + +- **Varför kan den nya instansen inte svara ännu?** Att distributionen är klar betyder att containern är redo; du måste konfigurera modellen och uppgifterna i det ursprungliga gränssnittet innan du kan börja använda den. +- **Är extra plugin-program eller modell-fallback förinstallerade?** Inga läggs till som standard; konfigurera dem vid behov i det ursprungliga gränssnittet. +- **Hur uppdaterar jag en befintlig instans?** Den ursprungliga Application och ordern behålls, och den aktuella tjänsteversionen används vid omdistribution; säkerhetskopiera data och kontrollera versionskompatibiliteten före uppgraderingen. +- **Vad gör jag om uppstarten misslyckas?** Kontrollera först distributionsloggarna och händelserna, och konfigurera modellen först efter att instansen är klar. Exponera inte instanslösenord och nycklar i offentliga kommentarer eller skärmbilder. diff --git a/sv/guides/platform/wework_bot.mdx b/sv/guides/platform/wework_bot.mdx deleted file mode 100644 index a06a165ae..000000000 --- a/sv/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/uk/guides/aichat/aichat2_conversations.mdx index df57c93bc..7fb5fd3c3 100644 --- a/uk/guides/aichat/aichat2_conversations.mdx +++ b/uk/guides/aichat/aichat2_conversations.mdx @@ -3,34 +3,34 @@ title: "Інструкція з інтеграції AI Chat v2 API" description: "AI Dialogue API guide - Ace Data Cloud" --- -AI Chat v2 API (`/aichat2/conversations`) — це нове покоління інтерфейсу діалогів, яке є повністю оновленою версією [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). На основі лаконічності v1 та керованих багатораундових діалогів він розширює: +AI Chat v2 API (`/aichat2/conversations`) — це нове покоління інтерфейсу діалогів, повністю оновлена версія [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations). На основі простоти v1 та керованих багатораундових діалогів він розширено такими можливостями: -- **Мультимодальні введення користувача**: безпосередньо передавайте текст + зображення + блоки файлів через структуроване поле `message`, без необхідності попередньо непрямо додавати їх за допомогою `references`. -- **Агентні виклики інструментів**: вбудований набір інструментів для онлайн-пошуку, отримання вебсторінок, читання файлів тощо, а також можливість підключати MCP-сервери, авторизовані користувачем (Google Drive, Notion, Slack, GitHub тощо); модель може в межах одного запиту автономно багаторазово викликати інструменти для виконання складних завдань. -- **Структуровані потокові події**: через `accept: text/event-stream` або `application/x-ndjson` можна отримувати події `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` тощо для кожного токена, що зручно для окремого рендерингу за відповідними типами на фронтенді. -- **Можливість переривання / відновлення**: коли моделі потрібно, щоб користувач доповнив інформацію, вона надсилає подію `ask_user_question` і призупиняється; під час наступного виклику достатньо повернути відповідь через `tool_results`, щоб продовжити. -- **Нові CRUD-дії**: через поле `action` на тому самому endpoint можна виконувати `retrieve` / `retrieve_batch` / `update` / `delete`, без потреби в додатковому API для керування діалогами. -- **Список моделей, що постійно оновлюється**: за замовчуванням підключені сучасні моделі GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 тощо. +- **Мультимодальне введення користувача**: безпосереднє передавання тексту + зображень + блоків файлів через структуроване поле `message`, без необхідності спершу непрямо додавати їх через `references`. +- **Виклики інструментів в Agent-форматі**: вбудований набір інструментів для пошуку в Інтернеті, отримання вебсторінок, читання файлів тощо, а також можливість підключати авторизовані користувачем MCP-сервери (Google Drive, Notion, Slack, GitHub тощо); модель може самостійно виконувати багатораундові виклики інструментів в одному запиті для завершення складних завдань. +- **Структуровані потокові події**: через `accept: text/event-stream` або `application/x-ndjson` можна отримувати події `text_delta`, `tool_use`, `tool_result`, `thinking`, `citation`, `card`, `artifact` тощо для кожного токена, що полегшує їх окреме відображення на фронтенді за відповідними типами. +- **Можливість переривання / відновлення**: коли моделі потрібно, щоб користувач доповнив інформацію, вона надсилає подію `ask_user_question` і призупиняється; під час наступного виклику можна продовжити, передавши відповідь назад через `tool_results`. +- **Нові CRUD-дії**: через поле `action` в одному й тому самому endpoint можна виконувати `retrieve` / `retrieve_batch` / `update` / `delete`, без потреби в додатковому API для керування діалогами. +- **Список моделей, що постійно оновлюється**: за замовчуванням підключено сучасні моделі, такі як GPT-5.4, Claude Opus 4.8, Claude Sonnet 4.6, Gemini 3.1 Pro, GLM 5.1, DeepSeek V4, Kimi K3 тощо. -Водночас на рівні тіла запиту він **повністю зворотно сумісний із v1**: достатньо передати лише `model` + `question` (+ необов’язкові `stateful` / `id` / `references` / `preset`), щоб отримати JSON-відповідь `{answer, id}`, еквівалентну v1; тому для міграції з `/aichat/conversations` не потрібно переписувати клієнт — достатньо замінити шлях на `/aichat2/conversations`. +Водночас на рівні тіла запиту він **повністю зворотно сумісний із v1**: достатньо передати лише `model` + `question` (+ необов’язкові `stateful` / `id` / `references` / `preset`), щоб отримати JSON-відповідь `{answer, id}`, еквівалентну v1. Тому під час міграції з `/aichat/conversations` не потрібно переписувати клієнт — достатньо змінити шлях на `/aichat2/conversations`. -> Якщо ви зараз використовуєте `/aichat/conversations`, старий інтерфейс і надалі буде доступний, і ви можете мігрувати у зручному для себе темпі. +> Якщо ви зараз використовуєте `/aichat/conversations`, старий інтерфейс продовжить працювати, і ви можете мігрувати у власному темпі. ## Процес подання заявки -Щоб використовувати AI Chat v2 API, спершу перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications), щоб отримати ваш API Token і зберегти його для подальшого використання. +Щоб використовувати AI Chat v2 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). > 📘 Повна документація: [AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## Базове використання -Найпростіше використання повністю відповідає v1: передайте `model` + `question` і отримайте `{answer, id}`. +Найпростіший спосіб використання повністю ідентичний v1: передайте `model` + `question` і отримайте `{answer, id}`. Приклад CURL: @@ -45,7 +45,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Результат, що повертається: +Результат повернення: ```json { @@ -86,11 +86,11 @@ print(response.json()) - Moonshot: `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` тощо - Zhipu: `glm-5.3`, `glm-5.2`, `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.7`, `glm-4.5v` тощо -Докладні правила тарифікації дивіться в картці Pricing на сторінці сервісу. +Детальні правила тарифікації дивіться в картці Pricing на сторінці сервісу. ## Багатораундовий діалог -Як і у v1, передайте `stateful: true`, щоб увімкнути збереження діалогу; API поверне `id`; у наступних запитах достатньо передавати цей `id`, щоб продовжити діалог, без необхідності самостійно підтримувати історію messages. +Як і у v1, передайте `stateful: true`, щоб увімкнути збереження діалогу; API поверне `id`; у наступних запитах достатньо передати цей `id`, щоб продовжити діалог, без необхідності самостійно підтримувати історію messages. Перший запит: @@ -106,7 +106,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Повертається: +Повернення: ```json { @@ -115,7 +115,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -Другий запит, додайте той самий `id`: +Другий запит — передайте той самий `id`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -136,17 +136,17 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -> `stateful` за замовчуванням має значення `true`; пропускання та явна передача `true` є еквівалентними. Якщо ви не хочете, щоб сервер зберігав цей раунд діалогу, можна явно встановити `stateful: false`. +> `stateful` за замовчуванням має значення `true`; пропуск і явна передача `true` є еквівалентними. Якщо ви не хочете, щоб сервер зберігав цей раунд діалогу, можна явно встановити `stateful: false`。 ## Потокова відповідь -v2 підтримує два потокові формати, які вибираються за заголовком `accept`: +v2 підтримує два формати потокової передачі, які вибираються відповідно до заголовка `accept`: -| Сценарій | `accept` | Форма даних | +| Сценарій | `accept` | Формат даних | | --------------------- | ---------------------- | ------------------------------------------ | -| Вебфронтенд / EventSource | `text/event-stream` | `data: {json}\n\n`, останній рядок — `data: [DONE]\n\n` | -| Сервер / CLI / потоковий парсинг Node | `application/x-ndjson` | Один JSON-об’єкт у кожному рядку | -| Потоковий режим не потрібен | `application/json`（за замовчуванням） | Одноразово повертає `{answer, id}` | +| Web-фронтенд / EventSource | `text/event-stream` | `data: {json}\n\n`，останній рядок `data: [DONE]\n\n` | +| Сервер / CLI / потоковий парсинг Node | `application/x-ndjson` | Кожен рядок — один JSON-об’єкт | +| Потокова передача не потрібна | `application/json`（за замовчуванням） | Одноразово повертає `{answer, id}` | ### Приклад NDJSON @@ -195,7 +195,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: ### Приклад SSE -Використання `EventSource` у браузері не підтримує власне тіло запиту, тому рекомендується використовувати `fetch` + ручний розбір на зрізи за `\n\n`: +Використання `EventSource` у браузері не підтримує користувацьке тіло запиту, рекомендується використовувати `fetch` + ручний парсинг шляхом розділення на фрагменти за `\n\n`: ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -236,24 +236,24 @@ while (true) { | `type` | Значення | | ------------------- | ----------------------------------------------------------------------------------------------- | -| `text_delta` | Інкрементальний текстовий фрагмент відповіді асистента. `content` містить новий вміст; для сумісності з v1 та сама подія також містить `delta_answer` (дорівнює `content`) та `id`. | -| `thinking` | Процес міркування моделі (з’являється лише тоді, коли вибрана модель розкриває reasoning). | -| `tool_use` | Модель вирішує викликати інструмент; подія містить `tool_id`, `tool_name`, `input`. | -| `tool_result` | Результат виконання інструмента; поєднується з попереднім `tool_use` через `tool_id`, а `is_error` вказує, чи сталася помилка. | -| `card` | Структурована картка, створена інструментом (наприклад, зображення, попередній перегляд посилання), придатна для прямого рендерингу. | -| `citation` | URL-адреса джерела для доповнення посиланнями на відповідні текстові фрагменти. | -| `ask_user_question` | Виникає, коли моделі потрібна додаткова інформація від користувача; діалог переходить у стан `awaiting_user_input`; детальніше див. нижче [Відновлення призупиненого діалогу](#відновлення-призупиненого-діалогу). | -| `artifact` | Незалежний артефакт, створений моделлю (наприклад, блок коду, документ), який можна зберегти або завантажити. | -| `system_message` | Системне інформаційне повідомлення (не вміст користувача чи асистента), використовується лише для підказок в UI. | -| `compact` | Подія, у якій внутрішній контекст було стиснуто; спеціальна обробка не потрібна. | -| `error` | У цьому раунді сталася помилка; `message` описує її вміст. | -| `done` | Потокова відповідь завершена; містить `usage` (зокрема `prompt_tokens` / `completion_tokens` / `total_tokens`) і `terminal_reason`. | +| `text_delta` | Інкрементальний текстовий фрагмент відповіді асистента. `content` містить новий вміст; для сумісності з v1 та сама подія також містить `delta_answer`（дорівнює `content`）і `id`。 | +| `thinking` | Процес міркування моделі（з’являється лише тоді, коли вибрана модель надає reasoning）。 | +| `tool_use` | Модель вирішує викликати інструмент; подія містить `tool_id`、`tool_name`、`input`。 | +| `tool_result` | Результат виконання інструмента, пов’язаний із попереднім `tool_use` через `tool_id`; `is_error` позначає, чи сталася помилка。 | +| `card` | Структурована картка, створена інструментом（наприклад, зображення, попередній перегляд посилання），придатна для прямого відображення。 | +| `citation` | URL-адреса джерела, що використовується для доповнення цитування відповідного текстового фрагмента。 | +| `ask_user_question` | Надсилається, коли моделі потрібно, щоб користувач доповнив інформацію; діалог переходить у стан `awaiting_user_input`，детальніше див. нижче [Відновлення призупиненого діалогу](#відновлення-призупиненого-діалогу)。 | +| `artifact` | Незалежний результат, згенерований моделлю（наприклад, блок коду, документ），який можна зберегти або завантажити。 | +| `system_message` | Системне інформаційне повідомлення（не вміст користувача чи асистента），використовується лише для підказок UI。 | +| `compact` | Подія, за якої внутрішній контекст було стиснуто; спеціальна обробка не потрібна。 | +| `error` | У цьому раунді сталася помилка; `message` описує вміст помилки。 | +| `done` | Потокова відповідь завершена; містить `usage`（включно з `prompt_tokens` / `completion_tokens` / `total_tokens`）і `terminal_reason`。 | -Для клієнтів, яких цікавить лише фінальна відповідь, об’єднання всіх `content` із `text_delta` є еквівалентним `answer` у режимі `application/json`. +Для клієнтів, яких цікавить лише остаточна відповідь, об’єднання `content` усіх `text_delta` є еквівалентним `answer` у режимі `application/json`。 -## Мультимодальне введення +## Мультимодальний ввід -Якщо введення користувача містить зображення або файл, передавайте `message` (масив) замість `question`. Кожен елемент масиву — це блок вмісту: +Якщо введення користувача містить зображення або файл, передайте `message`（масив）замість `question`。Кожен елемент масиву є блоком вмісту: ```json { @@ -268,30 +268,30 @@ while (true) { Підтримувані типи блоків: -- `text` — звичайний текст, обов’язкове поле `text`. -- `image_url` — зображення, обов’язкове поле `image_url.url`. -- `file_url` — файл (PDF, CSV, TXT тощо), обов’язкове поле `file_url.url`. +- `text` — звичайний текст, обов’язкове поле `text`。 +- `image_url` — зображення, обов’язкове поле `image_url.url`。 +- `file_url` — файл（PDF、CSV、TXT тощо），обов’язкове поле `file_url.url`。 -### Зв’язок із `references` у v1 +### Зв’язок із `references` v1 -Для сумісності зі старими клієнтами v2 і надалі розпізнає поле `references: ["https://...", ...]`: -- Суфікс URL — `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, автоматично перетворюється на блок `image_url`; +Для сумісності зі старими клієнтами v2 усе ще розпізнає поле `references: ["https://...", ...]`: +- Якщо суфікс URL є `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`, автоматично перетворюється на блок `image_url`; - Інші розширення перетворюються на блок `file_url`; -- Якщо водночас також надано `question`, він додається попереду як блок `text`. +- Якщо також одночасно надано `question`, він додається на початку як блок `text`. -Тому, якщо ви лише хочете перейти з v1 і не хочете змінювати тіло запиту, достатньо змінити шлях на `/aichat2/conversations`, а початковий спосіб використання `references` продовжить працювати як звично. +Тому, якщо ви хочете лише перейти з v1 і не хочете змінювати тіло запиту, достатньо змінити шлях на `/aichat2/conversations`, оригінальне використання `references` продовжить працювати як раніше. -Якщо потрібен точніший контроль (наприклад, розмістити кілька зображень між текстом або якщо порядок дуже важливий), безпосередньо використовуйте масив `message`. +Якщо потрібен більш точний контроль (наприклад, розміщувати кілька зображень між текстом або якщо порядок є дуже важливим), безпосередньо використовуйте масив `message`. ## Виклики інструментів і MCP -Основне покращення v2 полягає в тому, що модель може самостійно викликати інструменти для виконання багатокрокових завдань, **це увімкнено за замовчуванням**, і клієнту не потрібно виконувати жодних додаткових налаштувань у запиті. Типові сценарії: +Ключове покращення v2 полягає в тому, що модель може самостійно викликати інструменти для виконання багатокрокових завдань, **це увімкнено за замовчуванням**, і клієнту не потрібно виконувати жодних додаткових налаштувань у запиті. Типові сценарії: -- Користувач запитує: «Допоможи мені пошукати, які нові виставки нещодавно проходять у Шанхаї» → модель викликає вбудований web search → упорядковує результати у відповідь. -- Користувач запитує: «Прочитай цей PDF, а потім напиши резюме» → модель викликає file_read → пише резюме. -- Користувач уже авторизував Google Drive / GitHub / Notion тощо у [Connections](https://platform.acedata.cloud/connections) → модель може викликати відповідні інструменти MCP для читання та запису їхніх даних. +- Користувач запитує: «Допоможи мені пошукати, які нові виставки нещодавно є в Шанхаї» → модель викликає вбудований web search → упорядковує результати у відповідь. +- Користувач запитує: «Прочитай цей PDF і потім напиши резюме» → модель викликає file_read → пише резюме. +- Користувач уже авторизував Google Drive / GitHub / Notion тощо в [Connections](https://platform.acedata.cloud/connections) → модель може викликати відповідні інструменти MCP для читання та запису їхніх даних. -У потоці NDJSON / SSE виклики інструментів відображаються через два типи подій `tool_use` і `tool_result`, наприклад: +У потоці NDJSON / SSE виклики інструментів відображаються через два типи подій: `tool_use` і `tool_result`, наприклад: ```json {"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} @@ -301,13 +301,13 @@ while (true) { ... ``` -Якщо ви не хочете відображати у фронтенді деталі викликів інструментів, достатньо ігнорувати такі типи подій, як `tool_use` / `tool_result` / `card` / `citation`; фінальний вивід моделі все одно надходить через потік `text_delta`. +Якщо ви не хочете показувати у фронтенді деталі викликів інструментів, достатньо ігнорувати події типів `tool_use` / `tool_result` / `card` / `citation`; остаточний вивід моделі все одно надходить через потік `text_delta`. -`max_turns` може обмежити максимальну кількість раундів самостійних викликів інструментів моделлю в цьому запиті, а верхня межа за замовчуванням визначається платформою. Якщо встановити мале значення (наприклад, `max_turns: 1`), можна примусово отримати одноразову відповідь і не дозволити жодних викликів інструментів. +`max_turns` може обмежувати максимальну кількість раундів, у яких модель може самостійно викликати інструменти в цьому запиті; діапазон — 1–500, за замовчуванням, якщо його пропущено, — 500. Якщо встановити його на мале значення (наприклад, `max_turns: 1`), можна примусово отримати одноразову відповідь без дозволу на будь-які виклики інструментів. -## Асинхронне виконання та авторизація без нагляду +## Асинхронне виконання й авторизація без нагляду -Якщо ваш виклик надходить з Webhook сповіщень, CI/CD, системи моніторингу або інших фонових завдань, можна встановити `async: true`, щоб інтерфейс негайно повернув ID завдання, а виконання продовжилося у фоні: +Якщо ваш виклик походить із Webhook сповіщення, CI/CD, системи моніторингу або іншого фонового завдання, ви можете встановити `async: true`, щоб інтерфейс негайно повернув ID завдання, а виконання продовжилося у фоні: ```json { @@ -328,9 +328,9 @@ while (true) { } ``` -Після цього можна використовувати `action: retrieve` + `id` для запиту результату розмови; також можна надати `callback_url`, і після завершення завдання платформа надішле `{ status, answer, usage, error }` методом POST на вашу адресу зворотного виклику. `callback_url` повинен використовувати `http` / `https`, і не можна безпосередньо вказувати `localhost` або літеральну адресу приватного IP. +Після цього ви можете використати `action: retrieve` + `id` для запиту результату розмови; також можна надати `callback_url`, і після завершення завдання платформа надішле `{ status, answer, usage, error }` методом POST на вашу адресу зворотного виклику. `callback_url` повинен використовувати `http` / `https`, і в ньому не можна безпосередньо вказувати `localhost` або літеральну адресу приватної IP-адреси. -У фонових завданнях зазвичай немає людини, яка може натиснути підтвердження. Якщо ви хочете, щоб певні Skill або MCP Server виконували дії надсилання, публікації, запису тощо в режимі без нагляду, явно передайте в тілі запиту список попередньої авторизації: +У фонових завданнях зазвичай немає кому натиснути підтвердження. Якщо ви хочете, щоб певні Skill або MCP Server виконували дії надсилання, публікації, запису тощо в режимі без нагляду, явно передайте список попередньої авторизації в тілі запиту: ```json { @@ -342,9 +342,9 @@ while (true) { } ``` -Значення в `allowed_skills` — це slug підключених Skill; значення в `allowed_mcp_servers` — це slug підключених MCP Server. Skill / MCP Server, які не внесені до попередньої авторизації, у режимі без нагляду все ще можуть лише виконувати попередній перегляд, dry-run або відмовлятися від виконання операцій запису. +Значення в `allowed_skills` — це slug підключених Skill; значення в `allowed_mcp_servers` — це slug підключених MCP Server. Skill / MCP Server, не включені до попередньої авторизації, у режимі без нагляду все одно можуть лише переглядати, виконувати dry-run або відмовлятися від виконання операцій запису. -Якщо потрібен детальніший контроль, також можна використовувати еквівалентний об’єкт `unattended_policy`: +Якщо потрібен детальніший контроль, також можна використати еквівалентний об’єкт `unattended_policy`: ```json { @@ -356,13 +356,13 @@ while (true) { } ``` -Попередня авторизація — це самі ці два списки: порожній список означає, що жодні можливості не авторизовано, без потреби в додатковому полі-перемикачі. +Попередня авторизація — це самі ці два списки: порожній список означає, що жодні можливості не авторизовано, додаткове поле-перемикач не потрібне. -Зверніть увагу: попередня авторизація означає лише, що «цей запит дозволяє цим можливостям пропустити ручне підтвердження в режимі без нагляду». Конкретний Skill усе одно повинен підтримувати `--unattended-confirm` або відповідний механізм безпеки; інакше він продовжить виконувати dry-run і не виконуватиме операції запису безпосередньо. +Зверніть увагу: попередня авторизація означає лише «цей запит дозволяє цим можливостям пропускати ручне підтвердження в режимі без нагляду». Конкретний Skill усе одно повинен підтримувати `--unattended-confirm` або відповідний механізм безпеки; інакше він продовжить виконувати dry-run і не виконуватиме операції запису безпосередньо. -## Відновлення призупиненої розмови +## Відновлення призупинених розмов -Деякі інструменти змушують модель «ставити користувачу зустрічне запитання», і в цей момент модель надсилає подію `ask_user_question`, а розмова заморожується у стані `awaiting_user_input`: +Деякі інструменти змушують модель «перепитати користувача»; у цей момент модель надсилає подію `ask_user_question`, а розмова заморожується у стані `awaiting_user_input`: ```json { @@ -375,7 +375,7 @@ while (true) { } ``` -У фронтенді відрендерте цю подію як картку, щоб користувач вибрав відповідь, а потім надішліть наступний запит із тим самим `id`, повернувши відповідь через `tool_results`: +На фронтенді відрендеріть цю подію як картку, щоб користувач міг вибрати відповідь, а потім ініціюйте наступний запит із тим самим `id`, повернувши відповідь через `tool_results`: ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -`tool_use_id` у тілі запиту **обов’язково** має повністю збігатися з `tool_id` під час призупинення; у разі невідповідності буде повернуто 400. Коли в запиті одночасно присутні `tool_results`, `question` / `message` / `references` усі ігноруються. +`tool_use_id` у тілі запиту **має** повністю збігатися з `tool_id` у момент призупинення; у разі невідповідності буде повернуто 400. Якщо у запиті одночасно присутній `tool_results`, `question` / `message` / `references` будуть проігноровані. -Якщо користувач вирішить відмовитися від цього питання, достатньо безпосередньо передати новий `question` / `message`, і платформа автоматично позначить призупинений виклик інструменту як «пропущений користувачем». +Якщо користувач вирішить відмовитися від цього питання, достатньо безпосередньо передати новий `question` / `message`, і платформа автоматично позначить призупинений виклик інструмента як «пропущений користувачем». ## Керування розмовами (CRUD) -v2 на тому самому endpoint надає легковагове керування розмовами через поле `action`, без потреби окремо відкривати API. +v2 надає полегшене керування розмовами через поле `action` у тому самому endpoint, без необхідності відкривати окремий API. +### `action: retrieve` —— отримати сеанс -### `action: retrieve` —— отримати розмову ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,9 +415,9 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -Повертає повний документ розмови (включно з історією `messages`, `model`, `title`, `tools_used` тощо). +Повертає повний документ сеансу (включно з історією `messages`, `model`, `title`, `tools_used` тощо). -### `action: retrieve_batch` —— перелічити стислий опис розмов +### `action: retrieve_batch` —— перелічити зведення сеансів ```json { @@ -428,7 +428,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -Повертає `{ items: [...], total }`. **Стислий опис не містить `messages`**, він підходить для списку на бічній панелі; якщо користувач відкриває певну розмову, потім окремо отримайте її повні повідомлення за допомогою `action: retrieve`. +Повертає `{ items: [...], total }`. **Зведення не містить `messages`**, підходить для списку на бічній панелі; якщо користувач відкриває певний сеанс, потім використовуйте `action: retrieve`, щоб окремо отримати його повні повідомлення. Необов’язкові параметри фільтрації: `user_id`, `application_id`, `model_group`, `model`. @@ -438,13 +438,13 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ { "action": "update", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "title": "杭州旅行计划" + "title": "План подорожі до Ханчжоу" } ``` -Також можна передати `messages`, але сервер виконуватиме сувору перевірку schema (має бути форма згорнутого `ToolUseContent`), у разі невідповідності буде повернено 400. Зазвичай рекомендується використовувати це лише для зміни `title`. +`messages` також можна передати, але сервер виконує сувору перевірку schema (має бути у згорнутій формі `ToolUseContent`), інакше буде повернено 400. Зазвичай рекомендується використовувати це лише для зміни `title`. -### `action: delete` —— видалити одну розмову +### `action: delete` —— видалити один сеанс ```json { @@ -457,17 +457,17 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ ## Плавна міграція з v1 -Якщо ви вже використовуєте [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), міграція на v2 майже не потребує змін у коді: +Якщо ви вже використовуєте [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations), міграція на v2 майже не потребує змін коду: 1. Змініть URL з `https://api.acedata.cloud/aichat/conversations` на `https://api.acedata.cloud/aichat2/conversations`. 2. Якщо раніше ви передавали назви моделей v1 (наприклад, `gpt-3.5`, `gpt-4-browsing` тощо), під час переходу на v2 рекомендується оновитися до сучасних моделей (наприклад, `gpt-5.4`, `claude-opus-4-8`, `gemini-3.1-pro-preview` тощо). -3. Поля потоку NDJSON залишаються зворотно сумісними: кожна подія `text_delta` як і раніше містить `delta_answer` та `id`, тому клієнту, який раніше розбирав `delta_answer` построково, не потрібно нічого змінювати. +3. Поля потоку NDJSON залишаються зворотно сумісними: кожна подія `text_delta` як і раніше містить `delta_answer` та `id`, тому клієнтам, які раніше розбирали `delta_answer` рядок за рядком, не потрібно вносити зміни. -Після міграції можна за потреби ввімкнути нові можливості v2 (мультимодальне `message`, SSE, виклики інструментів, `action` CRUD) і впроваджувати їх у зручному темпі. +Після міграції ви можете за потреби увімкнути нові можливості v2 (мультимодальне `message`, SSE, виклики інструментів, CRUD через `action`) і поступово впроваджувати їх у зручному темпі. ## Обробка помилок -Відповіді з помилками уніфіковані: +Відповідь із помилкою має уніфікований формат: ```json { @@ -483,12 +483,12 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ - `400 bad_request`: відсутні обов’язкові поля, `tool_use_id` не збігається, schema `messages` є недійсною тощо. - `401 invalid_token`: заголовок `authorization` неправильний. -- `404 not_found`: під час `action: retrieve / update / delete` розмова, що відповідає `id`, не існує. +- `404 not_found`: сеанс, якому відповідає `id`, не існує під час `action: retrieve / update / delete`. - `429 too_many_requests`: спрацювало обмеження швидкості. -- `500 chat_error`: помилка висхідної LLM або в цьому раунді `completion_tokens=0` (обробляється як невикористане, плата не стягується). +- `500 chat_error`: помилка у висхідній LLM або в цьому раунді `completion_tokens=0` (розглядається як невикористане, плата не стягується). -У потоковій відповіді помилка надсилається як подія `{"type":"error","message":"..."}`, після чого потік одразу завершується. +У потоковій відповіді помилки надсилаються як подія `{"type":"error","message":"..."}`, після чого потік одразу завершується. ## Висновок -AI Chat v2 API, зберігаючи зворотну сумісність із v1, оновлює діалоги з «одиночних / багатораундових запитань і відповідей» до «спостережуваних Agent-діалогів»: мультимодальний ввід, виклики інструментів, можливість призупинення / відновлення, потокові структуровані події, вбудований CRUD. Для нових інтеграцій рекомендується одразу використовувати v2; наявні інтеграції v1 можна плавно мігрувати поетапно. Якщо у вас виникнуть будь-які запитання, будь ласка, звертайтеся до нашої команди технічної підтримки в будь-який час. +AI Chat v2 API, зберігаючи зворотну сумісність із v1, оновлює діалог із «одиночних / багатораундових запитань і відповідей» до «спостережуваного діалогу з Agent»: мультимодальне введення, виклики інструментів, можливість призупинення / відновлення, потокові структуровані події, вбудований CRUD. Для нових інтеграцій рекомендується одразу використовувати v2; наявні інтеграції v1 можуть плавно мігрувати поетапно. Якщо у вас виникнуть будь-які запитання, будь ласка, звертайтеся до нашої команди технічної підтримки в будь-який час. diff --git a/uk/guides/platform/hermes_managed.mdx b/uk/guides/platform/hermes_managed.mdx index 6a3bad0b5..d320b44bd 100644 --- a/uk/guides/platform/hermes_managed.mdx +++ b/uk/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent приватне розгортання" +title: "Розгортання Hermes" description: "Platform API guide - Ace Data Cloud" --- -Ace Data Cloud надає вхід для приватного розгортання Hermes Agent. Цей вхід є контрольованою службою, доступність та вибір ресурсів визначаються поточним відображенням на консолі. +Створюйте окремий екземпляр контейнера Hermes для кожного Application. За замовчуванням використовується базовий образ фіксованої версії релізу зі збереженням нативних функцій; платформа надає купівлю, продовження, постійне сховище та керування розгортанням. -## Кроки використання +## Створення та купівля -1. Знайдіть на платформі **Hermes Agent приватне розгортання**. -2. Виберіть доступну конфігурацію та створіть службу відповідно до підказок на сторінці. -3. Дочекайтеся, поки платформа відобразить стан готовності. -4. Використовуйте наданий на сторінці вхід та облікові дані для доступу до екземпляра. -5. Спочатку надішліть `Reply only OK`, а потім починайте реальне завдання. +1. Відкрийте [розгортання Hermes](https://platform.acedata.cloud/services/hermes) і створіть Application. +2. На сторінці купівлі виберіть тарифний план за тривалістю та завершіть оплату. +3. Поверніться на сторінку конфігурації, де можна вибрати модель чату платформи зі спадного списку та переглянути поточну ціну моделі. Платформа створить незалежні API-облікові дані для цього екземпляра; також можна вимкнути доступ платформи та налаштувати все самостійно в нативній консолі. +4. Виберіть автоматичне створення облікових даних доступу або встановіть власний надійний пароль/Token, після підтвердження почнеться розгортання. Облікові дані доступу та API-облікові дані моделі є незалежними одне від одного. +5. Після готовності екземпляра отримайте адресу доступу та облікові дані для входу на сторінці керування. +6. Увійдіть до нативної консолі та налаштуйте власних постачальників моделей, ключі й канали. -Модель, облікові дані, зберігання та дії з видаленням визначаються сторінкою створення та вікном підтвердження; не використовуйте YAML з локального посібника Hermes безпосередньо як контракт для розгортання на платформі. Перед видаленням спочатку експортуйте дані, які потрібно зберегти. +Плата за розгортання стягується відповідно до тривалості тарифного плану; конкретна ціна в доларах США та тривалість вказуються на сторінці купівлі. Витрати на виклики моделей стягуються окремо; придбання тривалості розгортання не надає квоти моделі. Якщо увімкнено доступ платформи, спеціальні API-облікові дані відкривають лише інтерфейс чату, що відповідає вибраній моделі, а виклики додатково оплачуються з вашого балансу платформи. Кожен Application купується, продовжується та керується окремо. -Якщо консоль не відображає вхід для створення, це означає, що поточний обліковий запис ще не має доступу до цієї служби, можна скористатися [Hermes інтерактивним майстром](https://platform.acedata.cloud/documents/hermes-wizard-integration) або [ручним налаштуванням](https://platform.acedata.cloud/documents/hermes-manual-integration). +## Паролі, облікові дані та подальша конфігурація + +Облікові дані доступу встановлюються до першого запуску. Автоматичний спосіб використовує випадкові облікові дані, користувацький пароль має містити щонайменше 16 символів, а OpenClaw Token — щонайменше 32 символи. Чернетка не зберігає пароль; після переходу на іншу сторінку може знадобитися ввести його повторно. Після розгортання лише власник Application та адміністратори можуть переглядати облікові дані доступу. + +API-облікові дані моделі кожного екземпляра не використовуються спільно, їхня чинність продовжується разом із продовженням розгортання, а під час видалення екземпляра вони відкликаються. Після ініціалізації розгортання змінюйте моделі та канали в нативній консолі; якщо ви обираєте модель іншого сервісу, спочатку скоригуйте авторизацію відповідного інтерфейсу в керуванні обліковими даними платформи або використовуйте відповідні облікові дані. Звичайне повторне розгортання не перезаписує нативні налаштування. Середовища розгортання, що не пройшли перевірку публікації, тимчасово відхилятимуть нові розгортання; зверніться до підтримки. + +## Версії та дані + +На сторінці конфігурації відображається поточна версія опублікованого образу. Нові екземпляри використовують поточну опубліковану версію сервісу; наявні екземпляри не замінюються автоматично після оновлення каталогу. Повторне розгортання застосує поточну версію сервісу; спочатку створіть резервну копію та підтвердьте вимоги до оновлення використовуваної версії. + +Кожен екземпляр за замовчуванням надає 1 CPU, ліміт пам’яті 2 GiB і 10 GiB постійного сховища. Перезапуск зберігає дані екземпляра. Активне видалення розгортання або вилучення після завершення терміну дії видалить сховище; заздалегідь експортуйте дані, які потрібно зберегти. + +## Продовження та завершення терміну дії + +Продовжуйте термін дії на сторінці купівлі поточного Application; термін дії буде продовжено відповідно до наявних правил тривалості платформи. Після завершення терміну дії точка доступу призупиняється, а продовження протягом пільгового періоду відновлює доступ; після завершення пільгового періоду екземпляр і дані буде вилучено. Орієнтуйтеся на час завершення терміну дії, статус виставлення рахунків і повідомлення про видалення на сторінці керування. + +## Вхід до інтерфейсу керування + +На сторінці керування розгортанням скопіюйте адресу Dashboard, ім’я користувача `admin` і пароль, після чого відкрийте адресу та увійдіть. Інформація для входу надається лише власнику цього Application і адміністраторам платформи. Моделі, навички та канали налаштовуються в нативному інтерфейсі Hermes. + +## Поширені запитання + +- **Чому новий екземпляр ще не може відповідати?** Завершення розгортання означає, що контейнер готовий; перед початком використання потрібно налаштувати модель та облікові дані в нативному інтерфейсі. +- **Чи попередньо встановлено додаткові плагіни або fallback моделей?** За замовчуванням не додаються, налаштуйте їх за потреби в нативному інтерфейсі. +- **Як оновити наявний екземпляр?** Початкові Application і замовлення зберігаються, а під час повторного розгортання використовується поточна версія сервісу; перед оновленням спочатку створіть резервну копію даних і перевірте сумісність версії. +- **Що робити в разі помилки запуску?** Спочатку перегляньте журнали та події розгортання, а після підтвердження готовності екземпляра налаштуйте модель. Не розкривайте пароль екземпляра та ключі в публічних коментарях або знімках екрана. diff --git a/uk/guides/platform/wework_bot.mdx b/uk/guides/platform/wework_bot.mdx deleted file mode 100644 index 644130b59..000000000 --- a/uk/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/zh-Hans/guides/aichat/aichat2_conversations.mdx index 14c208dc0..46918244e 100644 --- a/zh-Hans/guides/aichat/aichat2_conversations.mdx +++ b/zh-Hans/guides/aichat/aichat2_conversations.mdx @@ -305,7 +305,7 @@ v2 的核心增强点是模型可以自主调用工具完成多步任务，**这 如果你不想在前端展示工具调用细节，忽略 `tool_use` / `tool_result` / `card` / `citation` 这几类事件即可，模型最终输出依然通过 `text_delta` 流出。 -`max_turns` 可以限制本次请求里模型最多自我调用工具几轮，默认上限由平台决定。把它设小（比如 `max_turns: 1`）可以强制单次回答、不允许任何工具调用。 +`max_turns` 可以限制本次请求里模型最多自我调用工具几轮，范围为 1–500，省略时默认 500。把它设小（比如 `max_turns: 1`）可以强制单次回答、不允许任何工具调用。 ## 异步执行与无人值守授权 diff --git a/zh-Hans/guides/platform/hermes_managed.mdx b/zh-Hans/guides/platform/hermes_managed.mdx index fa6a13b2f..46d487f76 100644 --- a/zh-Hans/guides/platform/hermes_managed.mdx +++ b/zh-Hans/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent 私有部署" +title: "Hermes 部署" description: "Platform 集成指南 - Ace Data Cloud" --- -Ace Data Cloud 提供 Hermes Agent 私有部署入口。该入口为受控服务，是否可用及可选资源以控制台当前显示为准。 +为每个 Application 创建独立 Hermes 容器实例。默认使用固定发行版本的基础镜像，保留原生功能；平台提供购买、续费、持久化存储与部署管理。 -## 使用步骤 +## 创建与购买 -1. 在平台找到 **Hermes Agent 私有部署**。 -2. 按页面提示选择可用配置并创建服务。 -3. 等待平台显示就绪状态。 -4. 使用页面提供的入口和凭据访问实例。 -5. 先发送 `Reply only OK`，再开始真实任务。 +1. 打开 [Hermes 部署](https://platform.acedata.cloud/services/hermes) 并创建 Application。 +2. 在购买页选择时长套餐，完成付款。 +3. 返回配置页，可从下拉列表选择平台聊天模型，并查看当前模型价格。平台会为这个实例创建独立 API 凭据；也可关闭平台接入，在原生控制台自行配置。 +4. 选择自动生成访问凭据，或设置自己的强密码/Token，确认后开始部署。访问凭据与模型 API 凭据互相独立。 +5. 实例就绪后，从管理页取得访问地址与登录凭据。 +6. 登录原生控制台，配置自己的模型提供商、密钥和渠道。 -模型、凭据、存储和删除行为以创建页面及确认弹窗为准；不要把本地 Hermes 教程中的 YAML 直接当作平台部署合同。删除前先导出需要保留的数据。 +部署费按套餐时长计费，具体美元价格、时长以购买页为准。模型调用费用另计；购买部署时长不会赠送模型额度。启用平台接入时，专用 API 凭据仅开放所选模型对应的聊天接口，调用从你的平台余额另外计费。每个 Application 分别购买、续费和管理。 -如果控制台未显示创建入口，说明当前账户暂未开放该服务，可改用 [Hermes 交互向导](https://platform.acedata.cloud/documents/hermes-wizard-integration) 或 [手动配置](https://platform.acedata.cloud/documents/hermes-manual-integration)。 +## 密码、凭据与后续配置 + +访问凭据会在首次启动前设置。自动生成方式使用随机凭据，自定义密码至少 16 个字符，OpenClaw Token 至少 32 个字符。草稿不保存密码；切换页面后可能需要重新输入。部署后，只有 Application 所有者和管理员能查看访问凭据。 + +每个实例的模型 API 凭据互不复用，随部署续费延长有效期，删除实例时撤销。部署初始化后，请在原生控制台修改模型和渠道；如果改选其他服务的模型，请先在平台凭据管理中调整对应接口授权，或使用相应凭据。普通重新部署不会覆盖原生设置。未经发布验证的部署环境会暂时拒绝新部署，请联系支持。 + +## 版本与数据 + +配置页显示当前发布的镜像版本。新建实例使用服务当前发布版本；现有实例不会随目录更新自动替换。重新部署会应用当前服务版本，请先备份，确认所用版本的升级要求。 + +每个实例默认提供 1 CPU、2 GiB 内存上限和 10 GiB 持久化存储。重启保留实例数据。主动删除部署或到期回收会删除存储，请提前导出需要保留的数据。 + +## 续费与到期 + +在当前 Application 的购买页续费，有效期按平台现有时长规则延长。到期后访问入口暂停，宽限期内续费恢复访问；超过宽限期会回收实例与数据。以管理页的到期时间、计费状态及删除提示为准。 + +## 登录管理界面 + +在部署管理页复制 Dashboard 地址、用户名 `admin` 和密码，打开后登录。登录信息仅向该 Application 的所有者和平台管理员提供。模型、技能与渠道在 Hermes 原生界面中配置。 + +## 常见问题 + +- **为什么新实例还不能回答？** 部署完成表示容器就绪；需要在原生界面配置模型和凭据才能开始使用。 +- **是否预装额外插件或模型 fallback？** 默认不添加，按需要在原生界面配置。 +- **已有实例怎么更新？** 原有 Application 和订单保留，重新部署时使用当前服务版本；升级前先备份数据并检查版本兼容性。 +- **启动失败怎么办？** 先查看部署日志与事件，确认实例就绪后再配置模型。不要在公开评论或截图中暴露实例密码和密钥。 diff --git a/zh-Hans/guides/platform/wework_bot.mdx b/zh-Hans/guides/platform/wework_bot.mdx deleted file mode 100644 index eb176a965..000000000 --- a/zh-Hans/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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/aichat/aichat2_conversations.mdx b/zh-Hant/guides/aichat/aichat2_conversations.mdx index 0a2cea101..dc1e6f844 100644 --- a/zh-Hant/guides/aichat/aichat2_conversations.mdx +++ b/zh-Hant/guides/aichat/aichat2_conversations.mdx @@ -5,16 +5,16 @@ description: "AI Dialogue 整合指南 - Ace Data Cloud" AI Chat v2 API（`/aichat2/conversations`）是新一代的對話介面，是 [AI Chat API](https://platform.acedata.cloud/documents/aichat-conversations) 的全面升級版本。它在 v1 簡潔、託管多輪對話的基礎上，擴展了： -- **多模態使用者輸入**：透過結構化 `message` 欄位直接傳送文字 + 圖片 + 檔案區塊，無需先使用 `references` 間接附加。 -- **Agent 化工具呼叫**：內建一套網路搜尋、網頁擷取、檔案讀取等工具，並可掛載使用者授權的 MCP 伺服器（Google Drive、Notion、Slack、GitHub 等），模型可在一次請求裡多輪自主呼叫工具完成複雜任務。 +- **多模態使用者輸入**：透過結構化 `message` 欄位直接傳送文字 + 圖片 + 檔案區塊，無需先用 `references` 間接附加。 +- **Agent 化工具呼叫**：內建一套連網搜尋、網頁擷取、檔案讀取等工具，並可掛載使用者授權的 MCP 伺服器（Google Drive、Notion、Slack、GitHub 等），模型可在一次請求裡多輪自主呼叫工具完成複雜任務。 - **結構化串流事件**：透過 `accept: text/event-stream` 或 `application/x-ndjson` 可取得逐 token 的 `text_delta`、`tool_use`、`tool_result`、`thinking`、`citation`、`card`、`artifact` 等事件，便於在前端依對應類型分別渲染。 - **可中斷 / 可恢復**：模型在需要使用者補充資訊時會發出 `ask_user_question` 事件並暫停，下次呼叫透過 `tool_results` 回填答案即可繼續。 - **新增 CRUD 動作**：在同一個 endpoint 上透過 `action` 欄位完成 `retrieve` / `retrieve_batch` / `update` / `delete`，無需額外的會話管理 API。 -- **持續更新的模型清單**：預設接入 GPT-5.4、Claude Opus 4.8、Claude Sonnet 4.6、Gemini 3.1 Pro、GLM 5.1、DeepSeek V4、Kimi K3 等當代模型。 +- **持續更新的模型列表**：預設接入 GPT-5.4、Claude Opus 4.8、Claude Sonnet 4.6、Gemini 3.1 Pro、GLM 5.1、DeepSeek V4、Kimi K3 等當代模型。 -同時它在請求體層面**完全向後相容 v1**：只傳送 `model` + `question`（+ 可選 `stateful` / `id` / `references` / `preset`）即可取得與 v1 等價的 `{answer, id}` JSON 回應，所以從 `/aichat/conversations` 遷移過來不需要重寫用戶端，只需將路徑換為 `/aichat2/conversations`。 +同時它在請求體層面**完全向後相容 v1**：只傳 `model` + `question`（+ 可選 `stateful` / `id` / `references` / `preset`）即可得到與 v1 等價的 `{answer, id}` JSON 回應，所以從 `/aichat/conversations` 遷移過來不需要重寫用戶端，只需把路徑換為 `/aichat2/conversations`。 -> 如果你目前正在使用 `/aichat/conversations`，舊介面仍會保留服務，可以依自己的節奏遷移。 +> 如果你目前在使用 `/aichat/conversations`，舊介面仍會保留服務，可以依自己的節奏遷移。 ## 申請流程 @@ -22,15 +22,15 @@ AI Chat v2 API（`/aichat2/conversations`）是新一代的對話介面，是 [A ![](https://cdn.acedata.cloud/dvc3cg.jpg) -如果你尚未登入或註冊，會自動跳轉至登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。 +如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。 -**一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。 +**一個 API Token 即可呼叫平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。 > 📘 完整文件：[AI Chat v2 API →](https://platform.acedata.cloud/documents/aichat2-conversations) ## 基本使用 -最簡單的用法和 v1 完全一致：傳送 `model` + `question`，取得 `{answer, id}`。 +最簡單的用法和 v1 完全一致：傳 `model` + `question`，取得 `{answer, id}`。 CURL 範例： @@ -90,7 +90,7 @@ print(response.json()) ## 多輪對話 -和 v1 一樣，傳送 `stateful: true` 開啟會話儲存，API 會回傳一個 `id`；後續請求將 `id` 帶回即可繼續對話，無需自行維護 messages 歷史。 +和 v1 一樣，傳 `stateful: true` 開啟會話保存，API 會回傳一個 `id`；後續請求把 `id` 帶回來即可繼續對話，無需自己維護 messages 歷史。 第一次請求： @@ -125,24 +125,24 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ "model": "gpt-5.4", "stateful": true, "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44", - "question": "我剛才讓你記住的數字是多少？" + "question": "我刚才让你记住的数字是多少？" }' ``` ```json { - "answer": "你讓我記住的數字是 42。", + "answer": "你让我记住的数字是 42。", "id": "f2f4b3e8-0c0a-4d3a-aaa2-7ff80c0a1c44" } ``` -> `stateful` 預設是 `true`，省略和明確傳入 `true` 等價。如果你不希望伺服器儲存這一輪對話，可以明確設定 `stateful: false`。 +> `stateful` 預設為 `true`，省略和明確傳入 `true` 等價。如果你不希望伺服器儲存這一輪對話，可以明確設定 `stateful: false`。 ## 串流回應 v2 支援兩種串流格式，依照 `accept` 標頭選擇： -| 場景 | `accept` | 資料型態 | +| 情境 | `accept` | 資料形態 | | --------------------- | ---------------------- | ------------------------------------------ | | Web 前端 / EventSource | `text/event-stream` | `data: {json}\n\n`，最後一行 `data: [DONE]\n\n` | | 伺服器端 / CLI / Node 串流解析 | `application/x-ndjson` | 每行一個 JSON 物件 | @@ -165,7 +165,7 @@ headers = { payload = { "model": "gpt-5.4", "stateful": True, - "question": "用三句話介紹杭州。", + "question": "用三句话介绍杭州。", } with requests.post(url, json=payload, headers=headers, stream=True) as resp: @@ -175,7 +175,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: continue event = json.loads(line) if event.get("type") == "text_delta": - # 與 v1 相容：增量片段同時透過 delta_answer 欄位提供 + # 与 v1 兼容：增量片段同时通过 delta_answer 字段提供 answer += event["content"] print(event["delta_answer"], end="", flush=True) elif event.get("type") == "done": @@ -183,7 +183,7 @@ with requests.post(url, json=payload, headers=headers, stream=True) as resp: print("usage =", event.get("usage")) ``` -NDJSON 每一行都是結構化事件，最常見的是 `text_delta`： +NDJSON 的每一行都是結構化事件，最常見的是 `text_delta`： ```json {"type":"text_delta","content":"杭","delta_answer":"杭","id":"f2f4b3e8-..."} @@ -195,7 +195,7 @@ NDJSON 每一行都是結構化事件，最常見的是 `text_delta`： ### SSE 範例 -瀏覽器端使用 `EventSource` 不支援自訂請求主體，建議使用 `fetch` + 手動依照 `\n\n` 切片解析： +瀏覽器端使用 `EventSource` 不支援自訂請求主體，建議使用 `fetch` + 手動依 `\n\n` 切片解析： ```javascript const resp = await fetch("https://api.acedata.cloud/aichat2/conversations", { @@ -239,7 +239,7 @@ while (true) { | `text_delta` | 助手回答的增量文字片段。`content` 為新增內容；為相容 v1，同一事件還攜帶 `delta_answer`（等於 `content`）和 `id`。 | | `thinking` | 模型的思考過程（僅在所選模型暴露 reasoning 時出現）。 | | `tool_use` | 模型決定呼叫一個工具，事件攜帶 `tool_id`、`tool_name`、`input`。 | -| `tool_result` | 工具執行結果，與上一條 `tool_use` 透過 `tool_id` 配對，`is_error` 標示是否失敗。 | +| `tool_result` | 工具執行結果，與上一條 `tool_use` 透過 `tool_id` 配對，`is_error` 標識是否失敗。 | | `card` | 工具產出的結構化卡片（如圖片、連結預覽），適合直接渲染。 | | `citation` | 用於補充對應文字片段引用的來源 URL。 | | `ask_user_question` | 模型需要使用者補充資訊時發出，對話進入 `awaiting_user_input` 狀態，詳見下文 [恢復暫停的對話](#恢復暫停的對話)。 | @@ -249,7 +249,7 @@ while (true) { | `error` | 本輪發生錯誤，`message` 描述錯誤內容。 | | `done` | 串流回應結束，攜帶 `usage`（含 `prompt_tokens` / `completion_tokens` / `total_tokens`）和 `terminal_reason`。 | -對於只關心最終答案的用戶端，把所有 `text_delta` 的 `content` 串接起來就和 `application/json` 模式下的 `answer` 等價。 +對於只關心最終答案的用戶端，將所有 `text_delta` 的 `content` 串接起來就和 `application/json` 模式下的 `answer` 等價。 ## 多模態輸入 @@ -260,7 +260,7 @@ while (true) { "model": "gpt-5.4", "stateful": true, "message": [ - { "type": "text", "text": "这张图片里有几只猫？" }, + { "type": "text", "text": "這張圖片裡有幾隻貓？" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/cats.jpg" } } ] } @@ -275,45 +275,45 @@ while (true) { ### 與 v1 `references` 的關係 為了相容舊用戶端，v2 仍然識別 `references: ["https://...", ...]` 欄位： -- URL 後綴為 `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`，自動轉成 `image_url` 區塊； +- URL 後綴是 `jpg / jpeg / png / gif / bmp / webp / svg / heic / heif`，自動轉成 `image_url` 區塊； - 其他副檔名轉成 `file_url` 區塊； - 如果還同時提供了 `question`，則把它作為一個 `text` 區塊前置。 -因此只想從 v1 遷移又不想改請求體的話，把路徑換成 `/aichat2/conversations` 即可，原本的 `references` 用法照常運作。 +因此只想從 v1 遷移又不想改請求體的話，把路徑換成 `/aichat2/conversations` 即可，原 `references` 用法照常運作。 -需要更精細控制（例如把多張圖片放在文字之間、或是順序很重要）就直接使用 `message` 陣列。 +需要更精細控制（比如把多張圖片放在文字之間、或者順序很重要）就直接用 `message` 陣列。 ## 工具呼叫與 MCP -v2 的核心增強點是模型可以自主呼叫工具完成多步任務，**這是預設開啟的**，不需要用戶端在請求裡做任何額外設定。常見情境： +v2 的核心增強點是模型可以自主呼叫工具完成多步任務，**這是預設開啟的**，不需要用戶端在請求裡做任何額外設定。常見場景： -- 使用者問「幫我搜尋一下最近上海有什麼新展覽」→ 模型呼叫內建 web search → 把結果整理成回答。 +- 使用者問「幫我搜一下最近上海有什麼新展覽」→ 模型呼叫內建 web search → 把結果整理成回答。 - 使用者問「讀一下這個 PDF 然後寫個摘要」→ 模型呼叫 file_read → 寫摘要。 - 使用者已在 [Connections](https://platform.acedata.cloud/connections) 裡授權了 Google Drive / GitHub / Notion 等 → 模型可呼叫對應的 MCP 工具讀寫其資料。 在 NDJSON / SSE 串流裡，工具呼叫透過 `tool_use` 和 `tool_result` 兩類事件呈現，例如： ```json -{"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展览"},"id":"f2f4b3e8-..."} +{"type":"tool_use","tool_id":"toolu_01ABCDEF","tool_name":"web_search","input":{"query":"上海 2026 春季展覽"},"id":"f2f4b3e8-..."} {"type":"tool_result","tool_id":"toolu_01ABCDEF","output":"...","is_error":false,"id":"f2f4b3e8-..."} {"type":"text_delta","content":"目前","delta_answer":"目前","id":"f2f4b3e8-..."} {"type":"text_delta","content":"上海","delta_answer":"上海","id":"f2f4b3e8-..."} ... ``` -如果你不想在前端顯示工具呼叫細節，忽略 `tool_use` / `tool_result` / `card` / `citation` 這幾類事件即可，模型最終輸出依然會透過 `text_delta` 串流輸出。 +如果你不想在前端展示工具呼叫細節，忽略 `tool_use` / `tool_result` / `card` / `citation` 這幾類事件即可，模型最終輸出依然透過 `text_delta` 串流輸出。 -`max_turns` 可以限制本次請求裡模型最多自行呼叫工具幾輪，預設上限由平台決定。把它設小（例如 `max_turns: 1`）可以強制單次回答、不允許任何工具呼叫。 +`max_turns` 可以限制本次請求裡模型最多自行呼叫工具幾輪，範圍為 1–500，省略時預設 500。把它設小（比如 `max_turns: 1`）可以強制單次回答、不允許任何工具呼叫。 ## 非同步執行與無人值守授權 -如果你的呼叫來自告警 Webhook、CI/CD、監控系統或其他後台任務，可以設定 `async: true` 讓介面立即返回任務 ID，後台繼續執行： +如果你的呼叫來自告警 Webhook、CI/CD、監控系統或其他背景任務，可以設定 `async: true` 讓介面立即返回任務 ID，背景繼續執行： ```json { "model": "gpt-5.5", "async": true, - "question": "我的服務報警了，用個人微信通知微信群「AceDataCloud團隊」……" + "question": "我的服務告警了，用個人微信通知微信群「AceDataCloud團隊」……" } ``` @@ -328,9 +328,9 @@ v2 的核心增強點是模型可以自主呼叫工具完成多步任務，**這 } ``` -之後可使用 `action: retrieve` + `id` 查詢會話結果；也可以提供 `callback_url`，任務完成後平台會把 `{ status, answer, usage, error }` POST 到你的回呼位址。`callback_url` 必須使用 `http` / `https`，且不能直接填寫 `localhost` 或私有 IP 字面位址。 +之後可用 `action: retrieve` + `id` 查詢會話結果；也可以提供 `callback_url`，任務完成後平台會把 `{ status, answer, usage, error }` POST 到你的回呼地址。`callback_url` 必須使用 `http` / `https`，且不能直接填寫 `localhost` 或私有 IP 字面位址。 -後台任務通常沒有人能點擊確認。如果你希望某些 Skill 或 MCP Server 在無人值守模式下執行傳送、發布、寫入等動作，請在請求體裡明確傳入預授權清單： +背景任務通常沒有人能點擊確認。如果你希望某些 Skill 或 MCP Server 在無人值守模式下執行發送、發布、寫入等動作，請在請求體裡明確傳入預授權清單： ```json { @@ -338,13 +338,13 @@ v2 的核心增強點是模型可以自主呼叫工具完成多步任務，**這 "async": true, "allowed_skills": ["acedatacloud/personal-wechat"], "allowed_mcp_servers": [], - "question": "我的服務報警了，用個人微信通知微信群「AceDataCloud團隊」……" + "question": "我的服務告警了，用個人微信通知微信群「AceDataCloud團隊」……" } ``` `allowed_skills` 裡的值是已連線 Skill 的 slug；`allowed_mcp_servers` 裡的值是已連線 MCP Server 的 slug。未列入預授權的 Skill / MCP Server 在無人值守模式下仍只能預覽、dry-run 或拒絕執行寫入操作。 -如果需要更細緻的控制，也可以使用等價的 `unattended_policy` 物件： +如果需要更細的控制，也可以使用等價的 `unattended_policy` 物件： ```json { @@ -358,24 +358,24 @@ v2 的核心增強點是模型可以自主呼叫工具完成多步任務，**這 預授權就是這兩個清單本身：清單為空即不授權任何能力，無需額外的開關欄位。 -注意：預授權只代表「本次請求允許這些能力在無人值守模式下略過人工確認」。具體 Skill 仍必須支援 `--unattended-confirm` 或對應的安全機制；否則它會繼續 dry-run，不會直接執行寫入操作。 +注意：預授權只代表「本次請求允許這些能力在無人值守模式下跳過人工確認」。具體 Skill 仍必須支援 `--unattended-confirm` 或對應的安全機制；否則它會繼續 dry-run，不會直接執行寫入操作。 ## 恢復暫停的對話 -某些工具會讓模型「反問使用者」，模型這時會發出一個 `ask_user_question` 事件，對話會凍結在 `awaiting_user_input` 狀態： +某些工具會讓模型「反問使用者」，模型這時會發出一個 `ask_user_question` 事件，對話被凍結在 `awaiting_user_input` 狀態： ```json { "type": "ask_user_question", "tool_id": "toolu_01XYZW", "tool_name": "ask_user_question", - "question": "你希望生成的报告是中文还是英文？", + "question": "你希望生成的報告是中文還是英文？", "options": ["中文", "英文"], "id": "f2f4b3e8-..." } ``` -在前端把這個事件渲染成卡片讓使用者選擇答案，然後使用相同的 `id` 發起下一次請求，把答案透過 `tool_results` 回填： +在前端把這個事件渲染成卡片讓使用者選答案，然後用同一個 `id` 發起下一次請求，把答案透過 `tool_results` 回填： ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ @@ -395,15 +395,15 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -請求體中的 `tool_use_id` **必須**和暫停時的 `tool_id` 完全一致；不一致會返回 400。當請求裡同時存在 `tool_results` 時，`question` / `message` / `references` 都會被忽略。 +請求體中 `tool_use_id` **必須**和暫停時的 `tool_id` 完全一致；不一致會返回 400。當請求裡同時存在 `tool_results` 時，`question` / `message` / `references` 都會被忽略。 -如果使用者決定放棄這個問題，直接傳入一個新的 `question` / `message` 即可，平台會自動把暫停的工具呼叫標記為「使用者略過」。 +如果使用者決定放棄這個問題，直接傳一個新的 `question` / `message` 即可，平台會自動把暫停的工具呼叫標記為「使用者跳過」。 ## 會話管理（CRUD） -v2 在同一個 endpoint 上透過 `action` 欄位提供輕量級會話管理，無需另外開設 API。 +v2 在同一個 endpoint 上透過 `action` 欄位提供輕量級會話管理，無需另外開 API。 +### `action: retrieve` —— 擷取一個對話 -### `action: retrieve` —— 取得一個會話 ```shell curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ -H 'accept: application/json' \ @@ -415,7 +415,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ }' ``` -回傳完整的對話文件（包含 `messages` 歷史紀錄、`model`、`title`、`tools_used` 等）。 +回傳完整的對話文件（包含 `messages` 歷史、`model`、`title`、`tools_used` 等）。 ### `action: retrieve_batch` —— 列出對話摘要 @@ -428,11 +428,11 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -回傳 `{ items: [...], total }`。**摘要不包含 `messages`**，適合用於側邊欄清單；如果使用者點開某一筆對話，再使用 `action: retrieve` 個別取得其完整訊息。 +回傳 `{ items: [...], total }`。**摘要不包含 `messages`**，適合用來做側邊欄列表；如果使用者點開某則對話，再使用 `action: retrieve` 單獨擷取它的完整訊息。 可選篩選參數：`user_id`、`application_id`、`model_group`、`model`。 -### `action: update` —— 修改標題或覆寫歷史紀錄 +### `action: update` —— 修改標題或重寫歷史 ```json { @@ -442,7 +442,7 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ } ``` -也可以傳送 `messages`，但伺服器端會進行嚴格的 schema 驗證（必須是摺疊後的 `ToolUseContent` 形式），不符合時會回傳 400。一般只建議用來修改 `title`。 +`messages` 也可以傳入，但伺服器端會進行嚴格的 schema 驗證（必須是摺疊後的 `ToolUseContent` 形式），不符合會回傳 400。一般只建議用來修改 `title`。 ### `action: delete` —— 刪除一個對話 @@ -457,13 +457,13 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ ## 從 v1 平滑遷移 -如果你已經在使用 [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations)，遷移至 v2 幾乎不需要修改程式碼： +如果你已經在使用 [`/aichat/conversations`](https://platform.acedata.cloud/documents/aichat-conversations)，遷移到 v2 幾乎不需要修改程式碼： 1. 將 URL 從 `https://api.acedata.cloud/aichat/conversations` 改為 `https://api.acedata.cloud/aichat2/conversations`。 -2. 如果你先前傳送的是 v1 模型名稱（如 `gpt-3.5`、`gpt-4-browsing` 等），切換至 v2 時建議升級至當代模型（如 `gpt-5.4`、`claude-opus-4-8`、`gemini-3.1-pro-preview` 等）。 -3. NDJSON 串流的欄位保持向後相容：每個 `text_delta` 事件仍帶有 `delta_answer` 與 `id`，因此原本按行解析 `delta_answer` 的用戶端無需修改。 +2. 如果你之前傳入的是 v1 模型名稱（如 `gpt-3.5`、`gpt-4-browsing` 等），切換到 v2 時建議升級到當代模型（如 `gpt-5.4`、`claude-opus-4-8`、`gemini-3.1-pro-preview` 等）。 +3. NDJSON 串流的欄位保持向後相容：每個 `text_delta` 事件依然帶有 `delta_answer` 與 `id`，因此原本按行解析 `delta_answer` 的客戶端無需修改。 -遷移後可依需求啟用 v2 的新功能（多模態 `message`、SSE、工具呼叫、`action` CRUD），依照節奏推進即可。 +遷移之後可以視需要啟用 v2 的新功能（多模態 `message`、SSE、工具呼叫、`action` CRUD），按節奏推進即可。 ## 錯誤處理 @@ -481,14 +481,14 @@ curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \ 常見錯誤： -- `400 bad_request`：缺少必填欄位、`tool_use_id` 不相符、`messages` schema 不合法等。 +- `400 bad_request`：缺少必填欄位、`tool_use_id` 不匹配、`messages` schema 不合法等。 - `401 invalid_token`：`authorization` 標頭不正確。 - `404 not_found`：執行 `action: retrieve / update / delete` 時，`id` 對應的對話不存在。 - `429 too_many_requests`：觸發了速率限制。 -- `500 chat_error`：上游 LLM 發生錯誤，或本輪 `completion_tokens=0`（視為未消費處理，不會扣費）。 +- `500 chat_error`：上游 LLM 回報錯誤或本輪 `completion_tokens=0`（視為未消費處理，不會扣費）。 -在串流回應中，錯誤會以 `{"type":"error","message":"..."}` 事件發出，隨後串流便會結束。 +在串流回應中，錯誤會以 `{"type":"error","message":"..."}` 事件發出，緊接著串流就會結束。 ## 結論 -AI Chat v2 API 在向後相容 v1 的同時，將對話從「單輪 / 多輪問答」升級為「Agent 化的可觀測對話」：多模態輸入、工具呼叫、可暫停 / 可恢復、串流結構化事件、內建 CRUD。建議新接入直接使用 v2；既有 v1 整合可分階段平滑遷移。如有任何問題，請隨時聯絡我們的技術支援團隊。 +AI Chat v2 API 在向後相容 v1 的同時，將對話從「單輪 / 多輪問答」升級為「Agent 化的可觀測對話」：多模態輸入、工具呼叫、可暫停 / 可恢復、串流結構化事件、內建 CRUD。建議新接入直接使用 v2；已有 v1 整合可以分階段平滑遷移。如有任何問題，請隨時聯絡我們的技術支援團隊。 diff --git a/zh-Hant/guides/platform/hermes_managed.mdx b/zh-Hant/guides/platform/hermes_managed.mdx index 5463750da..178d3ccc0 100644 --- a/zh-Hant/guides/platform/hermes_managed.mdx +++ b/zh-Hant/guides/platform/hermes_managed.mdx @@ -1,18 +1,44 @@ --- -title: "Hermes Agent 私有部署" +title: "Hermes 部署" description: "Platform 整合指南 - Ace Data Cloud" --- -Ace Data Cloud 提供 Hermes Agent 私有部署入口。该入口为受控服务，是否可用及可选资源以控制台当前显示为准。 +為每個 Application 建立獨立 Hermes 容器實例。預設使用固定發行版本的基礎映像，保留原生功能；平台提供購買、續費、持久化儲存與部署管理。 -## 使用步骤 +## 建立與購買 -1. 在平台找到 **Hermes Agent 私有部署**。 -2. 按页面提示选择可用配置并创建服务。 -3. 等待平台显示就绪状态。 -4. 使用页面提供的入口和凭据访问实例。 -5. 先发送 `Reply only OK`，再开始真实任务。 +1. 開啟 [Hermes 部署](https://platform.acedata.cloud/services/hermes) 並建立 Application。 +2. 在購買頁選擇時長方案，完成付款。 +3. 返回設定頁，可從下拉列表選擇平台聊天模型，並查看目前模型價格。平台會為這個實例建立獨立 API 憑據；也可關閉平台接入，在原生控制台自行設定。 +4. 選擇自動產生存取憑據，或設定自己的強密碼/Token，確認後開始部署。存取憑據與模型 API 憑據互相獨立。 +5. 實例就緒後，從管理頁取得存取網址與登入憑據。 +6. 登入原生控制台，設定自己的模型供應商、金鑰和渠道。 -模型、凭据、存储和删除行为以创建页面及确认弹窗为准；不要把本地 Hermes 教程中的 YAML 直接当作平台部署合同。删除前先导出需要保留的数据。 +部署費按方案時長計費，具體美元價格、時長以購買頁為準。模型呼叫費用另計；購買部署時長不會贈送模型額度。啟用平台接入時，專用 API 憑據僅開放所選模型對應的聊天介面，呼叫從你的平台餘額另外計費。每個 Application 分別購買、續費和管理。 -如果控制台未显示创建入口，说明当前账户暂未开放该服务，可改用 [Hermes 交互向导](https://platform.acedata.cloud/documents/hermes-wizard-integration) 或 [手动配置](https://platform.acedata.cloud/documents/hermes-manual-integration)。 +## 密碼、憑據與後續設定 + +存取憑據會在首次啟動前設定。自動產生方式使用隨機憑據，自訂密碼至少 16 個字元，OpenClaw Token 至少 32 個字元。草稿不儲存密碼；切換頁面後可能需要重新輸入。部署後，只有 Application 擁有者和管理員能查看存取憑據。 + +每個實例的模型 API 憑據互不共用，隨部署續費延長有效期，刪除實例時撤銷。部署初始化後，請在原生控制台修改模型和渠道；如果改選其他服務的模型，請先在平台憑據管理中調整對應介面授權，或使用相應憑據。一般重新部署不會覆蓋原生設定。未經發布驗證的部署環境會暫時拒絕新部署，請聯絡支援。 + +## 版本與資料 + +設定頁顯示目前發布的映像版本。新建實例使用服務目前發布版本；現有實例不會隨目錄更新自動替換。重新部署會套用目前服務版本，請先備份，確認所用版本的升級要求。 + +每個實例預設提供 1 CPU、2 GiB 記憶體上限和 10 GiB 持久化儲存。重新啟動會保留實例資料。主動刪除部署或到期回收會刪除儲存，請提前匯出需要保留的資料。 + +## 續費與到期 + +在目前 Application 的購買頁續費，有效期按平台現有時長規則延長。到期後存取入口暫停，寬限期內續費可恢復存取；超過寬限期會回收實例與資料。以管理頁的到期時間、計費狀態及刪除提示為準。 + +## 登入管理介面 + +在部署管理頁複製 Dashboard 網址、使用者名稱 `admin` 和密碼，開啟後登入。登入資訊僅向該 Application 的擁有者和平台管理員提供。模型、技能與渠道在 Hermes 原生介面中設定。 + +## 常見問題 + +- **為什麼新實例還不能回答？** 部署完成表示容器就緒；需要在原生介面設定模型和憑據才能開始使用。 +- **是否預裝額外外掛或模型 fallback？** 預設不添加，按需要在原生介面設定。 +- **已有實例怎麼更新？** 原有 Application 和訂單保留，重新部署時使用目前服務版本；升級前先備份資料並檢查版本相容性。 +- **啟動失敗怎麼辦？** 先查看部署日誌與事件，確認實例就緒後再設定模型。不要在公開評論或截圖中暴露實例密碼和金鑰。 diff --git a/zh-Hant/guides/platform/wework_bot.mdx b/zh-Hant/guides/platform/wework_bot.mdx deleted file mode 100644 index d04b41f47..000000000 --- a/zh-Hant/guides/platform/wework_bot.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -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 小時不再鎖定視窗，不代表已經消除偵測，也不代表實例可以保證長期無人值守。