循序渐进 · 教学 · 函数(十七)

用 Platform SDK 调用平台 API

除了操作本体,函数还能反向调用 Foundry 平台自身的 API(读写数据集、管资源等)。这篇讲安装、初始化客户端、以及客户端权限。

全部目录 ← 上一篇 用 Platform SDK 调用平台 API 下一篇 →
本文来源 · Source 内容整理自 Palantir Foundry 官方文档:
https://www.palantir.com/docs/foundry/functions/platform-sdk/
原始标题:Language-agnostic features > Use platform APIs with the Foundry platform SDK

先记住这几条

① 平台 SDK ≠ 本体 SDK
OSDK 操作本体对象,Platform SDK 操作平台资源(数据集、服务等)。
② 先初始化 client
凭据与端点由环境提供,初始化后才能调用。
③ 客户端本身有权限边界
SDK 能做什么,取决于运行它的主体有什么权限。
④ Python 版本要核对
Python SDK 对解释器版本有兼容要求。
0

写在前面

Foundry 的 API 暴露了丰富的功能,你可以通过函数搭配 Foundry platform SDK 库来使用。借助 platform SDK,你可以构建用于管理或治理工作流的函数、与调度和构建交互、访问媒体集,等等。

TypeScript v1 函数不支持一等身份认证。对于这类工作流,我们建议使用 Python 函数与 TypeScript v2 函数。

1

安装 SDK

安装 SDK

要点:安装步骤,注意 Python 版本兼容性要求。

要安装 Foundry platform SDK,请在代码仓库中打开 Libraries 侧边栏,搜索 SDK 名称:Python 对应 foundry-platform-sdk,TypeScript 对应 @osdk/foundry

Libraries 搜索面板,正在搜索 Python 版 platform SDK。
Libraries 搜索面板,正在搜索 Python 版 platform SDK。
Libraries 搜索面板,正在搜索 TypeScript 版 platform SDK。
Libraries 搜索面板,正在搜索 TypeScript 版 platform SDK。

Python version compatibility

Python 版 foundry-platform-sdk 需要 Python 3.9 或更高版本。对 Python 3.14 的支持从 foundry-platform-sdk 1.93.0 版本开始。更早的 SDK 版本在 Python 3.14 下可能返回 typing 模块错误。要解决这些错误,请升级到 1.93.0 或更高版本;或者改用 Python 3.11、3.12 或 3.13。

2

初始化客户端

初始化客户端

要点:拿到可用的 client 实例。

你的函数需要身份认证才能与 Foundry API 交互。这一过程需要实例化一个经过认证的「客户端(client)」,通过它你可以用 SDK 向 Foundry API 发起请求。在 TypeScript v2 仓库中,这需要 @osdk/client 库,它应当已预先安装。你可以查找绿色图钉来确认:

TypeScript 用的身份认证库。
TypeScript 用的身份认证库。
3

调用平台 API

调用平台 API

要点:用 client 发起调用,以及客户端权限的边界。

函数完成认证后,你就可以开始使用 Foundry API。下面的示例展示了如何在 Python 和 TypeScript 中调用语言模型或查询媒体集:

import {
    Client, // 若你的函数与 Ontology 交互则使用 Client
    PlatformClient // 若你的函数不与 Ontology 交互则使用 PlatformClient
} from "@osdk/client";
import { Functions } from "@osdk/foundry";

export default async function useLlm(
    client: PlatformClient, // 该参数由 Foundry 在运行时填充
    prompt: string
): Promise<string> {

    const promptMessage = [
        {
            role: "USER",
            content: prompt
        }
    ];
    const result = await Functions.Queries.execute(
        client,
        "com.foundry.languagemodelservice.models.gpt41.CreateChatCompletion",
        {
            parameters: {
                messages: promptMessage
            }
        },
        {
            preview: true, // 仅对不稳定端点需要,详见 API 参考
        }
    );
    return result.value["completion"] as string;
}
from foundry_sdk import FoundryClient

@function
def media_item_to_base64(media_item_rid: str, media_set_rid: str) -> str:
    foundry_client = FoundryClient()

    result = foundry_client.media_sets.MediaSet.read(
        media_set_rid=media_set_rid,
        media_item_rid=media_item_rid,
        preview=True  # 仅对不稳定端点需要,详见 API 参考
    )

    # 将二进制流转换为 base64 编码字符串
    base64_encoded = base64.b64encode(result).decode('utf-8')

    return base64_encoded

Client permissions

在运行时由 Foundry 传入的 TypeScript v2 客户端,以及在代码中初始化的 Python 客户端,拥有以下权限范围:

  • api:admin-read
  • api:functions-read
  • api:ontologies-read
  • api:orchestration-read
  • api:usage:mediasets-read
  • api:usage:ontologies-write

每个平台 API 端点都需要特定的权限范围才能访问。这些范围的说明可在 API 参考中查阅。

Foundry 函数不支持通过 api:usage:datasets-read 范围直接读取数据集。数据集读取会返回权限错误。代码在 Code Workspaces 实时预览中可能成功,因为它以你的用户上下文和完整权限范围运行;但作为已部署函数运行时则会失败,因为已部署函数使用的是受限权限。

延伸阅读 · 相关页面

按主题横向跳转,不必顺着目录一篇篇读。

常见问题速答 · FAQ

关于「用 Platform SDK 调用平台 API」,读者最常问的几个问题。

安装 SDK是什么?
安装步骤,注意 Python 版本兼容性要求。要安装 Foundry platform SDK,请在代码仓库中打开 Libraries 侧边栏,搜索 SDK 名称:Python 对应 foundry-platform-sdk,TypeScript 对应 @os…
初始化客户端是什么?
拿到可用的 client 实例。你的函数需要身份认证才能与 Foundry API 交互。这一过程需要实例化一个经过认证的「客户端(client)」,通过它你可以用 SDK 向 Foundry API 发起请求。
调用平台 API是什么?
用 client 发起调用,以及客户端权限的边界。函数完成认证后,你就可以开始使用 Foundry API。下面的示例展示了如何在 Python 和 TypeScript 中调用语言模型或查询媒体集。