関数

関数を登録する

関数実行モードで実行する場合は、Foundry のほかの場所から呼び出せるように、Compute Module に関数を登録する必要があります。このページでは、Compute Module の関数を手動で登録する2つの方法を説明します。

Compute Modules SDK は関数のスキーマを自動的に推論するため、関数の登録が容易になります。Compute Modules SDK を使用している場合は、後述の関数スキーマの自動推論セクションを確認してください。

Compute Modules アプリケーションから関数を登録する

関数ページから、Compute Module の関数を手動で登録できます。関数を追加を選択すると、カスタム関数作成パネルが開きます。

1. 関数名： 呼び出す関数の名前です。通常は、Compute Module 内の関数の名前と一致させます。
2. 入力値： Compute Module の関数に引数として渡す入力パラメーターです。

Compute Module の関数への入力は JSON オブジェクトにまとめられます。追加する各入力は、関数に渡される入力オブジェクトのプロパティに対応します。以下の例では、左側に関数の入力、右側に対応する関数に渡される JSON オブジェクトを示しています。

example_function_payload.json

Copied!
1
2
3
4
5
{
    "arg1": "hello",
    "arg2": 2,
    "arg3": "1969-07-20"
}

3. 出力： 関数の戻り値の型です。
4. API 名： API名は、TypeScript 関数を介した呼び出しなど、Foundry 内のほかのコードから関数を呼び出すための関数ロケーターです。 Compute Module の API 形式は com.<namespace>.computemodules.<MyApiName> という構造に従い、以下の命名規則に準拠する必要があります。

• 名前空間： すべて小文字で、特殊文字を含めてはいけません。
• MyApiName: キャメルケースで、特殊文字を含めてはいけません。

関数を定義したら、テストタブに切り替えて関数の呼び出しを試すことや、保存を選択して関数を保存し、Foundry から呼び出せるようにすることができます。

JSON を使用して関数を登録する

Compute Module 内から HTTP POST リクエストを送信して、関数スキーマを手動で定義することもできます。通常、これが必要になるのは独自のクライアントを作成する場合のみです。HTTP リクエストについては、関数スキーマの POSTドキュメントを確認してください。

このエンドポイントは、ペイロードとして JSON 配列を受け取ります。配列の各要素は、Compute Module 内の関数の仕様に対応します。Python SDK ↗は、この JSON ペイロードを組み立てる方法を確認するための参考になります。

関数のデータ型リファレンス

以下のテーブルは、関数の入力と出力のデータ型と、それらが HTTP 経由で Compute Module に渡される際のシリアライズ形式との対応を示しています。

Records、dataclasses、TypedDict、@JsonProperty 注釈などのデータ型の定義方法の詳細については、Python SDK、Java SDK、TypeScript SDKのガイドを確認してください。

関数スキーマの自動推論

Compute Module では、関数の定義と登録を簡単に行うことができ、スキーマの自動推論と Foundry の Compute Module アプリケーションとの統合が可能です。このセクションでは、開発をよりスムーズに進められるように、関数の自動登録と高度な使用シナリオについて詳しく説明します。

Compute Module では、コード内で直接 JSON 構造を使用して関数のスキーマを定義できます。この方法には、次の利点があります。

• スキーマ定義の一元化
• メンテナンスと更新の容易さ
• Foundry との自動統合

Compute Module の起動時に単純な POST 呼び出しを行うと、モジュールはエンドポイントの呼び出しからスキーマを自動的に推論し、Compute Module アプリケーションで関数として利用できるようにします。これにより、開発者はエンドポイントのスキーマを一度定義するだけで、Foundry に簡単にインポートできます。

例：関数スキーマを追加する

入力が x と y（2個の整数）で、出力が文字列の単純な add 関数を考えてみます。以下の例は、この関数の JSON スキーマを定義する方法を示しています。

schemas.json

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "functionName": "add",
    "inputs": [
        {
            "name": "x",
            "dataType": {
                "integer": {},
                "type": "integer"
            },
            "required": true,
            "constraints": []
        },
        {
            "name": "y",
            "dataType": {
                "integer": {},
                "type": "integer"
            },
            "required": true,
            "constraints": []
        }
    ],
    "output": {
        "single": {
            "dataType": {
                "string": {},
                "type": "string"
            }
        },
        "type": "single"
    }
}

