模型弃用与迁移

模型供应商经常会弃用模型，这会影响依赖这些模型的工作流，并要求用户迁移到推荐的替代模型。当供应商宣布模型弃用时，Palantir 会通知受影响的用户，并通过 Upgrade Assistant 识别依赖受影响模型的资源。

收到通知后，我们鼓励用户提前规划，将任何使用即将弃用模型的现有工作流迁移到推荐的替代模型上。用户会收到迁移截止日期的通知，此后将对模型实施一系列 brownout（降级服务）访问限制，以推动剩余工作流完成迁移。

如果在 brownout 截止日期前未采取任何措施，使用已弃用模型的工作流将会失败，并在 brownout 期间输出以下错误消息：

{
    "errorCode": "NOT_FOUND",
    "errorName": "LanguageModelService:LanguageModelNotAvailable",
    "errorInstanceId": "<error instance id>",
    "parameters": {
        "safeParams": "{languageModelRid=<language model rid>, deprecationDate=<deprecation date>, brownoutStart=<brown-out start>, brownoutEnd=<brown-out end>}",
        "unsafeParams": "{}",
        "message": "Unable to use model: language model is in planned deprecation and is currently under a brown-out"
    }
}

同样，如果在供应商的模型弃用日期前未采取任何措施，使用已弃用模型的工作流将会失败，并输出下面的错误消息，直到该工作流迁移到替代模型为止：

{
    "errorCode": "NOT_FOUND",
    "errorName": "LanguageModelService:LanguageModelNotAvailable",
    "errorInstanceId": "<error instance id>",
    "parameters": {
        "safeParams": "{languageModelRid=<language model rid>, deprecationDate=<deprecation date>}",
        "unsafeParams": "{}",
        "message": "Unable to use model: language model is deprecated"
    }
}

模型 brownout 是一种引导用户远离正在被弃用模型的策略。Brownout 会引入刻意的、临时的不稳定性，以发出即将变化的信号，并避免突然中止向那些未对 Upgrade Assistant 中列出的受影响资源采取行动的用户提供服务。

每个模型都遵循特定的 brownout 时间表。要查看正在经历弃用的模型的 brownout 时间表，包括阶段数、开始日期和持续时间，请参阅该已弃用模型的 Upgrade Assistant 描述页面。

要成功从已弃用模型迁移出去并避免关键工作流中断，请执行以下步骤：

1. 识别需要迁移的资源。
2. 导航到受影响的资源。
3. 替换已弃用的模型。

Identify resources that require migration

导航到 Upgrade Assistant，并在 Active upgrades 小节中打开相关的模型弃用页面。在已弃用模型的描述页面上，向下滚动到 Resources 小节，即可看到受此次模型弃用影响的资源列表。

Resource identification criteria

资源会根据以下标准被标记为需要迁移：

• 如果某个资源调用了已弃用的模型，该资源将被标记为 PENDING。这表示该资源中使用的模型仍需迁移。
• 如果某个此前调用了已弃用模型的资源改而调用另一个模型，并且对已弃用模型的最后一次调用发生在 24 小时之前，该资源将被标记为 COMPLETED，因为使用不同的模型表明该资源已完成迁移。

在少数情况下，资源可能被标记为 COMPLETED，随后又回到 PENDING。如果某个资源对已弃用模型发起了新的调用，就可能出现这种情况。为防止这种情况，请确保 Workshop modules 等资源在相关函数保存并发布之后更新到该函数的最新版本。

配置为使用已弃用模型、但在迁移期内未被实际使用的资源不会出现在 Upgrade Assistant 的资源列表中。例如，如果某个 pipeline 配置为使用已弃用模型，但在迁移期内未被构建，它就不会出现在 Upgrade Assistant 的资源列表中，因为它并未主动调用已弃用模型。在这种情况下，我们建议盘点你的生产工作流，并使用下方小节中的工具来了解资源用量，评估是否有必要迁移。

Navigate to the affected resources

在 Upgrade Assistant 描述页面中，选择一个资源以导航到该资源所在的应用。根据资源类型的不同，迁移到新模型的过程可能有所差异。对于每个受影响的资源，你必须确定已弃用模型的使用方式，例如 Pipeline Builder 和 AIP Logic 中的 Use LLM 节点，或 transforms 中的代码引用。你可能需要导航到额外的上游资源，才能为你的工作流选择新模型。

