Function Calling API

Funktionsaufrufe verbessern die Fähigkeit der LLMs, relevante und kontextbezogene Antworten zu liefern.

Mit der Function Calling API können Sie benutzerdefinierte Funktionen für ein generatives KI-Modell bereitstellen. Das Modell ruft diese Funktionen nicht direkt auf, sondern generiert eine strukturierte Datenausgabe, die den Funktionsnamen und die vorgeschlagenen Argumente angibt.

Diese Ausgabe ermöglicht den Aufruf externer APIs oder Informationssysteme wie Datenbanken, Customer-Relationship-Management-Systeme und Dokument-Repositories. Die resultierende API-Ausgabe kann vom LLM verwendet werden, um die Antwortqualität zu verbessern.

Weitere konzeptionelle Dokumentationen zum Funktionsaufruf finden Sie unter Funktionsaufrufe.

Unterstützte Modelle:

Modell Version
Gemini 1.5 Flash gemini-1.5-flash-001
Gemini 1.5 Pro, gemini-1.5-pro-001
Gemini 1.0 Pro gemini-1.0-pro-001
gemini-1.0-pro-002 (Unterstützung für Funktionsaufrufe ist Vorschau)

Beschränkungen:

  • Es können maximal 64 Funktionen aufgerufen werden.
  • FunctionCallingConfig ist nur mit dem Modell gemini-1.5-pro-001 verfügbar.

Beispielsyntax

Syntax zum Senden einer API-Anfrage für einen Funktionsaufruf.

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
  "contents": [{
    ...
  }],
  "tools": [{
    "function_declarations": [
      {
        ...
      }
    ]
  }]
}'

Python

gemini_model = GenerativeModel(
    MODEL_ID,
    generation_config=generation_config,
    tools=[
        Tool(
            function_declarations=[
                FunctionDeclaration(
                    ...
                )
            ]
        )
    ],
)

Parameterliste

Einzelheiten zur Implementierung finden Sie in den Beispielen.

FunctionDeclaration

Eine strukturierte Darstellung einer Funktionsdeklaration gemäß der Definition der OpenAPI 3.0-Spezifikation, die eine Funktion darstellt, für die das Modell JSON-Eingaben generieren kann.

Parameter

name

string

Der Name der aufzurufenden Funktion.

description

Optional: string

Beschreibung und Zweck der Funktion.

parameters

Optional: Schema

Beschreibt die Parameter der Funktion im OpenAPI-JSON-Schemaobjektformat: OpenAPI 3.0-Spezifikation.

response

Optional: Schema

Beschreibt die Ausgabe der Funktion im OpenAPI-JSON-Schemaobjektformat: OpenAPI 3.0-Spezifikation.

Schema

Mit dem Schema wird das Format der Eingabe- und Ausgabedaten in einem Funktionsaufruf definiert. Eine strukturierte Darstellung einer Funktionsdeklaration gemäß der Definition der OpenAPI 3.0-Schemaspezifikation.

Parameter
Typ

string

Enum. Der Typ der Daten. Muss einer der folgenden sein:

  • STRING
  • INTEGER
  • BOOLEAN
  • NUMBER
  • ARRAY
  • OBJECT
description

Optional: string

Beschreibung der Daten.
enum

Optional: string[]

Mögliche Werte des Elements Type.STRING im enum-Format.
items

Optional: Schema[]

Schema der Elemente von Type.ARRAY
properties

Optional: Schema

Schema der Attribute von Type.OBJECT
required

Optional: string[]

Erforderliche Attribute von Type.OBJECT.
nullable

Optional: bool

Gibt an, ob der Wert null sein kann.

FunctionCallingConfig (Vorschau)

Die FunctionCallingConfig steuert das Verhalten des Modells und bestimmt, welche Art von Funktion aufgerufen wird.

Dieses Feature ist nur für das gemini-1.5-pro-preview-0409-Modell verfügbar.

Parameter

mode

Optional: enum/string[]

  • AUTO: Standardverhalten des Modells. Das Modell kann Vorhersagen in einer Funktionsaufrufform oder in einer Natural Language-Antwortform treffen. Das Modell entscheidet basierend auf dem Kontext, welches Format verwendet wird.
  • NONE: Das Modell trifft keine Vorhersagen in Form von Funktionsaufrufen.
  • ANY: Das Modell sagt immer einen einzelnen Funktionsaufruf vorher.

allowed_function_names

Optional: string[]

Funktionsnamen, die aufgerufen werden sollen. Nur festgelegt, wenn der mode ANY ist. Funktionsnamen sollten mit [FunctionDeclaration.name] übereinstimmen. Wenn der Modus auf ANY gesetzt ist, sagt das Modell einen Funktionsaufruf aus dem Satz der angegebenen Funktionsnamen voraus.

