Functions on models（模型函数）¶

You can deploy models in the context of the Ontology by using functions that invoke models during their runtime. Model functions are automatically generated wrappers around live model deployments that can be imported into a functions repository and called from your code. This enables you to add custom business logic around model predictions, integrate models with Ontology objects, or orchestrate multiple model calls.

Overview¶

Model functions can be published from two types of deployments:

Direct model deployments: Published directly from the model page.
Modeling Objective live deployments: Published from the deployment details page in a Modeling Objective.

Both methods create a function with the same input and output API as your model. For details on function behavior, version upgrades, and configuration options, see the Model functions developer guide.

Model functions are fully supported in TypeScript v1, TypeScript v2, and Python functions.

Import a live deployment in a repository¶

Once a function for a live deployment has been created either on the model itself or in a modeling objective, it must be imported for usage in a specific repository. Select Add and Query Functions in the Resource Imports menu on the left side bar in the repository. Models are searchable by the function name that was chosen during publishing. Note that Python and TypeScript v2 repositories only support model functions that are tied to an ontology, as described in the section below.

:::callout{title="Notes" theme="neutral"} For TypeScript v1 repositories, it is also possible to import a model function by selecting Models, which is functionally equivalent to importing it under Query Functions.

Legacy function on models that use the API Name card in Modeling Objectives instead of the preferred model publication dialog can still be imported under the Modeling Objectives section, but are being sunset. :::

Ontology or space-bound functions¶

Starting from February 2026 onwards, all new model functions will be tied to an ontology. This is a prerequisite for usage in TypeScript v2 and Python functions, which only allow ontology resource imports. Prior to this date, model functions were tied to the model's space. TypeScript v1 allows importing both types of model functions, but the import and usage semantics vary slightly as detailed below.

To check if a function is bound to an ontology, navigate to your model: model functions that are not bound to an ontology will indicate that a migration is available. Learn more on migrating your function to be ontology-bound.

Call a model function from Python or TypeScript v2 functions¶

Once a function for a live deployment has been created, it must be imported for usage in a specific repository. It can then be queried like any query function.

Example code: Python¶

from functions.api import function, Double
from foundry_sdk_runtime import AllowBetaFeatures
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Flight


@function(beta=True)
def predict_flight_delays(flight: Flight) -> Double:
    # Prepare the input to match the model function's API.
    model_output = FoundryClient().ontology.queries.flight_model_deployment(
        df_in=[
            {
                "lastArrivalTime": flight.last_arrival_time,
                "lastExpectedArrivalTime": flight.last_expected_arrival_time,
            },
        ]
    )
    return model_output.df_out[0].prediction

Example code: TypeScript v2¶

import { Client } from "@osdk/client";
import { Double } from "@osdk/functions";
import { flightModelDeployment, Flight } from "@ontology/sdk";

async function predictFlightDelays(client: Client, flight: Flight): Promise<Double> {
    // Prepare the input to match the model function's API.
    const modelOutput = await client(flightModelDeployment).executeFunction({
        "df_in": [
            {
                "lastArrivalTime": flight.lastArrivalTime,
                "lastExpectedArrivalTime": flight.lastExpectedArrivalTime,
            },
        ]
    });
    return modelOutput.df_out[0].prediction;
}

export default predictFlightDelays;

Write a model-backed TypeScript v1 function¶

If the model function is registered to a space¶

We first need to import the function:

// If the model function is tied to a space and not to an ontology,
// copy the import snippet from the Resource imports sidebar.

Then, write a function that takes a flight, prepares data for the model, and interprets the result of the model execution. The model is imported as an asynchronous function that respects the model's input and output specification or API. From this, TypeScript can ensure, at compile time, that the correct data structure is sent to and received from the model deployment.

Note that if your model's API expects a single tabular input and output, the associated function will accept single TypeScript objects with properties corresponding to the columns specified for the input if the Enable row-wise processing option is enabled, which is the default. The predictFlightDelaysRowWise function below demonstrates this pattern. Alternatively, consider using an Object or ObjectSet directly in the model API to facilitate use of your model with objects in functions.

The predictFlightDelays function below returns a FunctionsMap, which is the TypeScript v1 type used to return a map keyed by objects or scalar values. In this example, it maps each Flight object to its predicted delay value.