Replace deprecated models

为防止已弃用模型对你工作流造成中断，需要选择一个新模型。Upgrade Assistant 中每个已弃用模型的描述页面都会包含潜在的替代模型，但我们强烈建议在 AIP Evals 中设置评估套件，以确保你为用例使用了最佳模型。

Upgrade Assistant 会识别使用即将弃用模型的资源，而每种资源类型都需要以不同方式解决。部分资源可以直接配置，使用模型选择器即可选择新模型。在其他资源类型中，例如 Workshop modules 或 pipelines，模型可能是从上游资源调用的，比如 AIP Logic functions 或 Code Repositories transforms。在这些情况下，模型选择需要在包含模型配置选项的上游资源中进行。关于资源类型的更多细节，请参阅下方小节。

Model selector supported applications

如果已弃用模型是通过模型选择器选择的，则可以以相同方式选择新模型。在导航到 Logic functions 和 AIP Chatbots（原 AIP Agents）等资源时，打开资源配置设置并使用模型选择器选择新模型。

支持模型选择器的应用包括：

• Pipeline Builder
• AIP Chatbot Studio
• AIP Evals
• AIP Logic
• Workshop
• Quiver
• Marketplace
• Code Workspaces

资源配置设置会在受影响的模型旁显示一个警告，并将其标记为 Sunset。

要选择替代模型，请打开模型选择器并选择一个新模型。

Model usage in Pipeline Builder

对于 Pipeline Builder 资源，Upgrade Assistant 会链接到整个 pipeline，而不是特定的受影响节点。为了在大型 pipeline 中高效地找到相关节点，请使用 Pipeline Builder 的搜索功能。

1. 通过在 Upgrade Assistant 模型弃用页面的资源列表中选择相应项，导航到受影响的 pipeline。

1. 选择 pipeline 图表右上角的搜索图标。<br><br> <img src="./media/model-deprecation-pipeline-search.png" alt="Pipeline Builder 搜索图标。" width="500"> <br><br>

1. 输入 “use LLM” 作为搜索词，查看该 pipeline 中所有 Use LLM 节点的列表。所有搜索结果还会以 pipeline 图表图例中所示的颜色高亮显示。<br><br> <br><br>

1. 从列出的结果中，选择每个节点以在 pipeline 图表中将其高亮显示。右键点击所选节点，并从上下文菜单中选择 Edit。这将打开该节点的配置页面。

1. 导航到 Model 小节，如果该模型正被弃用，模型名称旁会显示一个警告图标。如果存在此警告，请选择 Show configurations，并从 Model type 下拉菜单中选择一个新模型。

1. 对该 pipeline 中所有 Use LLM 节点重复此过程。

1. 保存、部署并重新构建你的 pipeline。

Model usage in Workshop

Workshop 中的模型使用可能来源于 AIP widgets 或被引用的函数，例如 AIP Logic functions。取决于来源不同，模型可以从 widget 配置设置中更改，也可以从上游资源（例如 AIP Logic function 或 AIP Chatbot）的配置设置中更改。你可以通过在 Upgrade Assistant 模型弃用页面的资源列表中选择受影响的 Workshop modules，来导航到它们。进入编辑模式以查看 module 配置设置。

你需要对受影响的 Workshop modules 拥有编辑权限。请遵循以下说明来处理基于函数和基于 widget 的模型使用。

Function-based model usage

1. 要识别某个 Workshop module 中使用的函数，请打开工作区左上角的 Overview 面板。在 Capabilities 小节下，选择 Functions。<br><br> <br><br>

1. 在 Functions 面板中，选择每个函数以查看函数源代码。<br><br> <br><br>

1. 选择函数源代码以导航到源应用，在本例中为 AIP Logic。在该源中，你可以配置模型设置，并在函数使用已弃用模型时选择新模型。

1. 保存并发布该函数的新版本。

1. 回到 Workshop，按步骤 1 所述导航到 Overview 面板中的 Functions 小节。选择已更新的函数，并使用 Bulk update version 小节下的函数版本下拉菜单，为所有变量或 widgets 选择该函数的最新版本。<br><br> <br><br>