Beispiele

Funktionsdeklaration senden

Das folgende Beispiel zeigt ein einfaches Beispiel für das Senden einer Abfrage und einer Funktionsdeklaration an das Modell.

REST

Ersetzen Sie dabei folgende Werte für die Anfragedaten:

  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
  • MODEL_ID: Die ID des Modells, das verarbeitet wird.
  • ROLE: Die Identität der Entität, die die Nachricht erstellt.
  • TEXT: Der Prompt, der an das Modell gesendet werden soll.
  • NAME: Der Name der aufzurufenden Funktion.
  • DESCRIPTION: Beschreibung und Zweck der Funktion.
  • Informationen zu anderen Feldern finden Sie in der Tabelle Parameterliste.

HTTP-Methode und URL:

POST   https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

JSON-Text der Anfrage:

{
  "contents": [{
    "role": "ROLE",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "function_declarations": [
      {
        "name": "NAME",
        "description": "DESCRIPTION",
        "parameters": {
          "type": "TYPE",
          "properties": {
            "location": {
              "type": "TYPE",
              "description": "DESCRIPTION"
            }
          },
          "required": [
            "location"
          ]
        }
      }
    ]
  }]
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

Beispiel: cURL-Befehls

PROJECT_ID=myproject
LOCATION=us-central1
MODEL_ID=gemini-1.0-pro-002

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "What is the weather in Boston?"
      }]
    }],
    "tools": [{
      "functionDeclarations": [
        {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              }
            },
            "required": [
              "location"
            ]
          }
        }
      ]
    }]
  }'

Python 

import vertexai
from vertexai.generative_models import (
    Content,
    FunctionDeclaration,
    GenerationConfig,
    GenerativeModel,
    Part,
    Tool,
)

# Initialize Vertex AI
# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
vertexai.init(project=project_id, location="us-central1")

# Initialize Gemini model
model = GenerativeModel(model_name="gemini-1.0-pro-001")

# Define the user's prompt in a Content object that we can reuse in model calls
user_prompt_content = Content(
    role="user",
    parts=[
        Part.from_text("What is the weather like in Boston?"),
    ],
)

# Specify a function declaration and parameters for an API request
function_name = "get_current_weather"
get_current_weather_func = FunctionDeclaration(
    name=function_name,
    description="Get the current weather in a given location",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "Location"}},
    },
)

# Define a tool that includes the above get_current_weather_func
weather_tool = Tool(
    function_declarations=[get_current_weather_func],
)

# Send the prompt and instruct the model to generate content using the Tool that you just created
response = model.generate_content(
    user_prompt_content,
    generation_config=GenerationConfig(temperature=0),
    tools=[weather_tool],
)
function_call = response.candidates[0].function_calls[0]
print(function_call)

# Check the function name that the model responded with, and make an API call to an external system
if function_call.name == function_name:
    # Extract the arguments to use in your API call
    location = function_call.args["location"]  # noqa: F841

    # Here you can use your preferred method to make an API request to fetch the current weather, for example:
    # api_response = requests.post(weather_api_url, data={"location": location})

    # In this example, we'll use synthetic data to simulate a response payload from an external API
    api_response = """{ "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy",
                    "icon": "partly-cloudy", "humidity": 65, "wind": { "speed": 10, "direction": "NW" } }"""

# Return the API response to Gemini so it can generate a model response or request another function call
response = model.generate_content(
    [
        user_prompt_content,  # User prompt
        response.candidates[0].content,  # Function call response
        Content(
            parts=[
                Part.from_function_response(
                    name=function_name,
                    response={
                        "content": api_response,  # Return the API response to Gemini
                    },
                ),
            ],
        ),
    ],
    tools=[weather_tool],
)

# Get the model response
print(response.text)

Node.js 

const {
  VertexAI,
  FunctionDeclarationSchemaType,
} = require('@google-cloud/vertexai');

const functionDeclarations = [
  {
    function_declarations: [
      {
        name: 'get_current_weather',
        description: 'get weather in a given location',
        parameters: {
          type: FunctionDeclarationSchemaType.OBJECT,
          properties: {
            location: {type: FunctionDeclarationSchemaType.STRING},
            unit: {
              type: FunctionDeclarationSchemaType.STRING,
              enum: ['celsius', 'fahrenheit'],
            },
          },
          required: ['location'],
        },
      },
    ],
  },
];

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function functionCallingBasic(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.preview.getGenerativeModel({
    model: model,
  });

  const request = {
    contents: [
      {role: 'user', parts: [{text: 'What is the weather in Boston?'}]},
    ],
    tools: functionDeclarations,
  };
  const result = await generativeModel.generateContent(request);
  console.log(JSON.stringify(result.response.candidates[0].content));
}

