共用方式為

定義代理程式的輸入和輸出架構

  • 發行項

AI 代理程式必須遵循特定的輸入和輸出架構需求，才能與 Azure Databricks 上的其他功能相容。 本文說明如何確保您的 AI 代理程式遵守這些需求，以及如何自定義代理程式的輸入和輸出架構，同時確保相容性。

馬賽克 AI 會使用 MLflow 模型簽章 來定義代理程式的輸入和輸出架構需求。 模型簽章會告知內部和外部元件如何與您的代理程序互動，並驗證它們是否符合架構。

OpenAI 聊天完成架構 （建議）

Databricks 建議使用 OpenAI 聊天完成架構 來定義代理程式輸入和輸出。 此架構廣泛採用並與許多代理程式架構和應用程式相容，包括 Databricks 中的架構。

如需有關聊天完成 輸入架構設計 和 輸出架構設計的詳細資訊，請參閱 OpenAI 文件。

注意

OpenAI 聊天完成架構只是建構代理程式輸入和輸出的標準。 實作此架構並不牽涉到使用 OpenAI 的資源或模型。

MLflow 為 LangChain 和 PyFunc 型代理程式提供方便的 API，協助您建立與聊天完成架構相容的代理程式。

使用 LangChain 實作聊天完成

如果您的代理程式使用 LangChain，請使用 MLflow 的 ChatCompletionOutputParser()，將代理程式的最終輸出格式化為與聊天完成架構相容。 如果您使用 LangGraph，請參閱 LangGraph 自訂架構。


  from mlflow.langchain.output_parsers import ChatCompletionOutputParser

  chain = (
      {
          "user_query": itemgetter("messages")
          | RunnableLambda(extract_user_query_string),
          "chat_history": itemgetter("messages") | RunnableLambda(extract_chat_history),
      }
      | RunnableLambda(DatabricksChat)
      | ChatCompletionOutputParser()
  )

使用 PyFunc 實現聊天完成功能

如果您使用 PyFunc，Databricks 建議將您的代理程式撰寫為 mlflow.pyfunc.ChatModel的子類別。 此方法提供下列優點：

  • 可讓您使用具類型的 Python 類別撰寫與聊天完成架構相容的代理程式代碼。

  • 記錄代理程式時，MLflow 會自動推斷出與聊天完成相容的簽章，即使沒有 input_example。 這可簡化註冊和部署代理程式的程式。 請參閱在記錄期間 推斷模型簽章。

    from dataclasses import dataclass
from typing import Optional, Dict, List, Generator
from mlflow.pyfunc import ChatModel
from mlflow.types.llm import (
    # Non-streaming helper classes
    ChatCompletionRequest,
    ChatCompletionResponse,
    ChatCompletionChunk,
    ChatMessage,
    ChatChoice,
    ChatParams,
    # Helper classes for streaming agent output
    ChatChoiceDelta,
    ChatChunkChoice,
)

class MyAgent(ChatModel):
    """
    Defines a custom agent that processes ChatCompletionRequests
    and returns ChatCompletionResponses.
    """
    def predict(self, context, messages: list[ChatMessage], params: ChatParams) -> ChatCompletionResponse:
        last_user_question_text = messages[-1].content
        response_message = ChatMessage(
            role="assistant",
            content=(
                f"I will always echo back your last question. Your last question was: {last_user_question_text}. "
            )
        )
        return ChatCompletionResponse(
            choices=[ChatChoice(message=response_message)]
        )

    def _create_chat_completion_chunk(self, content) -> ChatCompletionChunk:
        """Helper for constructing a ChatCompletionChunk instance for wrapping streaming agent output"""
        return ChatCompletionChunk(
                choices=[ChatChunkChoice(
                    delta=ChatChoiceDelta(
                        role="assistant",
                        content=content
                    )
                )]
            )

    def predict_stream(
        self, context, messages: List[ChatMessage], params: ChatParams
    ) -> Generator[ChatCompletionChunk, None, None]:
        last_user_question_text = messages[-1].content
        yield self._create_chat_completion_chunk(f"Echoing back your last question, word by word.")
        for word in last_user_question_text.split(" "):
            yield self._create_chat_completion_chunk(word)

agent = MyAgent()
model_input = ChatCompletionRequest(
    messages=[ChatMessage(role="user", content="What is Databricks?")]
)
response = agent.predict(context=None, model_input=model_input)
print(response)

自定義輸入和輸出

Databricks 建議遵守大部分代理程式使用案例的 OpenAI 聊天完成架構。

不過，某些案例可能需要額外的輸入，例如 client_type 和 session_id，或擷取來源連結等輸出，這些輸出不應該包含在聊天記錄中以供日後互動。

在這些案例中，馬賽克 AI 代理程式架構支援使用自定義輸入和輸出來增強 OpenAI 聊天完成要求和回應。

請參閱下列範例，以瞭解如何建立 PyFunc 和 LangGraph 代理程式的自定義輸入和輸出。

警告

代理程式評估檢閱應用程式 目前不支援呈現具有額外輸入欄位的代理程式的追蹤資訊。

PyFunc 自定義架構

下列筆記本顯示使用 PyFunc 的自訂架構範例。

PyFunc 自定義架構代理程序筆記本

取得筆記本

PyFunc 自定義架構驅動程序筆記本

取得筆記本

LangGraph 自定義架構

下列筆記本顯示使用 LangGraph 的自定義架構範例。 您可以修改筆記本中的 wrap_output 函式，以剖析和擷取訊息數據流中的資訊。

LangGraph 自訂結構代理筆記本

取得筆記本

LangGraph 自訂架構驅動器筆記

取得筆記本

在 AI 遊樂場和代理程式檢閱應用程式中提供custom_inputs

如果您的代理程式使用 [custom_inputs] 字段接受其他輸入，您可以在 AI 遊樂場 和 代理程式檢閱應用程式手動提供這些輸入。

  1. 在 AI 遊樂場或代理程式檢閱應用程式中，選取齒輪圖示 齒輪圖示。

  2. 啟用 custom_inputs。

  3. 提供符合代理程式所定義輸入架構的 JSON 物件。

    在 AI 遊樂場中提供custom_inputs。

舊版輸入和輸出架構

SplitChatMessageRequest 輸入架構和 StringResponse 輸出架構已被取代。 如果您使用上述任一舊版架構，Databricks 建議您移轉至建議的聊天完成架構。

SplitChatMessageRequest 輸入架構 （已淘汰）

SplitChatMessagesRequest 可讓您將目前的查詢和歷程記錄個別傳遞為代理程序輸入。

  question = {
      "query": "What is MLflow",
      "history": [
          {
              "role": "user",
              "content": "What is Retrieval-augmented Generation?"
          },
          {
              "role": "assistant",
              "content": "RAG is"
          }
      ]
  }

StringResponse 輸出架構 （已淘汰）

StringResponse 可讓您以具有單一字串 content 字段的物件傳回代理程式的回應：

{"content": "This is an example string response"}