import { Function, Double, FunctionsMap } from "@foundry/functions-api";
import { Flight } from "@foundry/ontology-api";

@Function()
public async predictFlightDelaysRowWise(flight: Flight): Promise<Double> {
    // Prepare the input to match the model function's API.
    // This model function expects a single flight.
    // If you'd like to process multiple flights at a time,
    // edit your model function and uncheck "Enable row-wise processing".

    // Note you can also use an Object directly in the model API
    // to avoid tedious mapping between a model API and an object type's properties.
    const modelInput = {
        "lastArrivalTime": flight.lastArrivalTime,
        "lastExpectedArrivalTime": flight.lastExpectedArrivalTime,
    };
    // Call the Live deployment.
    const modelOutput = await FlightModelDeploymentRowWise(modelInput);
    return modelOutput.prediction;
}

@Function()
public async predictFlightDelays(flights: Flight): Promise<FunctionsMap<Flight, Double>> {
    let functionsMap = new FunctionsMap();
    // Prepare the input to match the model function's API,
    // for the case where row-wise processing is not enabled.

    // Note you can also use an ObjectSet directly in the model API
    // to avoid tedious mapping between a model API and an object type's properties.
    const dfIn = flights.map(flight => ({
        "lastArrivalTime": flight.lastArrivalTime,
        "lastExpectedArrivalTime": flight.lastExpectedArrivalTime,
    }));
    // Call the Live deployment.
    const modelOutput = await FlightModelDeployment(
        {"df_in": dfIn}
    );
    for (let i = 0; i < flights.length; i++) {
        functionsMap.set(flights[i], modelOutput.df_out[i].prediction);
    }
    return functionsMap;
}

Note the above example assumes the following Model API:

import palantir_models as pm


class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        inputs = {
            "df_in": pm.Pandas(columns=[("lastArrivalTime", datetime.datetime), ("lastExpectedArrivalTime", datetime.datetime)])
        }
        outputs = {
            "df_out": pm.Pandas(columns=[("prediction", float)])
        }
        return inputs, outputs
    ...

If the function is registered to an ontology¶

In this case, both the import and the query syntax need to be updated as detailed by the comments in the snippet below:

import { Function, Double } from "@foundry/functions-api";
// Add the Queries import to use an ontology-bound model function
import { Queries, Flight } from "@foundry/ontology-api";

export class MyFunctions {
    @Function()
    public async predictFlightDelays(flight: Flight): Promise<Double> {
        // Call your model by API Name from Queries
        const modelOutput = await Queries.flightModelDeployment({
            "df_in": [
                {
                    "lastArrivalTime": flight.lastArrivalTime,
                    "lastExpectedArrivalTime": flight.lastExpectedArrivalTime,
                },
            ]
        });
        return modelOutput.df_out[0].prediction;
    }
}

Migrating model functions to ontology-bound functions¶

When you migrate a space-bound model function to an ontology-bound function from the user interface, existing published versions of TypeScript v1 functions that use the model will continue to work. However, the import syntax will no longer be recognized, meaning preview and tagging new releases of the repository consuming the model function will no longer work.

To update your TypeScript v1 function after migration:

Open your code repository and select the Resource imports sidebar.
Select the newly created version of the model function, by updating the resources.json file to the new version.
Update your function code to use the query function syntax as detailed above, or see the dedicated documentation on calling a query function for more details.

:::callout{theme="warning"} Direct model function usage through the Foundry Platform SDK and the Functions.Query ↗ method will break immediately upon migration. This is because this consumption pattern refers to the function by its API name, which is migrated globally across all model function versions at once. To remediate these consumers, update the API name to its new value after the migration. :::

Performance considerations¶

Models are executed as part of the runtime of the function, therefore all standard limits apply. If your function backs an Action, there are further limits on the number of resulting edits. When calling live deployments, model input and output data is sent through the network with an upper limit of 50 MB. Including that additional throughput, the total execution time of the function cannot exceed 30 seconds. If you wish to increase this timeout limit per function, contact your Palantir representative.

中文翻译¶

模型函数¶

您可以通过在运行时调用模型的函数，在本体（Ontology）上下文中部署模型。模型函数是围绕实时模型部署自动生成的封装器，可导入到函数仓库中并从代码中调用。这使得您能够围绕模型预测添加自定义业务逻辑、将模型与本体对象集成，或编排多个模型调用。