JSON スキーマを定義したら、app.py ファイルで HTTP POST リクエストを送信して Foundry に登録します。

if __name__ == "__main__":
    certPath = os.environ['DEFAULT_CA_PATH']
    postSchemaUri = os.environ["POST_SCHEMA_URI"]

    with open('schemas.json', 'r') as file:
        SCHEMAS = json.load(file)

    requests.post(
        postSchemaUri,
        json=SCHEMAS,
        headers={"Module-Auth-Token": moduleAuthToken, "Content-Type": "application/json"},
        verify=certPath
    )

本番環境では、必ず例外処理を行い、適切なエラーログ記録を実装してください。

この関数は、次の制約に従っていることに注意してください。

• スキーマ定義関数では、サポートされている Python のデータ型（下のテーブルを参照）を使用して、すべての入力のデータ型と出力のデータ型を宣言する必要があります。
• 各関数のスキーマ定義では、Python の関数名と一致する functionName を宣言する必要があります。

Compute Module SDK による関数の自動検出

Compute Module SDK には、関数を自動検出する機能が含まれています。定義された関数とその入出力のデータ型を調べ、変更せずに Foundry の関数としてインポートできる FunctionSpecs に変換します。

この機能を円滑に動作させるには、SDK 内での型推論の仕組みと、入力および出力のデータ型を正しく定義する方法を理解しておく必要があります。次の考慮事項を確認してください。

• 入力クラスは複合型である必要があります。Foundry の関数仕様では、関数の入力のデータ型が複合型であることが必須です。関数が単一のプリミティブ型のみを入力として受け取る場合は、関数スキーマが正しく推論されるように、そのパラメーターを複合型でラップしてください。
• 入力のデータ型の定義

✅ 入力のデータ型として TypedDict を使用

Copied!
1
2
3
4
5
6
7
8
9
10
# app.py
from typing import TypedDict
from compute_modules.annotations import function

class HelloInput(TypedDict):
    planet: str

@function
def hello(context, event: HelloInput) -> str:
    return "Hello " + event["planet"] + "!"

✅ 入力のデータ型として dataclass を使用

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# app.py
from compute_modules.annotations import function
from dataclasses import dataclass
import datetime
import decimal

@dataclass
class TypedInput:
    bytes_value: bytes
    bool_value: bool
    date_value: datetime.date
    decimal_value: decimal.Decimal
    float_value: float
    int_value: int
    str_value: str
    datetime_value: datetime.datetime
    other_date_value: datetime.datetime

@function
def typed_function(context, event: TypedInput) -> str:
    diff = event.other_date_value - event.datetime_value
    return f"The difference between the provided dates is {diff}"

✅ クラスとコンストラクターの両方に型ヒントがある通常のクラス

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# app.py
from compute_modules.annotations import function

class GoodExample:
    some_flag: bool
    some_value: int

    def __init__(self, some_flag: bool, some_value: int) -> None:
        self.some_flag = some_flag
        self.some_value = some_value

@function
def typed_function(context, event: GoodExample) -> int:
    return event.some_value

❌ クラスの型ヒントがない Python クラスは避けてください

Copied!
1
2
3
4
5
# app.py
# これは例外を発生させます
class BadClassNoTypeHints:
    def __init__(self, arg1: str, arg2: int):
        ...

❌ コンストラクターに Args がある Python クラスは避けてください

Copied!
1
2
3
4
5
6
7
8
# app.py
# これは例外を発生させます
class BadClassArgsInit:
    arg1: str
    arg2: int

    def __init__(self, arg1: str, arg2: int, *args):
        ...

❌ コンストラクターに Kwargs がある Python クラスは避けてください

Copied!
1
2
3
4
5
6
7
8
# app.py
# これは例外を発生させます
class BadClassKwargsInit:
    arg1: str
    arg2: int

    def __init__(self, arg1: str, arg2: int, **kwargs):
        ...

• ストリーミング出力： Compute Module Python SDK は、出力が任意の Iterable 型（dict を除く）の場合にストリーミング出力をサポートします。結果のストリーミングを有効にするには、@function を @function(streaming=True) に変更します。詳細は、SDK ドキュメント ↗を参照できます。ストリーミング関数が正しく登録されるように、戻り値の型には任意の Iterable 型を使用してください。これにより、出力は Foundry の Array として登録されます。

✅ 出力タイプとして通常の Iterable を使用