1. 对所有列出的函数重复此过程。

Widget-based model usage

基于 widget 的模型配置取决于所使用的 widget 类型。请审阅以下选项，并针对你的 Workshop module 中使用的 widgets 遵循相应说明：

• AIP chatbot： AIP Chatbot widget 使用 chatbots，因此模型配置必须在 AIP Chatbot Studio 的 chatbot 配置设置中进行。
• 在 widget 配置面板中，选择正在使用的 chatbot，以在 Chatbot Studio 中打开它。
• 通过在 chatbot 界面右上角选择 Edit 来编辑该 chatbot。
• 打开 chatbot 配置面板并从模型选择器中选择一个新模型。
• 保存并发布你的 chatbot。

• AIP generated content： 对于 AIP generated content widget，只有当该 widget 使用 Direct to LLM 或 LLM via prompt function 选项时，模型使用才能在 Workshop 中配置。否则，需要在被引用的 Logic function 中配置。<br><br> <br><br>

• Direct to LLM/LLM via prompt function： 可以使用 widget 配置设置中的模型选择器选择新模型。
• Logic： 如果该 widget 使用 Logic 选项，该 Logic function 将列在 Overview 面板中该 module 的函数下。更多细节请参阅基于函数的模型使用小节。

• Free-form analysis： free-form analysis widget 的模型使用可以直接在 Workshop 中配置。在 widget 配置设置中，打开 AIP options 并选择 Enabled 以配置模型设置。然后，从模型选择器中选择一个新模型。<br><br> <br><br>

• Logic - Chain of thought： 该 widget 使用 Logic functions，它们列在 Overview 面板中。更多细节请参阅基于函数的模型使用小节。

请确保在任何改动之后保存并发布你的 Workshop module。

Code-based model usage

对于基于代码的模型使用，Upgrade Assistant 会列出包含该用法的 code repository、code workspace 或下游资源，而不是包含已弃用模型引用的确切代码文件或函数。对于下游资源被标记的情况，请查阅 Workshop 中的模型使用和附加工具小节。对于 code repository 或 workspace 被标记的情况，请打开 Upgrade Assistant 资源列表中列出的 repository 或 workspace。在 repository 或 workspace 中，你可以将已弃用模型的使用实例替换为新模型。

TypeScript v1 与 TypeScript v2 选择模型的方式不同，这改变了迁移所需的工作：

• TypeScript v1 在 import 语句中指明模型名称，因此已弃用模型必须在 import 处以及所有使用它的调用点进行替换。更多细节请查阅 TypeScript v1 语言模型文档；下面的示例使用的是旧版语言模型导入方式。
• TypeScript v2 通过代理端点调用模型，并使用模型别名来选择它。该别名解析为在 Resource imports 面板的 Platform SDK 标签页中配置的模型 RID，因此模型名称不会出现在函数体中。替换已弃用模型只需改动单个别名引用，而无需改动每个调用点。请求参数（例如 temperature 和 token 上限）遵循代理端点的格式，而不是 TypeScript v1 的 params 对象。

TypeScript v2 示例中使用的 openai 库并非预装。请从左侧面板的 Libraries 小节安装它。

模型的选择和使用方式如下方的 TypeScript v1、TypeScript v2 和 Python 示例所示：

import { Function } from "@foundry/functions-api"
// A deprecated model is imported
import { GPT_4_5 } from "@foundry/models-api/language-models"

/**
 * Used to send a text completion request to the model based on user input
 * @param {string} userInput - Text input to send to model
 */
export class MyFunctions {
    @Function()
    public async createChatCompletion(userInput: string): Promise<string | undefined> {
        // Deprecated model usage
        const response = await GPT_4_5.createChatCompletion({
            params: {
                "temperature": 0,
                "maxTokens": 1000,
            },
            messages: [{ role: "USER", contents: [{ text: userInput }],  }],
        });
        return response.choices[0].message.content;
    }
}

import { PlatformClient } from "@osdk/client";
import OpenAI from "openai";
import { Aliases } from "@osdk/functions";
import { getFoundryToken, getOpenAiBaseUrl, createFetch } from "@osdk/language-models";