概述¶

模型函数可从两种类型的部署中发布：

直接模型部署： 直接从模型页面发布。
建模目标实时部署： 从建模目标中的部署详情页面发布。

两种方法都会创建一个与模型具有相同输入和输出API的函数。有关函数行为、版本升级和配置选项的详细信息，请参阅模型函数开发者指南。

模型函数在TypeScript v1、TypeScript v2和Python函数中均得到完全支持。

在仓库中导入实时部署¶

一旦为实时部署创建了函数（无论是在模型本身上还是在建模目标中），必须将其导入到特定仓库中才能使用。在仓库左侧边栏的资源导入菜单中选择添加和查询函数。模型可通过发布时选择的函数名称进行搜索。请注意，Python和TypeScript v2仓库仅支持与本体关联的模型函数，如下节所述。

:::callout{title="注意" theme="neutral"} 对于TypeScript v1仓库，也可以通过选择模型来导入模型函数，这在功能上等同于在查询函数下导入。

在建模目标中使用API名称卡片而非推荐的模型发布对话框的旧版模型函数仍可在建模目标部分下导入，但正在逐步淘汰。 :::

本体绑定或空间绑定函数¶

从2026年2月起，所有新的模型函数都将与本体绑定。这是使用TypeScript v2和Python函数的先决条件，这些函数只允许导入本体资源。在此日期之前，模型函数与模型的空间绑定。TypeScript v1允许导入两种类型的模型函数，但导入和使用语义略有不同，详见下文。

要检查函数是否绑定到本体，请导航到您的模型：未绑定到本体的模型函数将指示有可用的迁移。了解更多关于将函数迁移为本体绑定的信息。

从Python或TypeScript v2函数调用模型函数¶

一旦为实时部署创建了函数，必须将其导入到特定仓库中才能使用。然后可以像任何查询函数一样查询它。

示例代码：Python¶

from functions.api import function, Double
from foundry_sdk_runtime import AllowBetaFeatures
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Flight


@function(beta=True)
def predict_flight_delays(flight: Flight) -> Double:
    # 准备输入以匹配模型函数的API。
    model_output = FoundryClient().ontology.queries.flight_model_deployment(
        df_in=[
            {
                "lastArrivalTime": flight.last_arrival_time,
                "lastExpectedArrivalTime": flight.last_expected_arrival_time,
            },
        ]
    )
    return model_output.df_out[0].prediction

示例代码：TypeScript v2¶

import { Client } from "@osdk/client";
import { Double } from "@osdk/functions";
import { flightModelDeployment, Flight } from "@ontology/sdk";

async function predictFlightDelays(client: Client, flight: Flight): Promise<Double> {
    // 准备输入以匹配模型函数的API。
    const modelOutput = await client(flightModelDeployment).executeFunction({
        "df_in": [
            {
                "lastArrivalTime": flight.lastArrivalTime,
                "lastExpectedArrivalTime": flight.lastExpectedArrivalTime,
            },
        ]
    });
    return modelOutput.df_out[0].prediction;
}

export default predictFlightDelays;

编写模型支持的TypeScript v1函数¶

如果模型函数已注册到空间¶

我们首先需要导入函数：

// 如果模型函数绑定到空间而非本体，
// 请从资源导入侧边栏复制导入代码片段。

然后，编写一个函数，该函数接收一个航班，为模型准备数据，并解释模型执行的结果。模型作为异步函数导入，该函数遵循模型的输入输出规范或API。由此，TypeScript可以在编译时确保向模型部署发送和从模型部署接收正确的数据结构。

请注意，如果您的模型API期望单个表格输入和输出，并且启用了启用逐行处理选项（默认启用），则关联的函数将接受单个TypeScript对象，其属性对应于为输入指定的列。下面的predictFlightDelaysRowWise函数演示了此模式。或者，考虑直接在模型API中使用Object或ObjectSet，以便于在函数中将模型与对象一起使用。

下面的predictFlightDelays函数返回一个FunctionsMap，这是TypeScript v1中用于返回以对象或标量值为键的映射的类型。在此示例中，它将每个Flight对象映射到其预测的延误值。

