您現在可以透過 Google 搜尋進行地面資訊驗證了！瞭解詳情

本頁面由 Cloud Translation API 翻譯而成。

函式呼叫教學課程

函式呼叫可讓您更輕鬆地從生成式模型取得結構化資料輸出內容。您可以運用這些輸出內容呼叫其他 API，並傳回傳送給模型的相關回應資料換句話說，函式呼叫可協助您將生成式模型連結至外部系統，讓產生的內容包含最新且正確的資訊。

您可以為 Gemini 模型提供函式說明。這些您以應用程式語言編寫的函式 (換句話說，非 Google Cloud Functions)。模型可能會要求您呼叫函式並傳回結果，以便模型處理您的查詢。

如果您還不熟悉，請參閱「函式呼叫簡介」一文，進一步瞭解相關資訊。您也可以在 Google Colab 中試用這項功能，或是在 Gemini API Cookbook 存放區中查看範例程式碼。

燈光控制 API 範例

假設您有一個基本的照明控制系統搭配應用程式設計介面 (API)，並希望使用者能透過簡單的文字要求您可以使用函式呼叫功能解讀光線將來自使用者的要求轉譯為 API 呼叫，藉此設定亮度輕鬆分配獎金這款假設性的照明控制系統光線的亮度以及色溫，定義為兩個分開的參數：

參數	類型	必要	說明
`brightness`	數字	是	光線強度從 0 到 100。0 代表關閉狀態，100 則為全彩。
`colorTemperature`	字串	是	燈具的色溫，可能是 `daylight`、`cool` 或 `warm`。

簡單來說，這個虛構的照明系統只有一盞燈，因此使用者也不必指定會議室或地點以下是您可以傳送至照明控制 API 的 JSON 要求範例，藉此使用日光色溫將光線亮度變更為 50%：

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

本教學課程將說明如何為 Gemini API 設定函式呼叫，以便解讀使用者的照明要求，並將這些要求對應至 API 設定，以便控制燈光的亮度和色溫值。

事前準備：設定專案和 API 金鑰

呼叫 Gemini API 前，請先設定專案並設定您的 API 金鑰。

展開查看如何設定專案和 API 金鑰

取得並保護 API 金鑰

須有 API 金鑰才能呼叫 Gemini API。如果您還沒有金鑰，請在 Google AI 工作室中建立金鑰。

取得 API 金鑰

強烈建議您「不要」在版本中檢查 API 金鑰控制系統

請將 API 金鑰儲存在 Google Cloud 等密鑰存放區 Secret Manager。

本教學課程假設您是以環境變數的形式存取 API 金鑰。

安裝 SDK 套件並設定 API 金鑰

Gemini API 適用的 Python SDK 包含在 google-generativeai 套件。

使用 pip 安裝依附元件：
```
pip install -U google-generativeai
```

匯入套件，並使用 API 金鑰設定服務：

import os
import google.generativeai as genai

genai.configure(api_key=os.environ['API_KEY'])

定義 API 函式

建立可提出 API 要求的函式。這個函式應定義在應用程式的程式碼中，但可以呼叫應用程式以外的服務或 API。Gemini API 不會直接呼叫這個函式，因此你可以控制透過應用程式執行此函式的方式和時間再也不是件繁重乏味的工作為方便示範，本教學課程定義了一個模擬 API 函式只會傳回要求的亮度值：

def set_light_values(brightness, color_temp):
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {
        "brightness": brightness,
        "colorTemperature": color_temp
    }

如果您建立函式，用於模型的函式呼叫，最好在函式和參數中盡量加入詳細資料說明生成式模型會使用這項資訊，判斷要選取哪個函式，以及如何在函式呼叫中提供參數的值。

在模型初始化期間宣告函式

如要使用函式呼叫功能，您必須在初始化模型物件時宣告函式。如要宣告函式，請設定模型的 tools 參數：

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                              tools=[set_light_values])

生成函式呼叫

使用函式宣告初始化模型後，您可以加入已定義函式的模型您應使用即時通訊提示 (sendMessage())，因為函式呼叫通常從並回答先前的提示和回應

chat = model.start_chat()
response = chat.send_message('Dim the lights so the room feels cozy and warm.')
response.text

Python SDK 的 ChatSession 物件會為您處理對話記錄，簡化聊天會話階段的管理作業。您可以使用 enable_automatic_function_calling 讓 SDK 自動呼叫函式。

# Create a chat session that automatically makes suggested function calls
chat = model.start_chat(enable_automatic_function_calling=True)

並行函式呼叫

除了上述基本函式呼叫之外，您也可以在單一回合中呼叫多個函式。本節舉例說明如何使用平行函式呼叫。

定義工具。

def power_disco_ball(power: bool) -> bool:
    """Powers the spinning disco ball."""
    print(f"Disco ball is {'spinning!' if power else 'stopped.'}")
    return True