Funktionsdeklaration mit FunctionCallingConfig senden

Das folgende Beispiel zeigt, wie eine FunctionCallingConfig an das Modell übergeben wird.

Die functionCallingConfig sorgt dafür, dass die Modellausgabe immer ein bestimmter Funktionsaufruf ist. Zum Konfigurieren:

  • Setzen Sie die Funktion, die mode aufruft, auf ANY.
  • Geben Sie die Funktionsnamen an, die Sie in allowed_function_names verwenden möchten. Wenn allowed_function_names leer ist, können alle bereitgestellten Funktionen zurückgegeben werden.

REST 

PROJECT_ID=myproject
LOCATION=us-central1
MODEL_ID=gemini-1.5-pro-preview-0409

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
      }]
    }],
    "tools": [{
      "functionDeclarations": [
        {
          "name": "get_product_sku",
          "description": "Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
          "parameters": {
            "type": "object",
            "properties": {
              "product_name": {"type": "string", "description": "Product name"}
            }
          }
        },
        {
          "name": "get_store_location",
          "description": "Get the location of the closest store",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "Location"}
            },
          }
        }
      ]
    }],
    "toolConfig": {
        "functionCallingConfig": {
            "mode":"ANY",
            "allowedFunctionNames": ["get_product_sku"]
      }
    },
    "generationConfig": {
      "temperature": 0.95,
      "topP": 1.0,
      "maxOutputTokens": 8192
    }
  }'

Python 

import vertexai
from vertexai.preview.generative_models import (
    FunctionDeclaration,
    GenerativeModel,
    Tool,
    ToolConfig,
)

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"

# Initialize Vertex AI
vertexai.init(project=project_id, location="us-central1")

# Specify a function declaration and parameters for an API request
get_product_sku_func = FunctionDeclaration(
    name="get_product_sku",
    description="Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {
            "product_name": {"type": "string", "description": "Product name"}
        },
    },
)

# Specify another function declaration and parameters for an API request
get_store_location_func = FunctionDeclaration(
    name="get_store_location",
    description="Get the location of the closest store",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "Location"}},
    },
)

# Define a tool that includes the above functions
retail_tool = Tool(
    function_declarations=[
        get_product_sku_func,
        get_store_location_func,
    ],
)

# Define a tool config for the above functions
retail_tool_config = ToolConfig(
    function_calling_config=ToolConfig.FunctionCallingConfig(
        # ANY mode forces the model to predict a function call
        mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
        # List of functions that can be returned when the mode is ANY.
        # If the list is empty, any declared function can be returned.
        allowed_function_names=["get_product_sku"],
    )
)

model = GenerativeModel(
    model_name="gemini-1.5-flash-001",
    tools=[retail_tool],
    tool_config=retail_tool_config,
)
response = model.generate_content(
    "Do you have the Pixel 8 Pro 128GB in stock?",
)

print(response.text)
print(response.candidates[0].function_calls)

Node.js 

const {
  VertexAI,
  FunctionDeclarationSchemaType,
} = require('@google-cloud/vertexai');

const functionDeclarations = [
  {
    function_declarations: [
      {
        name: 'get_product_sku',
        description:
          'Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc',
        parameters: {
          type: FunctionDeclarationSchemaType.OBJECT,
          properties: {
            productName: {type: FunctionDeclarationSchemaType.STRING},
          },
        },
      },
      {
        name: 'get_store_location',
        description: 'Get the location of the closest store',
        parameters: {
          type: FunctionDeclarationSchemaType.OBJECT,
          properties: {
            location: {type: FunctionDeclarationSchemaType.STRING},
          },
        },
      },
    ],
  },
];

const toolConfig = {
  function_calling_config: {
    mode: 'ANY',
    allowed_function_names: ['get_product_sku'],
  },
};

const generationConfig = {
  temperature: 0.95,
  topP: 1.0,
  maxOutputTokens: 8192,
};

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function functionCallingAdvanced(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.preview.getGenerativeModel({
    model: model,
  });

  const request = {
    contents: [
      {
        role: 'user',
        parts: [
          {text: 'Do you have the White Pixel 8 Pro 128GB in stock in the US?'},
        ],
      },
    ],
    tools: functionDeclarations,
    tool_config: toolConfig,
    generation_config: generationConfig,
  };
  const result = await generativeModel.generateContent(request);
  console.log(JSON.stringify(result.response.candidates[0].content));
}

Nächste Schritte

Eine ausführliche Dokumentation finden Sie hier: