본문 바로가기
WIKI 기술 지식 베이스

Create or Update Workflow API

원문 보기 위키 갱신

출처: 문서

본문

워크플로 생성 또는 업데이트 API

워크플로를 생성하면 워크플로 템플릿의 내용이 flow framework 시스템 인덱스에 추가돼요. 워크플로는 JSON 형식(Content-Type: application/json 지정)이나 YAML 형식(Content-Type: application/yaml 지정)으로 제공할 수 있어요. 기본적으로 워크플로는 유효성 검사를 거쳐서 다음과 같은 잘못된 구성을 식별하는 데 도움을 줘요:

  • 설치되지 않은 OpenSearch 플러그인을 필요로 하는 워크플로 스텝
  • 이전 노드 입력에 의존하는 워크플로 스텝(해당 입력은 그 스텝들이 제공)
  • 잘못된 값을 가진 워크플로 스텝 필드
  • 사이클을 포함하거나 중복된 ID를 가진 워크플로 그래프(노드/엣지) 구성

워크플로 스텝의 유효성 검사 템플릿을 얻으려면 Get Workflow Steps API를 호출하세요.

워크플로 스텝 필드의 값에 플레이스홀더 표현식을 포함할 수 있어요. 예를 들어 템플릿에서 자격 증명 필드를 {% raw %}openAI_key: '${{ openai_key }}'{% endraw %}와 같이 지정할 수 있어요. 이 표현식은 {% raw %}${{ <value> }}{% endraw %} 형식을 사용하며, 프로비저닝 중에 사용자가 제공한 값으로 대체돼요. 실제 키를 파라미터로 전달하려면 Provision Workflow API를 사용하거나, 이 API에 provision 파라미터를 true로 설정해서 사용하면 돼요.

워크플로를 생성한 후에는 다른 API에 workflow_id를 제공하세요.

POST 메서드는 새 워크플로를 생성하고, PUT 메서드는 기존 워크플로를 업데이트해요. update_fields 파라미터를 지정해서 특정 필드만 업데이트할 수도 있어요.

완전한 워크플로는 아직 프로비저닝되지 않은 경우에만 업데이트할 수 있어요. {: .note}

엔드포인트

POST /_plugins/_flow_framework/workflow
PUT /_plugins/_flow_framework/workflow/{workflow_id}

경로 파라미터

다음 표는 사용 가능한 경로 파라미터를 보여줘요.

파라미터 데이터 타입 설명
workflow_id String 업데이트할 워크플로의 ID예요. PUT 메서드에서는 필수예요.

쿼리 파라미터

워크플로는 보통 생성과 프로비저닝을 별도 단계로 진행해요. 하지만 워크플로를 충분히 테스트한 후에는 provision 쿼리 파라미터를 포함해서 생성 단계와 프로비저닝 단계를 하나로 합칠 수 있어요:

POST /_plugins/_flow_framework/workflow?provision=true

{% include copy-curl.html %}

true로 설정하면 워크플로 생성 직후 Provision Workflow API가 바로 실행돼요.

기본적으로 워크플로는 생성 시점에 유효성 검사를 거쳐서 문법이 올바른지, 그래프에 사이클이 없는지 확인해요. 이 동작은 validation 쿼리 파라미터로 제어할 수 있어요. validation을 all로 설정하면 OpenSearch가 템플릿 전체에 대한 유효성 검사를 수행해요. validation 파라미터에 다른 값을 지정하면 유효성 검사가 생략되기 때문에 불완전하거나 작성 중인 템플릿도 저장할 수 있어요. 템플릿 유효성 검사를 비활성화하려면 validation을 none으로 설정하세요:

POST /_plugins/_flow_framework/workflow?validation=none

{% include copy-curl.html %}

아직 프로비저닝하지 않은 워크플로에서는 workflows 필드 이외의 필드를 업데이트할 수 있어요. 예를 들어 다음과 같이 name과 description 필드를 업데이트할 수 있어요:

PUT /_plugins/_flow_framework/workflow/{workflow_id}?update_fields=true
{
  "name": "new-template-name",
  "description": "A new description for the existing template"
}

{% include copy-curl.html %}

provision 파라미터와 update_fields 파라미터를 동시에 지정할 수는 없어요. {: .note}

워크플로가 이미 프로비저닝된 경우에는 전체 템플릿을 업데이트하고 다시 프로비저닝할 수 있어요:

PUT /_plugins/_flow_framework/workflow/{workflow_id}?reprovision=true
{
  <updated complete template>
}

워크플로에 새 스텝을 추가할 수는 있지만 기존 스텝은 삭제할 수 없어요. 현재는 인덱스 설정, 검색 파이프라인, 인제스트 파이프라인 스텝만 업데이트할 수 있어요. {: .note}

요청이 프로비저닝과 재프로비저닝 과정의 완료를 얼마나 오래 기다릴지 제어하려면 wait_for_completion_timeout 파라미터를 사용하세요:

POST /_plugins/_flow_framework/workflow/?provision=true&wait_for_completion_timeout=2s

{% include copy-curl.html %}

PUT /_plugins/_flow_framework/workflow/{workflow_id}/?reprovision=true&wait_for_completion_timeout=2s

{% include copy-curl.html %}

지정한 시간 내에 작업이 완료되지 않으면 응답은 현재 워크플로 상태를 반환하고, 실행은 비동기적으로 계속 진행돼요.

wait_for_completion_timeout 파라미터는 provision 또는 reprovision이 true로 설정된 경우에만 사용할 수 있어요 {: .note}

예를 들어 다음 요청은 워크플로를 프로비저닝하고 완료될 때까지 최대 2초를 기다려요: 워크플로 템플릿을 사용하면 다음과 같이 워크플로를 생성하고 프로비저닝할 수 있어요:

POST /_plugins/_flow_framework/workflow?use_case={use_case}&provision=true
{
    "create_connector.credential.key" : "<YOUR API KEY>"
}

{% include copy-curl.html %}

다음 표는 사용 가능한 쿼리 파라미터를 보여줘요. 모든 쿼리 파라미터는 선택 사항이에요. 사용자 제공 파라미터는 provision 파라미터가 true로 설정된 경우에만 허용돼요.

파라미터 데이터 타입 설명
provision Boolean 요청의 일부로 워크플로를 프로비저닝할지 여부예요. 기본값은 false예요.
update_fields Boolean 요청 본문에 포함된 필드만 업데이트할지 여부예요. 기본값은 false예요.
reprovision Boolean 이미 프로비저닝된 경우 전체 템플릿을 다시 프로비저닝할지 여부예요. 요청 본문에 완전한 템플릿을 제공해야 해요. 기본값은 false예요.
validation String 워크플로의 유효성을 검사할지 여부예요. 유효한 값은 all(템플릿 검사)과 none(템플릿을 검사하지 않음)이에요. 기본값은 all이에요.
use_case String 워크플로를 생성할 때 사용할 워크플로 템플릿의 이름이에요.
wait_for_completion_timeout Time value 동기 프로비저닝 또는 재프로비저닝의 최대 대기 시간을 지정해요. 제한 시간을 초과하면 요청은 현재 워크플로 상태를 반환하고, 실행은 비동기적으로 계속 진행돼요.
사용자 제공 치환 표현식 String 템플릿의 치환 표현식과 일치하는 파라미터예요. provision이 true로 설정된 경우에만 허용돼요. 선택 사항이에요. provision이 false로 설정된 경우에는 Provision Workflow API 쿼리 파라미터에서 이 파라미터들을 전달할 수 있어요.

요청 본문 필드

다음 표는 사용 가능한 요청 필드를 보여줘요.

필드 데이터 타입 필수/선택 설명
name String 필수 워크플로의 이름이에요.
description String 선택 워크플로에 대한 설명이에요.
use_case String 선택 사용자가 제공하는 사용 사례예요. Search Workflow API와 함께 사용해서 관련 워크플로를 찾을 수 있어요. 이 필드에 사용자 지정 값을 지정할 수 있어요. 이 값은 use_case 쿼리 파라미터와는 별개예요.
version Object 선택 두 개의 필드를 가진 키-값 맵이에요. template은 템플릿 버전을 식별하고, compatibility는 필요한 최소 OpenSearch 버전 목록을 식별해요.
workflows Object 선택 워크플로의 맵이에요. provision 키만 지원돼요. 워크플로 키의 값은 user_params 필드와 nodes, edges 목록을 포함하는 키-값 맵이에요.

예제 요청: YAML로 외부 호스팅 모델 등록 및 배포

YAML 형식으로 템플릿을 제공하려면 요청 헤더에 Content-Type: application/yaml을 지정하세요:

curl -XPOST "http://localhost:9200/_plugins/_flow_framework/workflow" -H 'Content-Type: application/yaml'

YAML 템플릿에서는 주석을 사용할 수 있어요. {: .tip}

다음은 외부 호스팅 모델을 등록하고 배포하는 YAML 템플릿 예제예요:

# This Name Is Required API
name: createconnector-registerremotemodel-deploymodel
# Other Fields Are Optional But Useful API
description: This template creates a connector to a remote model, registers it, and
  deploys that model
# Other Templates With A Similar Use Case Can Be Searched API
use_case: REMOTE_MODEL_DEPLOYMENT
version:
  # Templates may be versioned by their authors
  template: 1.0.0
  # Compatibility with OpenSearch 2.12.0 and higher and 3.0.0 and higher
  compatibility:
  - 2.12.0
  - 3.0.0
# One Or More Workflows Can Be Included, Presently Only Provision Is Supported API
workflows:
  provision:
    # These nodes are the workflow steps corresponding to ML Commons APIs
    nodes:
    # This ID must be unique to this workflow
    - id: create_connector_1
      # There may be multiple steps with the same type
      type: create_connector
      # These inputs match the Create Connector API body
      user_inputs:
        name: OpenAI Chat Connector
        description: The connector to public OpenAI model service for gpt-4o-mini
        version: '1'
        protocol: http
        parameters:
          endpoint: api.openai.com
          model: gpt-4o-mini
        credential:
          openAI_key: '12345'
        actions:
        - action_type: predict
          method: POST
          url: https://${parameters.endpoint}/v1/chat/completions
    # This ID must be unique to this workflow
    - id: register_model_2
      type: register_remote_model
      # This step needs the connector_id produced as an output of the previous step
      previous_node_inputs:
        create_connector_1: connector_id
      # These inputs match the Register Model API body
      user_inputs:
        name: openAI-gpt-4o-mini
        function_name: remote
        description: test model
    # This ID must be unique to this workflow
    - id: deploy_model_3
      type: deploy_model
      # This step needs the model_id produced as an output of the previous step
      previous_node_inputs:
        register_model_2: model_id
    # Since the nodes include previous_node_inputs these are optional to define
    # They will be added automatically and included in the stored template
    # Additional edges may also be added here if required for sequencing
    edges:
    - source: create_connector_1
      dest: register_model_2
    - source: register_model_2
      dest: deploy_model_3

{% include copy-curl.html %}

예제 요청: 원격 모델 등록 및 배포(JSON)

JSON 형식으로 템플릿을 제공하려면 요청 헤더에 Content-Type: application/json을 지정하세요:

curl -XPOST "http://localhost:9200/_plugins/_flow_framework/workflow" -H 'Content-Type: application/json'

다음 JSON 템플릿은 앞 섹션에서 제공한 YAML 템플릿과 동일해요:

{
  "name": "createconnector-registerremotemodel-deploymodel",
  "description": "This template creates a connector to a remote model, registers it, and deploys that model",
  "use_case": "REMOTE_MODEL_DEPLOYMENT",
  "version": {
    "template": "1.0.0",
    "compatibility": [
      "2.12.0",
      "3.0.0"
    ]
  },
  "workflows": {
    "provision": {
      "nodes": [
        {
          "id": "create_connector_1",
          "type": "create_connector",
          "user_inputs": {
            "name": "OpenAI Chat Connector",
            "description": "The connector to public OpenAI model service for gpt-4o-mini",
            "version": "1",
            "protocol": "http",
            "parameters": {
              "endpoint": "api.openai.com",
              "model": "gpt-4o-mini"
            },
            "credential": {
              "openAI_key": "12345"
            },
            "actions": [
              {
                "action_type": "predict",
                "method": "POST",
                "url": "https://${parameters.endpoint}/v1/chat/completions"
              }
            ]
          }
        },
        {
          "id": "register_model_2",
          "type": "register_remote_model",
          "previous_node_inputs": {
            "create_connector_1": "connector_id"
          },
          "user_inputs": {
            "name": "openAI-gpt-4o-mini",
            "function_name": "remote",
            "description": "test model"
          }
        },
        {
          "id": "deploy_model_3",
          "type": "deploy_model",
          "previous_node_inputs": {
            "register_model_2": "model_id"
          }
        }
      ],
      "edges": [
        {
          "source": "create_connector_1",
          "dest": "register_model_2"
        },
        {
          "source": "register_model_2",
          "dest": "deploy_model_3"
        }
      ]
    }
  }
}

{% include copy-curl.html %}

예제 응답

OpenSearch는 workflow_id를 응답으로 반환해요:

{
  "workflow_id" : "8xL8bowB8y25Tqfenm50"
}

워크플로를 생성하고 나면 workflow_id를 사용해서 다른 워크플로 API를 사용할 수 있어요.

wait_for_completion_timeout 활성화 시 예제 응답

{
    "workflow_id": "K13IR5QBEpCfUu_-AQdU",
    "state": "COMPLETED",
    "resources_created": [
        {
            "workflow_step_name": "create_connector",
            "workflow_step_id": "create_connector_1",
            "resource_id": "LF3IR5QBEpCfUu_-Awd_",
            "resource_type": "connector_id"
        },
        {
            "workflow_step_id": "register_model_2",
            "workflow_step_name": "register_remote_model",
            "resource_id": "L13IR5QBEpCfUu_-BQdI",
            "resource_type": "model_id"
        },
        {
            "workflow_step_name": "deploy_model",
            "workflow_step_id": "deploy_model_3",
            "resource_id": "L13IR5QBEpCfUu_-BQdI",
            "resource_type": "model_id"
        }
    ]
}

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.