copilot for openbb
1.0.0
مرحبًا بك في مستودع الأمثلة لدمج مساعدي الطيارين المخصصين في OpenBB Terminal.
يوفر هذا المستودع كل ما تحتاجه لإنشاء نماذجك التجريبية المخصصة وإضافتها إلى OpenBB Copilot.
فيما يلي بعض الأسباب الشائعة التي قد تدفعك إلى إنشاء مساعد طيار خاص بك:
لدمج مساعد طيار مخصص يمكنك التفاعل معه من OpenBB Terminal، ستحتاج إلى إنشاء واجهة برمجة تطبيقات خلفية يمكن للمحطة الطرفية تقديم طلبات إليها.
سوف تستجيب واجهة برمجة التطبيقات المخصصة لمساعد الطيار مع الأحداث المرسلة من الخادم (SSEs).
ملاحظة: إذا كنت تتطلع إلى البدء سريعًا، نقترح تشغيل أحد أمثلة الطيارين المساعدين المضمنة كجزء من هذا المستودع، وإضافته كمساعد طيار مخصص إلى OpenBB Terminal (يتضمن كل مثال مساعد طيار تعليمات حول كيفية تشغيلها). يعد استنساخ نموذج مساعد الطيار وتعديله طريقة رائعة لإنشاء مساعد طيار مخصص.
المفهوم الأكثر أهمية الذي يجب فهمه هو أن بروتوكول مساعد الطيار عديم الحالة . هذا يعني أن كل طلب من OpenBB Terminal إلى مساعد الطيار الخاص بك سيتضمن جميع الرسائل السابقة (مثل عمليات إكمال الذكاء الاصطناعي والرسائل البشرية واستدعاءات الوظائف ونتائج استدعاءات الوظائف) في حمولة الطلب.
هذا يعني أنه ليس من الضروري أن يحافظ مساعد الطيار المخصص على أي حالة بين الطلبات. يجب عليه ببساطة استخدام حمولة الطلب لإنشاء استجابة.
OpenBB Terminal هو المسؤول الوحيد عن الحفاظ على حالة المحادثة، وسيقوم بإلحاق الردود بمصفوفة messages في حمولة الطلب.
ستقوم OpenBB Terminal بتقديم طلبات POST إلى نقطة نهاية query المحددة في ملف copilots.json الخاص بك (المزيد حول هذا لاحقًا). ستحتوي حمولة هذا الطلب على بيانات مثل رسائل المحادثة الحالية، وأي سياق مضاف بشكل صريح، ومعلومات حول الأدوات الموجودة على لوحة المعلومات النشطة حاليًا، وعناوين URL المطلوب استردادها، وما إلى ذلك.
جوهر مخطط طلب الاستعلام الذي يجب عليك تنفيذه هو كما يلي:
{
"messages" : [ # <-- the chat messages between the user and the copilot (including function calls and results)
{
"role" : "human" , # <-- each message has a role: "human", "ai", or "tool"
"content" : "Hi there." # <-- the content of the message
}
],
"context" : [ # <-- explicitly added context by the user (optional)
{
"uuid" : "3fa85f64-5717-4562-b3fc-2c963f66afa6" , # <-- the UUID of the widget
"name" : "<widget name>" , # <-- the name of the widget
"description" : "<widget description>" , # <-- the description of the widget
"data" : {
"content" : "<data>" # <-- the data of the widget
},
"metadata" : {
"<metadata key>" : "<metadata value>" , # <-- the metadata of the widget
...
}
},
...
],
"widgets" : [ # <-- the widgets currently visible on the active dashboard on Terminal Pro (optional)
{
"uuid" : "3fa85f64-5717-4562-b3fc-2c963f66afa6" , # <-- the UUID of the widget
"name" : "<widget name>" , # <-- the name of the widget
"description" : "<widget description>" , # <-- the description of the widget
"metadata" : {
"<metadata key>" : "<metadata value>" , # <-- the metadata of the widget
...
}
},
...
],
}سنتناول كل حقل من هذه الحقول بمزيد من التفاصيل أدناه.
messages هذه هي قائمة الرسائل بين المستخدم ومساعد الطيار. يتضمن ذلك رسائل المستخدم ورسائل مساعد الطيار واستدعاءات الوظائف ونتائج استدعاءات الوظائف. كل رسالة لها role content .
أبسط مثال هو عندما لا يتضمن الأمر استدعاء دالة، والذي يتكون ببساطة من مجموعة من الرسائل human ورسائل ai .
يقوم OpenBB Terminal تلقائيًا بإلحاق جميع رسائل ai المرتجعة (من Copilot الخاص بك) إلى مجموعة messages الخاصة بأي طلب متابعة.
# Only one human message
{
"messages" : [
{
"role" : "human" ,
"content" : "Hi there."
}
],
...
} # Multiple messages
{
"messages" : [
{
"role" : "human" ,
"content" : "Hi there."
},
{
"role" : "ai" ,
"content" : "Hi there, I'm a copilot. How are you?"
},
{
"role" : "human" ,
"content" : "I'm fine, thank you. What is the weather in Tokyo?"
}
],
...
} يتم أيضًا تضمين استدعاءات الوظائف إلى Terminal Pro (كما هو الحال عند استرداد بيانات عنصر واجهة المستخدم)، بالإضافة إلى نتائج استدعاءات الوظائف هذه (التي تحتوي على بيانات عنصر واجهة المستخدم) في مصفوفة messages . للحصول على معلومات حول استدعاء الوظائف، راجع قسم "استدعاء الوظائف" أدناه.
contextهذه مجموعة اختيارية من بيانات عناصر واجهة المستخدم التي سيتم إرسالها بواسطة OpenBB Terminal عندما تتم إضافة عناصر واجهة المستخدم كسياق بشكل صريح من قبل المستخدم. يحدث هذا عندما ينقر المستخدم على الزر "إضافة كسياق" الموجود على عنصر واجهة المستخدم في OpenBB Terminal.
يعمل حقل context على النحو التالي:
{
...
" context ": [
{
"uuid" : "3fa85f64-5717-4562-b3fc-2c963f66afa6" , # <-- each widget has a UUID
"name" : "Analyst Estimates" ,
"description" : "Contains analyst estimates for a ticker" ,
"data" : {
"content" : "<data>" # <-- the data of the widget could either be a JSON string or plaintext (you must choose how to handle this in your copilot)
},
"metadata" : { # <-- additional metadata about the widget
"symbol" : "AAPL" ,
"period" : "quarter" ,
"source" : "Financial Modelling Prep" ,
"lastUpdated" : 1728998071322
}
},
{
"uuid" : "8b2e5f79-3a1d-4c9e-b6f8-1e7d2a9c0b3d" , # <-- the context can have multiple widgets
"name" : "Earnings Transcripts" ,
"description" : "Contains earnings transcripts for a ticker" ,
"data" : {
"content" : "<data>" # <-- the data of the widget
},
"metadata" : {
"symbol" : "AAPL" ,
"period" : "quarter" ,
"source" : "Intrinio" ,
"lastUpdated" : 1728998071322
}
},
...
],
...
}widgetsهذه عبارة عن مجموعة من الأدوات التي تظهر حاليًا على لوحة المعلومات النشطة في Terminal Pro. * يعد هذا مفيدًا فقط إذا كنت تخطط لتنفيذ استدعاء الوظائف في مساعد الطيار المخصص لديك (وهو أمر موصى به، ولكنه غير مطلوب)، والذي يسمح له بطلب بيانات عنصر واجهة المستخدم من لوحة المعلومات النشطة حاليًا للمستخدم على OpenBB Terminal.
{
...
" widgets ": [
{
"uuid" : "c276369e-e469-4689-b5fe-3f8c76f7c45a" ,
"name" : "Stock Price Quote Widget" ,
"description" : "Contains the current stock price of a ticker" ,
"metadata" : {
"ticker" : "AAPL"
}
},
{
"uuid" : "9f8e7d6c-5b4a-3c2e-1d0f-9e8d7c6b5a4b" ,
"name" : "Financial Ratios Widget" ,
"description" : "Displays key financial ratios for a company" ,
"metadata" : {
"ticker" : "AAPL" ,
"period" : "TTM"
}
},
...
],
...
}يجب أن يستجيب مساعد الطيار المخصص لطلب OpenBB Terminal باستخدام الأحداث المرسلة من الخادم (SSEs).
يمكن لـ OpenBB Terminal معالجة SSEs التالية:
copilotMessageChunk : يستخدم لإعادة الرموز المميزة المتدفقة (الاستجابات الجزئية) إلى محطة OpenBB. يمكن دفق هذه الاستجابات عند إنشائها.copilotFunctionCall : يُستخدم لطلب البيانات (على سبيل المثال، بيانات عنصر واجهة المستخدم) أو تنفيذ وظيفة محددة. يؤدي هذا إلى توجيه Terminal Pro لاتخاذ مزيد من الإجراءات من جانب العميل. يعد هذا ضروريًا فقط إذا كنت تخطط لتنفيذ استدعاء الوظيفة في مساعد الطيار المخصص لديك. copilotMessageChunkتحتوي مجموعة الرسالة SSE على التنسيق التالي:
event: copilotMessageChunk
data: {"delta":"H"} # <-- the `data` field must be a JSON object.
يجب أن تكون delta عبارة عن سلسلة، ولكن يمكن أن تكون بأي طول. نقترح إعادة بث كل جزء تتلقاه من LLM الخاص بك بمجرد إنشائه كـ delta .
على سبيل المثال، إذا كنت تريد إعادة بث الرسالة "مرحبًا!"، فيمكنك إرسال SSEs التالية:
event: copilotMessageChunk
data: {"delta":"H"}
event: copilotMessageChunk
data: {"delta":"i"}
event: copilotMessageChunk
data: {"delta":"!"}
copilotFunctionCall (مطلوب فقط لاستدعاء الوظائف)استدعاء الوظيفة SSE له التنسيق التالي:
event: copilotFunctionCall
data: {"function":"get_widget_data","input_arguments":{"widget_uuid":"c276369e-e469-4689-b5fe-3f8c76f7c45a"}}
مرة أخرى، يجب أن يكون حقل data كائن JSON. حقل function هو اسم الوظيفة المطلوب استدعاؤها (حاليًا يتم دعم get_widget_data فقط)، وحقل input_arguments عبارة عن قاموس للوسائط التي سيتم تمريرها إلى الوظيفة. بالنسبة لوظيفة get_widget_data ، فإن الوسيطة الوحيدة المطلوبة هي widget_uuid ، وهو UUID الخاص بعنصر واجهة المستخدم لاسترداد البيانات (من أحد UUIDs في صفيف widgets للطلب).
من خلال إضافة وظيفة استدعاء إلى مساعد الطيار الخاص بك، سيكون قادرًا على طلب البيانات المرئية على لوحة معلومات المستخدم النشطة حاليًا في OpenBB Terminal.
يتم إرسال قائمة بجميع عناصر واجهة المستخدم المرئية حاليًا على لوحة معلومات المستخدم إلى مساعد الطيار الخاص بك في مصفوفة widgets الخاصة بحمولة الطلب.
لاسترداد البيانات من عنصر واجهة المستخدم، يجب أن يستجيب مساعد الطيار الخاص بك بحدث copilotFunctionCall ، مع تحديد UUID لعنصر واجهة المستخدم:
event: copilotFunctionCall
data: {"function":"get_widget_data","input_arguments":{"widget_uuid":"c276369e-e469-4689-b5fe-3f8c76f7c45a"}}
بعد إرسال حدث copilotFunctionCall ، يجب عليك إغلاق الاتصال وانتظار طلب استعلام جديد من OpenBB Terminal.
عند تلقي حدث copilotFunctionCall ، ستقوم OpenBB Terminal باسترداد البيانات وبدء طلب استعلام جديد . سيتضمن طلب الاستعلام الجديد هذا استدعاء الوظيفة الأصلية، بالإضافة إلى نتيجة استدعاء الوظيفة في مصفوفة messages .
{
...
" messages ": [
...
{
"role" : "ai" ,
"content" : "{ " function " : " get_widget_data " , " input_arguments " :{ " widget_uuid " : " c276369e-e469-4689-b5fe-3f8c76f7c45a " }}"
},
{
"role" : "tool" ,
"function" : "get_widget_data" ,
"data" : {
"content" : "<data>"
}
}
]
}لاحظ أن:
messages .content رسالة استدعاء الوظيفة ai هو كائن JSON مشفر حرفيًا لحقل data لحدث copilotFunctionCall (هذه آلية مفيدة جدًا لتهريب بيانات التعريف الإضافية المتعلقة باستدعاء الوظيفة، إذا كان مساعد الطيار الخاص بك يحتاج إليها). حاليًا، استدعاء الوظيفة الوحيد الذي تدعمه محطة OpenBB هو get_widget_data ، والذي يسترد البيانات من عنصر واجهة مستخدم محدد.
يتلقى مساعد الطيار المخصص الطلب التالي من محطة OpenBB:
{
"messages" : [
{
"role" : " human " ,
"content" : " What is the current stock price of AAPL? "
}
],
"widgets" : [
{
"uuid" : " 38181a68-9650-4940-84fb-a3f29c8869f3 " ,
"name" : " Historical Stock Price " ,
"description" : " Historical Stock Price " ,
"metadata" : {
"symbol" : " AAPL " ,
"source" : " Financial Modelling Prep " ,
"lastUpdated" : 1728994470324
}
}
]
}يمكنك بعد ذلك تحليل الاستجابة وتنسيق الرسائل إلى LLM الخاص بك (بما في ذلك المعلومات المتعلقة بالأدوات المتوفرة). لنفترض أن مساعد الطيار الخاص بك يحدد أنه يمكن الإجابة على استعلام المستخدم باستخدام الأداة المتاحة، ويقوم بإنشاء استدعاء دالة لاسترداد البيانات.
يستجيب مساعد الطيار الخاص بك بعد ذلك بـ SSE التالي ويغلق الاتصال:
event: copilotFunctionCall
data: {"function":"get_widget_data","input_arguments":{"widget_uuid":"38181a68-9650-4940-84fb-a3f29c8869f3"}}
ستقوم OpenBB Terminal بعد ذلك بتنفيذ الوظيفة المحددة، وتقديم طلب استعلام جديد إلى مساعد الطيار المخصص الخاص بك:
{
"messages" : [
{
"role" : "human" ,
"content" : "What is the current stock price of AAPL?"
},
{
"role" : "ai" ,
"content" : "{ " function " : " get_widget_data " , " input_arguments " :{ " widget_uuid " : " 38181a68-9650-4940-84fb-a3f29c8869f3 " }}"
},
{
"role" : "tool" ,
"function" : "get_widget_data" ,
"data" : {
"content" : "[{ " date " : " 2024-10-15T00:00:00-04:00 " , " open " :233.61, " high " :237.49, " low " :232.37, " close " :233.85, " volume " :61901688, " vwap " :234.33, " adj_close " :233.85, " change " :0.24, " change_percent " :0.0010274},{ " date " : " 2024-10-14T00:00:00-04:00 " , " open " :228.7, " high " :231.73, " low " :228.6, " close " :231.3, " volume " :39882100, " vwap " :230.0825, " adj_close " :231.3, " change " :2.6, " change_percent " :0.0114},{ " date " : " 2024-10-11T00:00:00-04:00 " , " open " :229.3, " high " :233.2, " low " :228.9, " close " :231.0, " volume " :32581944, " vwap " :231.0333, " adj_close " :231.0, " change " :1.7, " change_percent " :0.0074}, ... ]"
}
}
],
"widgets" : [
{
"uuid" : "38181a68-9650-4940-84fb-a3f29c8869f3" ,
"name" : "Historical Stock Price" ,
"description" : "Historical Stock Price" ,
"metadata" : {
"symbol" : "AAPL" ,
"source" : "Financial Modelling Prep" ,
"lastUpdated" : 1728994470324
}
}
} يمكنك بعد ذلك تحليل الاستجابة ومعالجة البيانات وتنسيق الرسائل إلى LLM الخاص بك. لنفترض أن LLM يقوم بعد ذلك بإنشاء سلسلة من الرموز المميزة للإجابة على استعلام المستخدم. يتم بعد ذلك دفقها مرة أخرى إلى المستخدم باستخدام برنامج copilotMessageChunk SSE:
event: copilotMessageChunk
data: {"delta":"The"}
event: copilotMessageChunk
data: {"delta":" current"}
event: copilotMessageChunk
data: {"delta":" stock"}
event: copilotMessageChunk
data: {"delta":" price"}
event: copilotMessageChunk
data: {"delta":" of"}
event: copilotMessageChunk
data: {"delta":" Apple"}
event: copilotMessageChunk
data: {"delta":" Inc."}
event: copilotMessageChunk
data: {"delta":" (AAPL)"}
event: copilotMessageChunk
data: {"delta":" is"}
event: copilotMessageChunk
data: {"delta":" $150.75."}
copilots.json ) لدمج مساعد الطيار المخصص الخاص بك مع OpenBB Terminal، تحتاج إلى تكوين ملف copilots.json وتقديمه. يحدد هذا الملف كيفية اتصال مساعد الطيار المخصص الخاص بك بالواجهة الأمامية، بما في ذلك الميزات التي يدعمها مساعد الطيار المخصص الخاص بك، والمكان الذي يجب إرسال الطلبات فيه.
فيما يلي مثال لتكوين copilots.json:
{
"example_copilot" : { # <-- the ID of your copilot
"name" : "Mistral Example Co. Copilot" , # <-- the display name of your copilot
"description" : "AI-powered financial copilot that uses Mistral Large as its LLM." , # <-- a short description of your copilot
"image" : "<url>" , # <-- a URL to an image icon for your copilot
"hasStreaming" : true , # <-- whether your copilot supports streaming responses via SSEs. This must always be true.
"hasFunctionCalling" : true , # <-- whether your copilot supports function calling
"endpoints" : {
"query" : "<url>" # <-- the URL that Terminal Pro will send requests to. For example, "http://localhost:7777/v1/query"
}
}
} يجب تقديم ملف copilots.json الخاص بك على <your-host>/copilots.json ، على سبيل المثال، http://localhost:7777/copilots.json .