Copied!
1
2
3
4
5
6
7
8
9
10
11
# app.py
# 出力は Foundry Array として登録されます
from compute_modules.annotations import function

@function(streaming=True)
def get_string_list(context, event) -> list[str]:
    return [f'string {i}' for i in range(10)]

@function(streaming=True)
def get_string_set(context, event) -> set[str]:
    return {'string 1', 'string 2', 'string 3'}

✅ 出力タイプとしてジェネレーターを使用

Copied!
1
2
3
4
5
6
7
8
9
# app.py
# ジェネレーターは Iterable です。出力は Foundry Array として登録されます
from compute_modules.annotations import function
import typing

@function(streaming=True)
def string_generator(context, event) -> typing.Iterable[str]:
    for i in range(10):
        yield f'string {i}'

⚠️ 出力タイプとして通常の Iterable を使用しているが、ストリーミングが有効になっていない

Copied!
1
2
3
4
5
6
7
# app.py
# これは有効です。出力は Foundry Array として登録されますが、結果はストリーミングされません
from compute_modules.annotations import function

@function
def get_string_list(context, event) -> list[str]:
    return [f'string {i}' for i in range(10)]

❌ 出力タイプとしてジェネレーターを使用しているが、ストリーミングが有効になっていない

Copied!
1
2
3
4
5
6
7
8
9
10
# app.py
# ジェネレーターはオブジェクト全体を JSON にシリアル化できません。非ストリーミング関数ではオブジェクト全体をシリアル化するため、使用できません
# 出力タイプは Foundry Array として登録されますが、実行時に例外が発生します
from compute_modules.annotations import function
import typing

@function
def string_generator(context, event) -> typing.Iterable[str]:
    for i in range(10):
        yield f'string {i}'

関数を登録する

次の手順に従って関数を登録します。

1. Compute Module が実行中であることを確認してください。
2. Compute Module アプリケーションの関数タブに移動します。
3. 検出された関数のリストに、定義した関数が表示されるはずです。

4. 登録する関数を選択して、ポップアップウィンドウを開きます。
5. ウィンドウでインポートを選択します。

サーバーを統合する

通常、Compute Module は、Compute Module API からジョブを取得するクライアントを使用します。ただし、クライアント、アダプター、SDK を必要とせずに、Compute Module で HTTP サーバーを使用することもできます。

OpenAPI 仕様

OpenAPI Specification (OAS) ↗ は、HTTP API を列挙するためのオープンソースフレームワークです。まず、サーバーの OpenAPI 仕様を指定する必要があります。サーバーの OpenAPI 仕様を作成する方法はさまざまです。OpenAPI ドキュメントに従って手動または LLM アシスタントを使って作成するほか、汎用の OpenAPI ジェネレーターや言語固有のライブラリを使用することもできます。

Compute Module で使用するには、OpenAPI 仕様が次のすべての制約を満たしている必要があります。

• OpenAPI Specification バージョン 3.0.0 以降を使用すること。
• URL が http://localhost:port の形式であるサーバーを1個だけ含めること。
• 各操作に operationId を含めること。これが Foundry での関数名になります。
• GET、PUT、POST、DELETE メソッドのみを使用すること。
• すべてのパラメーターに schema フィールドを含め、場所が cookie のパラメーターを使用しないこと。
• anyOf、oneOf、allOf スキーマ、または複数のデータ型を持つスキーマを使用しないこと。
• すべてのエンドポイントにレスポンスコードを1個だけ含めること（Foundry の関数は単一の出力スキーマのみをサポートするため）。そのコンテンツタイプは application/json である必要があります。

以下は、Flask を使用する Python サーバーと、それに対応する OpenAPI 仕様の例です。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
from flask import Flask, request, jsonify
import uuid

app = Flask(__name__)

books = {}


@app.route('/books', methods=['POST'])
def add_book():
    data = request.json

    user_id = request.headers.get('User-ID')
    title = data.get('title')
    author = data.get('author')
    published_year = int(data.get('published_year'))

    book_id = str(uuid.uuid4())

    books[book_id] = {
        'title': title,
        'author': author,
        'published_year': published_year,
        'added_by': user_id
    }
    return jsonify(book_id), 200


@app.route('/books/<book_id>', methods=['GET'])
def get_book(book_id):
    return jsonify(books.get(book_id)), 200


