Βήμα-προς-βήμα οδηγός: προσθήκη προσαρμοσμένων συναρτήσεων ΤΝ στον βοηθό ΤΝ του ONLYOFFICE

Με τον νέο μας έξυπνο πράκτορα AI, παρέχουμε εργαλεία αιχμής για να ανταποκριθούμε στις απαιτήσεις του σημερινού ταχέως μεταβαλλόμενου ψηφιακού κόσμου. Ως έργο ανοιχτού κώδικα, καλωσορίζουμε τις καινοτομίες που προωθούν οι χρήστες. Σε αυτήν την ανάρτηση, θα σας δείξουμε πώς να προσθέσετε προσαρμοσμένες συναρτήσεις στον AI agent, ώστε να κάνετε την εργασία σας με έγγραφα ταχύτερη, ευκολότερη και πιο βολική.

Τι είναι οι συναρτήσεις ΤΝ και για τι χρησιμεύουν;

Οι συναρτήσεις ΤΝ είναι τα βασικά δομικά στοιχεία της λειτουργικότητας ενός πράκτορα ΤΝ. Ουσιαστικά, είναι οδηγίες που λένε στον πράκτορα ΤΝ:

• Ποιο αίτημα να στείλετε στο μοντέλο τεχνητής νοημοσύνης.
• Ποιες επεξεργασίες να εκτελεστούν στο έγγραφό σας.

Χρησιμοποιώντας συναρτήσεις ΤΝ, μπορείτε να επεκτείνετε και να ελέγξετε τον τρόπο με τον οποίο η ΤΝ αλληλεπιδρά με το περιεχόμενο του εγγράφου σας.

Πώς να χρησιμοποιήσετε μια συνάρτηση ΤΝ

1. Προσθέστε ένα μοντέλο της επιλογής σας στο πρόσθετο ΤΝ.
2. Ανοίξτε το παράθυρο διαλόγου πράκτορα ΤΝ πατώντας CTRL + /.
3. Πληκτρολογήστε την εντολή σας και πατήστε Enter.

Παράδειγμα: η συνάρτηση commentText

Η συνάρτηση commentText σας επιτρέπει να προσθέτετε σχόλια που δημιουργήθηκαν από ΤΝ απευθείας στο έγγραφό σας. Δείτε πώς λειτουργεί:

• Επιλέξτε μια λέξη για την οποία θέλετε να αφήσετε σχόλιο
• Ανοίξτε το παράθυρο διαλόγου πράκτορα ΤΝ (CTRL + /).
• Πληκτρολογήστε την οδηγία σας, για παράδειγμα: “Εξήγησε αυτό το κείμενο.”
• Πατήστε Enter.

Ο πράκτορας ΤΝ θα εκτελέσει τη συνάρτηση commentText και θα εισαγάγει σχετικά σχόλια στο έγγραφό σας:

Γιατί να προσθέσετε προσαρμοσμένες συναρτήσεις στον πράκτορα ΤΝ σας;

Η προσθήκη προσαρμοσμένων συναρτήσεων ΤΝ σας επιτρέπει να επεκτείνετε τις δυνατότητες του έξυπνου πράκτορα ΤΝ και να τον προσαρμόσετε ακριβώς στις ανάγκες σας. Είτε δουλεύετε με έγγραφα, υπολογιστικά φύλλα ή παρουσιάσεις, η ευελιξία του πράκτορα, σε συνδυασμό με τη δύναμη των μοντέρνων μοντέλων ΤΝ, σας βοηθά να μετατρέψετε τις ιδέες σας σε πραγματικότητα και να τις ενσωματώσετε απρόσκοπτα στη ροή εργασίας σας.

Γενική λογική προσθήκης προσαρμοσμένης συνάρτησης ΤΝ

Η διαδικασία προσθήκης μιας προσαρμοσμένης συνάρτησης περιλαμβάνει δύο κύριες φάσεις:

• Εγγραφή συνάρτησης – Καταχωρεί τη συνάρτηση ΤΝ και τα μεταδεδομένα της στο περιβάλλον του πράκτορα.
• Εκτέλεση συνάρτησης – Υλοποιεί τον βασικό λογισμό, που περιλαμβάνει την αποστολή αιτημάτων στο μοντέλο ΤΝ και το χειρισμό του περιεχομένου του εγγράφου χρησιμοποιώντας το Office API μας.

Τώρα ας ρίξουμε μια πιο προσεκτική ματιά σε αυτές τις φάσεις.

Εγγραφή συνάρτησης

Για να προσθέσουμε μια νέα συνάρτηση, υλοποιούμε το αντικείμενο RegisteredFunction. Μας επιτρέπει να προσθέσουμε μεταδεδομένα και λογική. Εδώ είναι ένα παράδειγμα προσθήκης της συνάρτησης commentText για τον Επεξεργαστή Εγγράφων:

let func = new RegisteredFunction();
        func.name = "commentText";
        func.params = [
            "type (string): whether to add as a 'comment' or as a 'footnote'    default is 'comment')"
        ];


        func.examples = [
            "If you need to explain selected text as a comment, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"comment\"}",


            "If you need to add a footnote to selected text, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Add a footnote to this text\", \"type\": \"footnote\"}",


            "If you need to comment selected text, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Comment this text\"}",


            "If you need to explain selected text as a footnote, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"footnote\"}"
     ]

Όπου:

• func.name: το όνομα που η ΤΝ θα χρησιμοποιήσει για να καλέσει αυτή τη συνάρτηση (π.χ., “commentText”).
• func.params: μια λίστα παραμέτρων που η συνάρτηση αναμένει από την ΤΝ. Για παράδειγμα:

– prompt (string): μια περιγραφή ή οδηγία για το σχόλιο.

– type (string): “comment” ή “footnote” — καθορίζει τι να εισαχθεί.

• func.examples: παραδείγματα σωστών κλήσεων συνάρτησης για την ΤΝ.
• func.description: εξηγεί στην ΤΝ για τι χρησιμεύει η συνάρτηση.

Αυτές οι παράμετροι χρησιμοποιούνται από την ΤΝ. Το αντικείμενο RegisteredFunction() ορίζεται στο αρχείο helperFunc.js.

Λογική εκτέλεσης συνάρτησης

Μετά την εγγραφή της συνάρτησης, υλοποιούμε τον πραγματικό λογισμό που εκτελείται όταν το AI καλεί αυτή τη συνάρτηση.

• Ανάκτηση του επιλεγμένου κειμένου χρησιμοποιώντας το Asc.Editor.callCommand().

func.call = async function(params) {
            let type = params.type;
            let isFootnote = "footnote" === type;


// Executes a block of code inside the editor's context using the office=js API.
            let text = await Asc.Editor.callCommand(function(){
                let doc = Api.GetDocument();
// Gets the current selected text range.
                let range = doc.GetRangeBySelect();
                let text = range ? range.GetText() : "";
                if (!text)
                {
                    text = doc.GetCurrentWord();
// Selects the current word so comments can be applied to it.
                    doc.SelectCurrentWord();
                }


                return text;
            });

• Κατασκευή της εντολής για την ΤΝ συνδυάζοντας το params.prompt και το επιλεγμένο κείμενο.

let argPromt = params.prompt + ":\n" + text;

• Προετοιμασία του αντικειμένου AI.Request.create χρησιμοποιώντας το AI.Request.create. Το αντικείμενο ορίζεται στο αρχείο engine.js. Αυτό το αντικείμενο διευκολύνει την αποστολή ενός αιτήματος στο μοντέλο ΤΝ.

// Initializes a request engine for communicating with the AI model (e.g. Chat, Translation).
            let requestEngine = AI.Request.create(AI.ActionType.Chat);
            if (!requestEngine)
                return;

• Αποστολή του αιτήματος χρησιμοποιώντας το chatRequest() και λήψη του αποτελέσματος σε μια callback.

// Sends a prompt to the AI model and processes the response via callback. Can stream or wait.
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;

• Εισαγωγή της απάντησης ως σχόλιο ή υποσημείωση χρησιμοποιώντας το AddFootnote() ή το AddComment()

Υλοποίηση AddFootnote:

if (isFootnote)
            {
                let addFootnote = true;
// Sends a prompt to the AI model and processes the response via callback. Can stream or wait.
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;


// Marks the end of a logical group or block action in the editor.
                    await checkEndAction();
                    Asc.scope.data = data;
                    Asc.scope.model = requestEngine.modelUI.name;


                    if (addFootnote)
                    {
// Executes a block of code inside the editor's context using the document model API.
                        await Asc.Editor.callCommand(function(){
// Returns the main document object, which gives access to all editing, structure, and selection APIs.
                            Api.GetDocument().AddFootnote();
                        });
                        addFootnote = false;
                    }
// Inserts the AI-generated result into the document at the current selection or cursor.
                    await Asc.Library.PasteText(data);
                });

