Hyrje në thirrjet funksionale me Gemini API

Duke përdorur funksionin e thirrjes së funksionit Gemini API, mund t'i jepni modelit përkufizime të personalizuara të funksioneve. Modeli nuk i thërret drejtpërdrejt këto funksione, por në vend të kësaj gjeneron dalje të strukturuar që specifikon emrin e funksionit dhe argumentet e sugjeruara. Më pas mund të përdorni emrin e funksionit dhe argumentet për të thirrur një API të jashtme dhe mund të përfshini daljen e API-së që rezulton në një pyetje të mëtejshme të modelit, duke i mundësuar modelit të japë një përgjigje më gjithëpërfshirëse dhe të ndërmarrë veprime shtesë.

Thirrja e funksionit fuqizon përdoruesit të ndërveprojnë me informacione dhe shërbime në kohë reale si bazat e të dhënave, sistemet e menaxhimit të marrëdhënieve me klientët dhe depot e dokumenteve. Veçoria rrit gjithashtu aftësinë e modelit për të dhënë përgjigje përkatëse dhe kontekstuale. Thirrja e funksionit është më e mira për ndërveprim me sisteme të jashtme. Nëse rasti juaj i përdorimit kërkon që modeli të kryejë llogaritje, por nuk përfshin sisteme të jashtme ose API, duhet të merrni parasysh përdorimin e ekzekutimit të kodit .

Për një shembull pune të thirrjes së funksionit, shihni fletoren "light bot" .

Si funksionon thirrja e funksionit

Ju përdorni veçorinë e thirrjes së funksionit duke shtuar të dhëna të strukturuara të pyetjeve që përshkruajnë ndërfaqet programuese, të quajtura deklarata të funksionit , në një prompt modeli. Deklaratat e funksionit japin emrin e funksionit API, shpjegojnë qëllimin e tij, çdo parametër që ai mbështet dhe përshkrimet e atyre parametrave. Pasi t'i kaloni modelit një listë të deklaratave të funksioneve në një pyetje, ai analizon deklaratat e funksionit dhe pjesën tjetër të pyetjes për të përcaktuar se si të përdoret API e deklaruar në përgjigje të kërkesës.

Modeli më pas kthen një objekt në një skemë të pajtueshme me OpenAPI, duke specifikuar se si të thirret një ose më shumë funksione të deklaruara në mënyrë që t'i përgjigjet pyetjes së përdoruesit. Më pas mund të merrni parametrat e rekomanduar të thirrjes së funksionit, të telefononi API-në aktuale, të merrni një përgjigje dhe t'ia jepni atë përgjigje përdoruesit ose të ndërmerrni veprime të mëtejshme. Vini re se modeli në fakt nuk thërret funksionet e deklaruara. Në vend të kësaj, ju përdorni parametrat e kthyer të objektit të skemës për të thirrur funksionin. Gemini API gjithashtu mbështet thirrjet paralele të funksioneve, ku modeli rekomandon thirrje të shumta funksionesh API bazuar në një kërkesë të vetme.

Deklaratat e funksionit

Kur zbatoni thirrjen e funksionit në një prompt, krijoni një objekt tools , i cili përmban një ose më shumë function declarations . Ju përcaktoni funksionet duke përdorur JSON, veçanërisht me një nëngrup të zgjedhur të formatit të skemës OpenAPI . Një deklaratë e vetme funksioni mund të përfshijë parametrat e mëposhtëm:

  • name (string): Identifikuesi unik për funksionin brenda thirrjes API.
  • description (string): Një shpjegim gjithëpërfshirës i qëllimit dhe aftësive të funksionit.
  • parameters (objekt): Përcakton të dhënat hyrëse të kërkuara nga funksioni.
    • type (string): Përcakton llojin e përgjithshëm të të dhënave, si p.sh. object .
    • properties (objekt): Liston parametra individualë, secili me:
      • type (string): Lloji i të dhënave të parametrit, të tilla si string , integer , boolean .
      • description (string): Një shpjegim i qartë i qëllimit të parametrit dhe formatit të pritur.
    • required (array): Një grup vargjesh që listojnë emrat e parametrave që janë të detyrueshëm për funksionimin e funksionit.