export default async function createChatCompletion(client: PlatformClient, userInput: string): Promise<string> {
    const oaiClient = new OpenAI({
        apiKey: await getFoundryToken(client),
        baseURL: getOpenAiBaseUrl(client),
        fetch: createFetch(client),
    });

    const completion = await oaiClient.chat.completions.create({
        // Deprecated model usage through its alias
        model: Aliases.model("gpt45").rid,
        messages: [
            { role: "user", content: userInput },
        ],
        max_completion_tokens: 1000,
    });

    return completion.choices[0]?.message.content ?? "";
}

from transforms.api import transform, Input, Output
from palantir_models.transforms import OpenAiGptChatLanguageModelInput
from palantir_models.models import OpenAiGptChatLanguageModel
from language_model_service_api.languagemodelservice_api_completion_v3 import GptChatCompletionRequest
from language_model_service_api.languagemodelservice_api import ChatMessage, ChatMessageRole

@transform(
    reviews=Input("Input Dataset Rid"),
    # Deprecated model usage
    model=OpenAiGptChatLanguageModelInput("ri.language-model-service..language-model.gpt-4-5"),
    output=Output("Output dataset rid or path"),
)
def compute_sentiment(ctx, reviews, model: OpenAiGptChatLanguageModel, output):
    def get_completions(review_content: str) -> str:
        system_prompt = "Take the following review determine the sentiment of the review"
        request = GptChatCompletionRequest(
            [ChatMessage(ChatMessageRole.SYSTEM, system_prompt), ChatMessage(ChatMessageRole.USER, review_content)]
        )
        resp = model.create_chat_completion(request)
        return resp.choices[0].message.content

    reviews_df = reviews.pandas()
    reviews_df['sentiment'] = reviews_df['review_content'].apply(get_completions)
    out_df = ctx.spark_session.createDataFrame(reviews_df)
    return output.write_dataframe(out_df)

如果你不确定如何导入和使用新模型，请导航到 Model Catalog 应用查看 Palantir 提供的模型使用示例。在你的 code repository 或 workspace 中搜索已弃用模型的使用，并将所有实例替换为推荐的模型或你选择的模型。取决于你的工作流，这一过程可能涉及创建并向你的 repository 或 workspace 合并一个新分支，以便上游函数或 transform 的使用反映这些改动。

在上面的示例中，使用的是已弃用模型 GPT-4.5。升级到 GPT-4.1 在每种语言中需要不同的改动。

在 TypeScript v2 中，将 GPT-4.1 导入到 repository。导入对话框会为新模型创建一个别名。将传给 Aliases.model() 的别名名称更新为新别名。函数体中命名的是别名而不是模型。因此，这次更新只需要改动一行，而不是改动 import 语句和每个 TypeScript v1 调用点。

更新后的示例如下所示：

import { Function } from "@foundry/functions-api"
// Import a new model
import { GPT_4_1 } from "@foundry/models-api/language-models"

/**
 * Used to send a text completion request to the model based on user input
 * @param {string} userInput - Text input to send to model
 */
export class MyFunctions {
    @Function()
    public async createChatCompletion(userInput: string): Promise<string | undefined> {
        // Replace usage of the deprecated model with the new model.
        const response = await GPT_4_1.createChatCompletion({
            params: {
                "temperature": 0,
                "maxTokens": 1000,
            },
            messages: [{ role: "USER", contents: [{ text: userInput }],  }],
        });
        return response.choices[0].message.content;
    }
}

import { PlatformClient } from "@osdk/client";
import OpenAI from "openai";
import { Aliases } from "@osdk/functions";
import { getFoundryToken, getOpenAiBaseUrl, createFetch } from "@osdk/language-models";

export default async function createChatCompletion(client: PlatformClient, userInput: string): Promise<string> {
    const oaiClient = new OpenAI({
        apiKey: await getFoundryToken(client),
        baseURL: getOpenAiBaseUrl(client),
        fetch: createFetch(client),
    });

    const completion = await oaiClient.chat.completions.create({
        // Reference the alias for the substitute model.
        model: Aliases.model("gpt41").rid,
        messages: [
            { role: "user", content: userInput },
        ],
        max_completion_tokens: 1000,
    });

    return completion.choices[0]?.message.content ?? "";
}