Υλοποίηση AddComment:

let commentId = null;
// Sends a prompt to the AI model and processes the response via callback. Can stream or wait.
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;


// Marks the end of a logical group or block action in the editor.
                    await checkEndAction();
                    Asc.scope.data = data;
                    Asc.scope.model = requestEngine.modelUI.name;
                    Asc.scope.commentId = commentId;


// Executes a block of code inside the editor's context using the document model API.
                    commentId = await Asc.Editor.callCommand(function(){
// Returns the main document object, which gives access to all editing, structure, and selection APIs.
                        let doc = Api.GetDocument();


                        let commentId = Asc.scope.commentId;
                        if (!commentId)
                        {
// Gets the current selected text range, which can be modified or annotated.
                            let range = doc.GetRangeBySelect();
                            if (!range)
                                return null;


                            let comment = range.AddComment(Asc.scope.data, Asc.scope.model, "uid" + Asc.scope.model);
                            if (!comment)
                                return null;
                            doc.ShowComment([comment.GetId()]);
                            return comment.GetId();
                        }


                        let comment = doc.GetCommentById(commentId);
                        if (!comment)
                            return commentId;


                        comment.SetText(comment.GetText() + scope.data);
                        return commentId;
                    });
                });
            }

Σημείωση! Για να διασφαλίσουμε ότι ολόκληρο το μπλοκ αλλαγών μπορεί να αναιρεθεί μετά την εκτέλεση του αιτήματος, χρησιμοποιούμε τις μεθόδους StartAction και EndAction σε όλη τη συνάρτηση commentText.

Ολόκληρη η υλοποίηση της συνάρτησης commentText με σχόλια:

(function(){
// Defines the commentText function — lets AI insert a comment or footnote for selected text using AI response.
    WORD_FUNCTIONS.commentText = function()
    {
// Creates a new function object that will be registered and exposed to the AI.
        let func = new RegisteredFunction();
        func.name = "commentText";
// Lists the parameters expected by the function. These are passed as a JSON object by the AI agent.
        func.params = [
            "type (string): whether to add as a 'comment' or as a 'footnote' (default is 'comment')"
        ];


// Gives example JSON inputs to teach the AI how to correctly invoke this function.
        func.examples = [
            "If you need to explain selected text as a comment, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"comment\"}",


            "If you need to add a footnote to selected text, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Add a footnote to this text\", \"type\": \"footnote\"}",


            "If you need to comment selected text, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Comment this text\"}",


            "If you need to explain selected text as a footnote, respond with:\n" +
            "[functionCalling (commentText)]: {\"prompt\" : \"Explain this text\", \"type\": \"footnote\"}"
        ];
        
// The actual logic that gets executed when the AI calls this function.
        func.call = async function(params) {
            let type = params.type;
            let isFootnote = "footnote" === type;


// Executes a block of code inside the editor's context using the office-js API.
            let text = await Asc.Editor.callCommand(function(){
                let doc = Api.GetDocument();
// Gets the current selected text range.
                let range = doc.GetRangeBySelect();
                let text = range ? range.GetText() : "";
                if (!text)
                {
                    text = doc.GetCurrentWord();
// Selects the current word so comments can be applied to it.
                    doc.SelectCurrentWord();
                }


                return text;
            });


            let argPromt = params.prompt + ":\n" + text;


// Initializes a request engine for communicating with the AI model (e.g. Chat, Translation).
            let requestEngine = AI.Request.create(AI.ActionType.Chat);
            if (!requestEngine)
                return;


            let isSendedEndLongAction = false;
// Marks the end of a logical group or block action in the editor.
            async function checkEndAction() {
                if (!isSendedEndLongAction) {
// Marks the end of a logical group or block action in the editor.
                    await Asc.Editor.callMethod("EndAction", ["Block", "AI (" + requestEngine.modelUI.name + ")"]);
                    isSendedEndLongAction = true
                }
            }


// Starts a block action in the editor, used for undo/redo 
            await Asc.Editor.callMethod("StartAction", ["Block", "AI (" + requestEngine.modelUI.name + ")"]);
// Starts a block action in the editor, used for undo/redo
            await Asc.Editor.callMethod("StartAction", ["GroupActions"]);


            if (isFootnote)
            {
                let addFootnote = true;
// Sends a prompt to the AI model and processes the response via callback
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;


// Marks the end of a block action in the editor.
                    await checkEndAction();
                    Asc.scope.data = data;
                    Asc.scope.model = requestEngine.modelUI.name;


                    if (addFootnote)
                    {
// Executes a block of code inside the editor's context using the  office-js API.
                        await Asc.Editor.callCommand(function(){
                            Api.GetDocument().AddFootnote();
                        });
                        addFootnote = false;
                    }
// Inserts the AI-generated result into the document at the current selection or cursor.
                    await Asc.Library.PasteText(data);
                });
            }
            else 
            {
                let commentId = null;
// Sends a prompt to the AI model and processes the response via callback.
                let result = await requestEngine.chatRequest(argPromt, false, async function(data) {
                    if (!data)
                        return;


// Marks the end of a block action in the editor.
                    await checkEndAction();
                    Asc.scope.data = data;
                    Asc.scope.model = requestEngine.modelUI.name;
                    Asc.scope.commentId = commentId;


// Executes a block of code inside the editor's context using the office-js API.
                    commentId = await Asc.Editor.callCommand(function(){
                        let doc = Api.GetDocument();


                        let commentId = Asc.scope.commentId;
                        if (!commentId)
                        {
// Gets the current selected text range.
                            let range = doc.GetRangeBySelect();
                            if (!range)
                                return null;


                            let comment = range.AddComment(Asc.scope.data, Asc.scope.model, "uid" + Asc.scope.model);
                            if (!comment)
                                return null;
                            doc.ShowComment([comment.GetId()]);
                            return comment.GetId();
                        }


                        let comment = doc.GetCommentById(commentId);
                        if (!comment)
                            return commentId;


                        comment.SetText(comment.GetText() + scope.data);
                        return commentId;
                    });
                });
            }


// Marks the end of a  block action in the editor.
            await checkEndAction();
// Marks the end of a block action in the editor.
            await Asc.Editor.callMethod("EndAction", ["GroupActions"]);
        };


        return func;
    }

Αυτό που δεσμευόμαστε είναι να συμβαδίζουμε με τη μοντέρνα τεχνολογία, διασφαλίζοντας ότι ο έξυπνος πράκτορας ΤΝ μας συνεχίζει να εξελίσσεται παράλληλα με τις ανάγκες του σημερινού ψηφιακού κόσμου. Δημιουργώντας τις δικές σας προσαρμοσμένες συναρτήσεις, μπορείτε να επεκτείνετε τις δυνατότητές του ώστε να ταιριάζουν στις ακριβείς, μοναδικές σας απαιτήσεις. Καλωσορίζουμε τη δημιουργικότητα και τις ιδέες σας.

Εάν έχετε οποιεσδήποτε ερωτήσεις, προτάσεις ή σχόλια, μη διστάσετε να επικοινωνήσετε μαζί μας. Είμαστε πάντα έτοιμοι να συνεργαστούμε και να σας βοηθήσουμε να πραγματοποιήσετε το όραμά σας! Καλή τύχη στις εξερευνητικές σας προσπάθειες!