if __name__ == '__main__':
    app.run(port=8000)

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
{
  "openapi": "3.0.0",
  "servers": [
    {
      "url": "http://localhost:8000"
    }
  ],
  "paths": {
    "/books": {
      "post": {
        "operationId": "addBook",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "author": {
                    "type": "string"
                  },
                  "published_year": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "User-ID",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/books/{book_id}": {
      "get": {
        "operationId": "getBook",
        "parameters": [
          {
            "name": "book_id",
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "author": {
                      "type": "string"
                    },
                    "published_year": {
                      "type": "integer"
                    },
                    "added_by": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

サーバーを使用する

Docker イメージをビルドするときは、server.openapi イメージラベルを使用し、その値に OpenAPI 仕様を設定します。以下は、サーバーの仕様を付加した、上記の例の Dockerfile です。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
FROM python:3.12

EXPOSE 8000

RUN pip install flask
COPY src .

USER 5000

LABEL server.openapi='{"openapi":"3.0.0","servers":[{"url":"http://localhost:8000"}],"paths":{"/books":{"post":{"operationId":"addBook","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"author":{"type":"string"},"published_year":{"type":"integer"}}}}}},"parameters":[{"name":"User-ID","in":"header","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"string"}}}}}}},"/books/{book_id}":{"get":{"operationId":"getBook","parameters":[{"name":"book_id","in":"path","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"author":{"type":"string"},"published_year":{"type":"integer"},"added_by":{"type":"string"}}}}}}}}}}}'

CMD ["python", "app.py"]

通常どおりにイメージをビルド、公開、選択し、Compute Module の設定を保存します。次に、関数タブに移動し、OpenAPI 仕様から検出を選択します。その後、関数をインポートし、関数の生成元となった OpenAPI 仕様を表示できます。これらの関数は Foundry プラットフォーム全体で使用できます。

Functions CLI

Functions CLI は、Compute Module のアーティファクトの公開を支援するスタンドアロンツールです。主な役割は次の2つです。

1. ソースコードに対して静的推論を実行し、関数仕様を生成すること。
2. Foundry が必要とするメタデータラベルを付加した Docker イメージをビルドして公開すること。

Functions CLI は、ローカルの開発ワークフローで使用することも、CI/CD パイプラインに統合して Compute Module のビルドと公開のプロセスを自動化することもできます。

Functions CLI にアクセスする

Functions CLI をはじめるには、次の手順を実行します。

1. お使いのプラットフォーム向けの最新バイナリをダウンロードします。
2. バイナリが実行可能であることを確認します。

Copied!
1
chmod +x functions-cli

その後、ターミナルから CLI を直接呼び出せます。

推論

Functions CLI は、ソースコードに対して静的推論を実行し、関数仕様を自動生成できます。これは、Foundry に登録される関数スキーマを調べたり、検証したりする場合に便利です。

関数仕様の推論を実行するには、--opt functions フラグを使用します。SDK を使用する Python Compute Module では、--plugin python_cm フラグを指定します。

次の例では、./src ディレクトリ内の Python ソースコードに対して推論を実行します。

Copied!
1
functions-cli infer --opt functions --plugin python_cm --dir ./src

プランファイルを使用して推論を設定することもできます。

Copied!
1
functions-cli infer --planfile ./infer_plan.yml --dir ./src

出力は関数仕様の JSON 配列です。各仕様には、関数名、データ型を含む入力パラメーター、および出力タイプが含まれます。

ファイルプラグイン

自動推論に頼らずに関数スキーマを手動で定義する場合は、ファイルプラグインを使用できます。この方法では、明示的な型定義を使用して、JSON ファイル内で関数スキーマを指定できます。

次の例は、カスタム型と、その型を使用する関数を含む関数スキーマファイルです。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "types": {
    "Person": {
      "type": "object",
      "fields": {
        "name": { "dataType": "string" },
        "age": { "dataType": "integer" }
      }
    }
  },
  "functions": [
    {
      "functionName": "example_function",
      "inputs": [
        { "name": "text", "dataType": "string", "required": true },
        { "name": "items", "dataType": "list<Person>", "required": true },
        { "name": "metadata", "dataType": "optional<dict<string, string>>", "required": false }
      ],
      "outputs": [
        { "dataType": "dict<string, set<Person>>" }
      ]
    }
  ]
}

ファイルプラグインは、次のデータ型をサポートしています。

これらのデータ型をネストして、dict<string, set<Person>> や optional<list<integer>> などの複雑な構造を作成できます。

ビルド

Functions CLI は、Compute Module 用の Docker イメージをビルドして公開できます。ビルドは、YAML または JSON 形式のプランファイルを使用して設定します。

次の例はビルドプランです。

Copied!
1
2
3
4
5
6
7
8
9
10
name: my-compute-module-image
tag: $(IMAGE_TAG)
registry:
  url: stack-container-registry.palantirfoundry.com
  username: ri.artifacts.main.repository.example-artifact-repo-rid-abc123
auth:
  client_id: $(CLIENT_ID)
  client_secret: $(CLIENT_SECRET)
  host: stack.palantirfoundry.com
kind: python_cm

次のコマンドでビルドを実行します。

Copied!
1
functions-cli build -p ./build_plan.yml -d ./src

ビルドプランの auth セクションは、2つの認証方法をサポートしています。

• OAuth クライアント：client_id、client_secret、host フィールドを使用します。
• トークン：Foundry API トークンを設定した token フィールドを使用します。

タグのインクリメント

タグを手動で指定する代わりに、-t フラグを使用してイメージタグのバージョンを自動的にインクリメントできます。

エンジンのオプション

デフォルトでは、Functions CLI は Docker を使用してイメージをビルドします。Docker デーモンを利用できない場合は、代わりに GoCR エンジンを使用できます。

次の例は、GoCR エンジンを使用するビルドプランです。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
name: my-compute-module-image
tag: 0.0.1
registry:
  url: stack-container-registry.palantirfoundry.com
  username: ri.artifacts.main.repository.example-artifact-repo-rid-abc123
auth:
  token: $(FOUNDRY_TOKEN)
engine:
  gocr:
    base_image: python:3.12
    copy_paths:
      - source: ./src
        dest: /app/client
    entrypoint: ["python", "app.py"]
kind: python_cm

GoCR エンジンは Docker デーモンを必要としないため、Docker-in-Docker が利用できない、または制限されている CI/CD 環境に適しています。

ロギング

デバッグのために、CLI 出力の詳細度を上げることができます。

TypeScript 関数で Compute Module 関数を使用する

前提条件：

• Compute Module アプリケーションで、API名を指定して関数を登録する必要があります。
• ライブプレビューを機能させるには、Compute Module が実行中である必要があります。
• TypeScript コードリポジトリを初期化する必要があります。

リソース生成を有効にする

始める前に、TypeScript コードリポジトリでリソース生成が有効になっていることを確認してください。

• functions.json ファイルを開きます。
• enableResourceGeneration プロパティを true に設定します。

Compute Module 関数をインポートする

TypeScript で Compute Module 関数をインポートするには、次の手順に従います。

1. TypeScript コードリポジトリの左側のパネルで、リソースのインポートタブを見つけて選択します。
2. 追加を選択し、次にクエリ関数を選択すると、オントロジーを選択するポップアップウィンドウが表示されます。

3. Compute Module は特定のオントロジーに紐付いていませんが、インポート処理ではオントロジーを1つ選択する必要があります。ユースケースに適した任意のオントロジーを選択します。
4. Compute Module 関数のAPI名を検索します。
5. 関数を選択します。

6. 選択を確定を選択します。

コードワークスペースを再ビルドする

関数をインポートして使用する

次の例は、Compute Module 関数をインポートして使用する方法を示しています。

// index.ts
import { Function } from "@foundry/functions-api";

// API名: com.mycustomnamespace.computemodules.Add
import { add } from "@mycustomnamespace/computemodules";

export class MyFunctions {
    @Function()
    public async myFunction(): Promise<string> {
        return await add({ x: 50, y: 50 });
    }
}

重要な考慮事項

• プロジェクトの場所： ライブプレビューを正しく機能させるため、Compute Module が TypeScript コードと同じプロジェクト内にあることを確認してください。
• データ型の整合性： TypeScript は厳格な型チェックを適用します。宣言した戻り値の型が Compute Module 関数の実際の戻り値の型と一致していることを確認してください。たとえば、戻り値の型を string として宣言した場合、登録済みの Compute Module 関数は struct 型ではなく string を返す必要があります。
• 非同期操作： Compute Module 関数は通常、非同期です。適切に処理するには、async/await 構文を使用します。