import { Function, Double, FunctionsMap } from "@foundry/functions-api";
import { Flight } from "@foundry/ontology-api";

@Function()
public async predictFlightDelaysRowWise(flight: Flight): Promise<Double> {
    // 准备输入以匹配模型函数的API。
    // 此模型函数期望单个航班。
    // 如果您希望一次处理多个航班，
    // 请编辑您的模型函数并取消选中"启用逐行处理"。

    // 注意，您也可以直接在模型API中使用Object，
    // 以避免在模型API和对象类型的属性之间进行繁琐的映射。
    const modelInput = {
        "lastArrivalTime": flight.lastArrivalTime,
        "lastExpectedArrivalTime": flight.lastExpectedArrivalTime,
    };
    // 调用实时部署。
    const modelOutput = await FlightModelDeploymentRowWise(modelInput);
    return modelOutput.prediction;
}

@Function()
public async predictFlightDelays(flights: Flight): Promise<FunctionsMap<Flight, Double>> {
    let functionsMap = new FunctionsMap();
    // 准备输入以匹配模型函数的API，
    // 适用于未启用逐行处理的情况。

    // 注意，您也可以直接在模型API中使用ObjectSet，
    // 以避免在模型API和对象类型的属性之间进行繁琐的映射。
    const dfIn = flights.map(flight => ({
        "lastArrivalTime": flight.lastArrivalTime,
        "lastExpectedArrivalTime": flight.lastExpectedArrivalTime,
    }));
    // 调用实时部署。
    const modelOutput = await FlightModelDeployment(
        {"df_in": dfIn}
    );
    for (let i = 0; i < flights.length; i++) {
        functionsMap.set(flights[i], modelOutput.df_out[i].prediction);
    }
    return functionsMap;
}

请注意，上述示例假设以下模型API：

import palantir_models as pm


class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        inputs = {
            "df_in": pm.Pandas(columns=[("lastArrivalTime", datetime.datetime), ("lastExpectedArrivalTime", datetime.datetime)])
        }
        outputs = {
            "df_out": pm.Pandas(columns=[("prediction", float)])
        }
        return inputs, outputs
    ...

如果函数已注册到本体¶

在这种情况下，导入和查询语法都需要更新，如下面代码片段中的注释所述：

import { Function, Double } from "@foundry/functions-api";
// 添加Queries导入以使用本体绑定的模型函数
import { Queries, Flight } from "@foundry/ontology-api";

export class MyFunctions {
    @Function()
    public async predictFlightDelays(flight: Flight): Promise<Double> {
        // 通过Queries中的API名称调用您的模型
        const modelOutput = await Queries.flightModelDeployment({
            "df_in": [
                {
                    "lastArrivalTime": flight.lastArrivalTime,
                    "lastExpectedArrivalTime": flight.lastExpectedArrivalTime,
                },
            ]
        });
        return modelOutput.df_out[0].prediction;
    }
}

将模型函数迁移为本体绑定函数¶

当您从用户界面将空间绑定的模型函数迁移为本体绑定的函数时，使用该模型的TypeScript v1函数的现有已发布版本将继续工作。但是，导入语法将不再被识别，这意味着预览和标记使用该模型函数的仓库的新版本将不再工作。

迁移后更新您的TypeScript v1函数：

打开您的代码仓库并选择资源导入侧边栏。
通过将resources.json文件更新为新版本，选择新创建的模型函数版本。
更新您的函数代码以使用上述的查询函数语法，或参阅关于调用查询函数的专门文档了解更多详情。

:::callout{theme="警告"} 通过Foundry平台SDK和Functions.Query ↗方法的直接模型函数使用将在迁移后立即中断。这是因为这种消费模式通过其API名称引用函数，而该名称会在所有模型函数版本中一次性全局迁移。要修复这些消费者，请在迁移后将API名称更新为其新值。 :::

性能考虑¶

模型作为函数运行时的一部分执行，因此所有标准限制均适用。如果您的函数支持操作（Action），则对生成的编辑数量有进一步限制。调用实时部署时，模型输入和输出数据通过网络传输，上限为50 MB。包括该额外吞吐量在内，函数的总执行时间不能超过30秒。如果您希望增加每个函数的超时限制，请联系您的Palantir代表。