from transforms.api import transform, Input, Output
from palantir_models.transforms import OpenAiGptChatLanguageModelInput
from palantir_models.models import OpenAiGptChatLanguageModel
from language_model_service_api.languagemodelservice_api_completion_v3 import GptChatCompletionRequest
from language_model_service_api.languagemodelservice_api import ChatMessage, ChatMessageRole

@transform(
    reviews=Input("Input Dataset Rid"),
    # Replace usage of the deprecated model with the new model.
    model=OpenAiGptChatLanguageModelInput("ri.language-model-service..language-model.gpt-4-1"),
    output=Output("Output dataset rid or path"),
)
def compute_sentiment(ctx, reviews, model: OpenAiGptChatLanguageModel, output):
    def get_completions(review_content: str) -> str:
        system_prompt = "Take the following review determine the sentiment of the review"
        request = GptChatCompletionRequest(
            [ChatMessage(ChatMessageRole.SYSTEM, system_prompt), ChatMessage(ChatMessageRole.USER, review_content)]
        )
        resp = model.create_chat_completion(request)
        return resp.choices[0].message.content

    reviews_df = reviews.pandas()
    reviews_df['sentiment'] = reviews_df['review_content'].apply(get_completions)
    out_df = ctx.spark_session.createDataFrame(reviews_df)
    return output.write_dataframe(out_df)

Model usage in Quiver

Quiver 中的 LLM 使用可以在分析设置中配置。导航到受影响分析侧边栏中的设置标签页，并在 AIP Settings 小节下访问模型选择器。

Additional tools

工作流可能会变得复杂且难以驾驭，导致很难直观地找到所有受影响的资源使用实例。请查阅下方小节，了解可用于帮助识别工作流中 LLM 使用的工具。

Workflow Lineage

为了更好地理解跨资源的模型使用情况，你可以使用 Workflow Lineage。使用键盘快捷键 Cmd + I（macOS）或 Ctrl + I（Windows）在 Workflow Lineage 中打开某个 Workshop 应用或函数 repository。在 Workflow Lineage 图表中，你将能够查看支撑某个应用的对象、actions 和函数。

• Workshop applications： 对于 Workshop 应用，Workflow Lineage 会显示上游资源（如 Logic functions）以及它们被配置使用的模型。Workflow Lineage 还允许用户查看消费某个给定函数的其他 Workshop 或 OSDK 应用，从而更容易地理解受影响资源的完整范围。如果某个资源使用了已弃用模型，Workflow Lineage 会显示一个警告图标和一条消息，提醒用户该模型已处于弃用状态。<br><br> <br><br>

Workflow Lineage 可以借助其批量更新功能，帮助完成 Workshop 的模型迁移操作。如基于函数的模型使用小节所示更新某个函数之后，你可以在 Workflow Lineage 中打开该 Workshop 应用，以批量更新一个或所有依赖该函数的 Workshop 应用所使用的函数版本。此外，Workflow Lineage 还让你能够通过一次操作，从 lineage 图表中批量替换语言模型，跨越多个 AIP Logic functions。

• Function repositories： Workflow Lineage 可以提供可视化表示，帮助用户理解函数 repository 中的模型使用情况。调用模型的函数会有一个相连的模型节点，让用户能够一眼看出这些函数是否在调用已弃用模型。<br><br> <br><br>

关于 Workflow Lineage 完整功能集的更多信息，请参阅 Workflow Lineage 的使用文档。

Ontology Manager

一旦你识别出包含已弃用模型的函数，就可以在 Ontology Manager 中打开它，以跟踪使用该函数的资源。然后你可以导航到这些资源并更新函数版本，以确保服务不中断。对于 Workshop 应用，你可以使用上一小节所述的 Workflow Lineage 来批量更新函数版本。

要查看函数使用情况，请导航到 Ontology Manager 并在侧边栏中选择 Functions。在 functions 页面上，你可以搜索函数名称，并从 Functions 表中选择它以打开其概览页面。

在函数概览页面中，向下滚动到 Usage history 小节，查看使用该函数的资源列表。你可以按版本筛选，找出可能正在使用该函数过时版本的资源。

然后你可以导航到使用该函数的资源，将其更新到最新版本。更多信息请参阅 Ontology Manager 的函数类型视图文档。