def start_music(energetic: bool, loud: bool, bpm: int) -> str:
    """Play some music matching the specified parameters.

    Args:
      energetic: Whether the music is energetic or not.
      loud: Whether the music is loud or not.
      bpm: The beats per minute of the music.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}, {bpm=}")
    return "Never gonna give you up."


def dim_lights(brightness: float) -> bool:
    """Dim the lights.

    Args:
      brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
    """
    print(f"Lights are now set to {brightness:.0%}")
    return True

現在，請使用可使用所有指定工具的指令呼叫模型。

# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]

model = genai.GenerativeModel(model_name="gemini-1.5-flash", tools=house_fns)

# Call the API.
chat = model.start_chat()
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call.
for part in response.parts:
    if fn := part.function_call:
        args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
        print(f"{fn.name}({args})")

power_disco_ball(power=True)
start_music(energetic=True, loud=True, bpm=120.0)
dim_lights(brightness=0.3)

每個輸出的結果都反映了模型要求的單一函式呼叫。如要傳回結果，請按照要求的順序加入回應。

# Simulate the responses from the specified tools.
responses = {
    "power_disco_ball": True,
    "start_music": "Never gonna give you up.",
    "dim_lights": True,
}

# Build the response parts.
response_parts = [
    genai.protos.Part(function_response=genai.protos.FunctionResponse(name=fn, response={"result": val}))
    for fn, val in responses.items()
]

response = chat.send_message(response_parts)
print(response.text)

Let's get this party started! I've turned on the disco ball, started playing some upbeat music, and dimmed the lights. 🎶✨  Get ready to dance! 🕺💃

函式呼叫資料類型對應

從 Python 函式自動擷取結構定義並非在所有情況下都有效。舉例來說，它不會處理您描述巢狀字典物件的欄位，但 API 支援這種情況。API 可描述下列任一類型：

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

google.ai.generativelanguage 用戶端程式庫可讓您存取低層級的類型，方便您完全掌控。

首先查看模型的 _tools 屬性，瞭解該屬性如何描述您傳遞至模型的函式：

def multiply(a:float, b:float):
    """returns a * b."""
    return a*b

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                             tools=[multiply])

model._tools.to_proto()

[function_declarations {
   name: "multiply"
   description: "returns a * b."
   parameters {
     type_: OBJECT
     properties {
       key: "b"
       value {
         type_: NUMBER
       }
     }
     properties {
       key: "a"
       value {
         type_: NUMBER
       }
     }
     required: "a"
     required: "b"
   }
 }]

此方法會傳回要傳送至值區的genai.protos.Tool物件清單也能使用 Google Cloud CLI 或 Compute Engine API如果您不熟悉列印格式，這是因為這些是 Google protobuf 類別。每個 genai.protos.Tool (在本例中為 1) 都包含 genai.protos.FunctionDeclarations 清單，用於說明函式及其引數。

以下是使用 genai.protos 類別。請注意，這些類別只會描述也無法實作 API因此，使用這個方法無法搭配自動函式呼叫，但函式不一定需要實作。

calculator = genai.protos.Tool(
    function_declarations=[
      genai.protos.FunctionDeclaration(
        name='multiply',
        description="Returns the product of two numbers.",
        parameters=genai.protos.Schema(
            type=genai.protos.Type.OBJECT,
            properties={
                'a':genai.protos.Schema(type=genai.protos.Type.NUMBER),
                'b':genai.protos.Schema(type=genai.protos.Type.NUMBER)
            },
            required=['a','b']
        )
      )
    ])

同樣，您可以將此物件描述為與 JSON 相容的物件：

calculator = {'function_declarations': [
      {'name': 'multiply',
       'description': 'Returns the product of two numbers.',
       'parameters': {'type_': 'OBJECT',
       'properties': {
         'a': {'type_': 'NUMBER'},
         'b': {'type_': 'NUMBER'} },
       'required': ['a', 'b']} }]}

genai.protos.Tool(calculator)

function_declarations {
  name: "multiply"
  description: "Returns the product of two numbers."
  parameters {
    type_: OBJECT
    properties {
      key: "b"
      value {
        type_: NUMBER
      }
    }
    properties {
      key: "a"
      value {
        type_: NUMBER
      }
    }
    required: "a"
    required: "b"
  }
}

無論是哪種方式，您都必須將 genai.protos.Tool 的表示法或工具清單傳遞至

model = genai.GenerativeModel('gemini-1.5-flash', tools=calculator)
chat = model.start_chat()

response = chat.send_message(
    f"What's 234551 X 325552 ?",
)

如同模型傳回 genai.protos.FunctionCall，叫用計算機的 multiply 函式之前，就好像之前一樣：

response.candidates

[index: 0
content {
  parts {
    function_call {
      name: "multiply"
      args {
        fields {
          key: "b"
          value {
            number_value: 325552
          }
        }
        fields {
          key: "a"
          value {
            number_value: 234551
          }
        }
      }
    }
  }
  role: "model"
}
finish_reason: STOP
]

自行執行函式：

fc = response.candidates[0].content.parts[0].function_call
assert fc.name == 'multiply'

result = fc.args['a'] * fc.args['b']
result

76358547152.0

將結果傳送至模型，即可繼續對話：

response = chat.send_message(
    genai.protos.Content(
    parts=[genai.protos.Part(
        function_response = genai.protos.FunctionResponse(
          name='multiply',
          response={'result': result}))]))