Për shembuj kodesh të një deklarate funksioni duke përdorur komandat cURL, shihni shembujt e thirrjes së funksionit . Për shembuj të krijimit të deklaratave të funksioneve duke përdorur Gemini API SDK, shihni tutorialin e thirrjes së funksionit .

Praktikat më të mira për deklaratat e funksioneve

Përcaktimi i saktë i funksioneve tuaja është thelbësor kur i integroni ato në kërkesat tuaja. Çdo funksion mbështetet në parametra specifikë që drejtojnë sjelljen dhe ndërveprimin e tij me modelin. Lista e mëposhtme ofron udhëzime për përcaktimin e parametrave të një funksioni individual në një grup functions_declarations .

  • name : Përdorni emra të qartë, përshkrues pa karaktere hapësirë, pikë ( . ) ose vizë ( - ). Në vend të kësaj, përdorni karaktere nënvizore ( _ ) ose kuti deveje.

  • description : Jepni përshkrime të detajuara, të qarta dhe specifike të funksionit, duke ofruar shembuj nëse është e nevojshme. Për shembull, në vend që find theaters , përdorni find theaters based on location and optionally movie title that is currently playing in theaters. Shmangni përshkrimet tepër të gjera ose të paqarta.

  • properties > type : Përdorni parametra të shtypur fort për të reduktuar halucinacionet e modelit. Për shembull, nëse vlerat e parametrave janë nga një grup i kufizuar, përdorni një fushë enum në vend që të listoni vlerat në përshkrim (p.sh., "type": "enum", "values": ["now_playing", "upcoming"] ). Nëse vlera e parametrit është gjithmonë një numër i plotë, vendosni llojin në integer dhe jo në number .

  • properties > description : Jepni shembuj dhe kufizime konkrete. Për shembull, në vend të the location to search , përdorni The city and state, eg San Francisco, CA or a zip code eg 95616 .

Për më shumë praktika më të mira kur përdorni thirrjen e funksionit, shihni seksionin Praktikat më të mira .

Funksiononi modalitetin e thirrjes

Mund të përdorni parametrin mode të thirrjes së funksionit për të modifikuar sjelljen e ekzekutimit të funksionit. Ekzistojnë tre mënyra në dispozicion:

  • AUTO : Sjellja e modelit të paracaktuar. Modeli vendos të parashikojë ose një thirrje funksioni ose një përgjigje të gjuhës natyrore.
  • ANY : Modeli është i kufizuar të parashikojë gjithmonë një thirrje funksioni. Nëse allowed_function_names nuk ofrohen, modeli zgjedh nga të gjitha deklaratat e funksioneve të disponueshme. Nëse ofrohen allowed_function_names , modeli zgjedh nga grupi i funksioneve të lejuara.
  • NONE : Modeli nuk do të parashikojë një thirrje funksioni. Në këtë rast, sjellja e modelit është e njëjtë sikur të mos kaloni asnjë deklaratë funksioni.

Ju gjithashtu mund të kaloni një grup allowed_function_names që, kur ofrohet, kufizon funksionet që modeli do të thërrasë. Ju duhet të përfshini allowed_function_names vetëm kur modaliteti është ANY . Emrat e funksioneve duhet të përputhen me emrat e deklaratave të funksioneve. Me modalitetin e vendosur në ANY dhe të caktuar_emrat_funksioni_të allowed_function_names , modeli do të parashikojë një thirrje funksioni nga grupi i emrave të funksioneve të ofruara.

Pjesa e mëposhtme e kodit nga një kërkesë shembull tregon se si të vendosni mode në ANY dhe të specifikoni një listë të funksioneve të lejuara:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Thirrja e funksionit kompozicional

Gemini 2.0 mbështet një aftësi të re për thirrjen e funksionit: thirrjen e funksionit kompozicional . Thirrja e funksionit kompozicional i mundëson API-së Gemini të thërrasë automatikisht funksione të shumta të përcaktuara nga përdoruesi në procesin e gjenerimit të një përgjigjeje. Për shembull, për t'iu përgjigjur kërkesës "Get the temperature in my current location" , Gemini API mund të thërrasë si një funksion get_current_location() dhe një funksion get_weather() që merr vendndodhjen si parametër.

Thirrja e funksionit kompozicional me ekzekutimin e kodit kërkon transmetim dydrejtimësh dhe mbështetet vetëm nga API-ja e re Multimodal Live. Ja një shembull që tregon se si mund të përdorni thirrjen e funksionit kompozicional, ekzekutimin e kodit dhe API-në Multimodal Live së bashku:

turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}

prompt = """
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
  """

tools = [
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

Zhvilluesit e Python mund ta provojnë këtë në fletoren Live API Tool Use .

Përdorimi me shumë mjete

Me Gemini 2.0, mund të aktivizoni shumë mjete në të njëjtën kohë dhe modeli do të vendosë se kur t'i telefonojë ato. Ja një shembull që mundëson dy mjete, Grounding with Google Search dhe ekzekutimin e kodit, në një kërkesë duke përdorur Multimodal Live API.

prompt = """
  Hey, I need you to do three things for me.

  1. Turn on the lights.
  2. Then compute the largest prime palindrome under 100000.
  3. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
  """

tools = [
    {'google_search': {}},
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

Zhvilluesit e Python mund ta provojnë këtë në fletoren Live API Tool Use .

Shembuj të thirrjes së funksionit

Ky seksion ofron shembuj të kërkesave për thirrjen e funksionit duke përdorur komandat cURL. Shembujt përfshijnë skenarë me një kthesë të vetme dhe me shumë kthesa, si dhe aktivizimin e mënyrave të ndryshme të thirrjes së funksioneve.

Kur përdorni komandat cURL me këtë veçori, informacioni i funksionit dhe parametrave përfshihet në elementin e tools . Çdo deklaratë funksioni në elementin tools përmban emrin e funksionit dhe ju specifikoni parametrat duke përdorur një skemë të pajtueshme me OpenAPI dhe një përshkrim funksioni.

Shembull me një kthesë

Një kthesë është kur telefononi modelin e gjuhës një herë. Me thirrjen e funksionit, një rast përdorimi me një kthesë mund të jetë kur i jepni modelit një pyetje të gjuhës natyrore dhe një listë funksionesh. Në këtë rast, modeli përdor deklaratën e funksionit, e cila përfshin emrin e funksionit, parametrat dhe përshkrimin, për të parashikuar se cilin funksion do të thërrasë dhe argumentet me të cilat do të thirret.

Shembulli i mëposhtëm i kaçurrelave është një shembull i kalimit në një përshkrim të një funksioni që kthen informacione rreth vendit ku shfaqet një film. Në kërkesë përfshihen disa deklarata funksionesh, të tilla si find_movies dhe find_theaters . 

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Which theaters in Mountain View show Barbie movie?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ]
}'

Përgjigja ndaj këtij shembulli të kaçurrelave mund të jetë e ngjashme me sa vijon. 

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "movie": "Barbie",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "totalTokenCount": 9
  }
}]

Shembull me një kthesë duke përdorur çdo mënyrë

Shembulli i mëposhtëm i kaçurrelave është i ngjashëm me shembullin me një kthesë të vetme , por ai e vendos modalitetin në ANY :

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY"
    },
  }
}'

Përgjigja mund të jetë e ngjashme me sa vijon: 

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "",
                "location": "North Seattle, WA"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

Shembull me një kthesë duke përdorur çdo mënyrë dhe funksione të lejuara

Shembulli i mëposhtëm i kaçurrelave është i ngjashëm me shembullin me një kthesë , por ai e vendos modalitetin në ANY dhe përfshin një listë të funksioneve të lejuara:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY",
      "allowed_function_names": ["find_theaters", "get_showtimes"]
    },
  }
}'

Modeli nuk mund të parashikojë funksionin find_movies , sepse nuk është në listën e funksioneve të lejuara, kështu që parashikon një funksion tjetër. Përgjigja mund të jetë e ngjashme me sa vijon: 

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "location": "North Seattle, WA",
                "movie": null
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

Shembuj me shumë kthesa

Mund të zbatoni një skenar të thirrjes së funksionit me shumë kthesa duke bërë sa më poshtë:

  1. Merrni një përgjigje të thirrjes së funksionit duke thirrur modelin e gjuhës. Kjo është kthesa e parë.
  2. Thirrni modelin e gjuhës duke përdorur përgjigjen e thirrjes së funksionit nga kthesa e parë dhe përgjigjen e funksionit që merrni nga thirrja e atij funksioni. Kjo është kthesa e dytë.

Përgjigja nga kthesa e dytë ose përmbledh rezultatet për t'iu përgjigjur pyetjes suaj në radhën e parë, ose përmban një thirrje të dytë funksioni që mund ta përdorni për të marrë më shumë informacion për pyetjen tuaj.

Kjo temë përfshin dy shembuj të kaçurrelave me shumë kthesa:

Përdorni një përgjigje nga një kthesë e mëparshme

Shembulli i mëposhtëm curl thërret funksionin dhe argumentet e kthyera nga shembulli i mëparshëm me një kthesë për të marrë një përgjigje. Metoda dhe parametrat e kthyer nga shembulli me një kthesë janë në këtë JSON. 

"functionCall": {
  "name": "find_theaters",
  "args": {
    "movie": "Barbie",
    "location": "Mountain View, CA"
  }
}

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

Përgjigja ndaj këtij shembulli curl përfshin rezultatin e thirrjes së metodës find_theaters . Përgjigja mund të jetë e ngjashme me sa vijon: 

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  }
}

Thirrni modelin disa herë

Shembulli i mëposhtëm cURL thërret disa herë modelin gjenerues të AI për të thirrur një funksion. Sa herë që modeli thërret funksionin, ai mund të përdorë një funksion të ndryshëm për t'iu përgjigjur një pyetjeje të ndryshme të përdoruesit në kërkesë. 

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  },
  {
    "role": "model",
    "parts": [{
      "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
    }]
  },{
    "role": "user",
    "parts": [{
      "text": "Can we recommend some comedy movies on show in Mountain View?"
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'
    
[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "comedy",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 48,
    "totalTokenCount": 48
  }
}
]

Praktikat më të mira

Ndiqni këto praktika më të mira për të përmirësuar saktësinë dhe besueshmërinë e thirrjeve tuaja funksionale.

Kërkesa e përdoruesit

Për rezultate më të mira, parashtroni pyetjen e përdoruesit me detajet e mëposhtme:

  • Konteksti shtesë për modelin. Për shembull, You are a movie API assistant to help users find movies and showtimes based on their preferences.
  • Detaje ose udhëzime se si dhe kur të përdoren funksionet. Për shembull, Don't make assumptions on showtimes. Always use a future date for showtimes.
  • Udhëzime për të bërë pyetje sqaruese nëse pyetjet e përdoruesit janë të paqarta. Për shembull, Ask clarifying questions if not enough information is available to complete the request.

Parametrat e kampionimit

Për parametrin e temperaturës, përdorni 0 ose një vlerë tjetër të ulët. Kjo e udhëzon modelin të gjenerojë rezultate më të sigurta dhe redukton halucinacionet.

Thirrja e API-së

Nëse modeli propozon thirrjen e një funksioni që do të dërgonte një porosi, do të përditësonte një bazë të dhënash ose do të kishte pasoja të rëndësishme, vërtetoni thirrjen e funksionit me përdoruesin përpara se ta ekzekutoni atë.