기초 모델을 프로그래밍 방식으로 조정하기

watsonx.ai 에서 일련의 파운데이션 모델을 프로그래밍 방식으로 조정하여 사용 사례에 맞게 모델을 맞춤 설정할 수 있습니다.

다음 기법을 사용하여 파운데이션 모델을 프로그래밍 방식으로 미세 조정할 수 있습니다:

완벽한 미세 조정
저순위 적응( LoRA ) 미세 조정
양자화 저순위 적응( QLoRA ) 미세 조정

사용자 정의 파운데이션 모델을 튜닝할 때는 어떤 미세 조정 방법을 사용해도 됩니다.

필요한 권한: 튜닝 실험을 실행하려면 프로젝트에서 관리자 또는 편집자 권한이 있어야 합니다.
필수 자격 요건: watsonx.ai API에 인증하려면 자격 증명을 생성해야 합니다. 자세한 내용은 ‘베어러 토큰 생성’을 참조하십시오.
데이터 형식: 표 형식: JSON, JSONL; 지원되는 데이터 연결의 표 형식 데이터. 자세한 내용은 ‘데이터 형식’을 참조하십시오.; 참고: 하나의 훈련 데이터를 하나 이상의 튜닝 실험에 사용할 수 있습니다.
데이터 크기: 50개에서 10,000개까지의 입력-출력 예시 쌍. 파일 크기는 최대 200MB입니다.

발전하는 방법

다음과 같은 프로그래밍 방법을 사용하여 기초 모델을 조정할 수 있습니다

휴식 (REST API)
Python
Node.js

또는, watsonx.ai 의 그래픽 도구를 사용하여 기초 모델을 조정할 수 있습니다. 보다 Tuning Studio.

지원되는 기초 모델

전체 미세 조정을 지원하는 파운데이션 모델 목록을 확인하려면 다음 API 요청을 사용하세요:

curl -X GET \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/foundation_model_specs?version=2025-02-20&filters=function_fine_tune_trainable'

LoRA 또는 QLoRA 미세 조정을 지원하는 파운데이션 모델 목록을 확인하려면 다음 API 요청을 사용하세요:

curl -X GET \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/foundation_model_specs?version=2025-02-20&filters=function_lora_fine_tune_trainable'

조정할 기초 모델 선택하기를 참조하십시오.

LoRA 는 비양자화 모델에서만 사용할 수 있으며, QLoRA 는 양자화 모델에서만 사용할 수 있습니다.

휴식 (REST API)

각 기술에 따라 수행하는 고수준 단계는 거의 동일합니다. 주요 차이점은 미세 조정 훈련 작업의 요청 본문에 포함해야 하는 값들인데, 이는 다음 절차에서 강조 표시되어 있습니다. REST API 메서드에 대한 자세한 내용은 ‘ watsonx.ai ’ API 참조 문서의 ‘세부 조정’ 섹션을 참조하십시오.

기초 모델 튜닝에 사용할 훈련 데이터 파일을 만듭니다.

훈련 데이터 파일 요건에 대한 자세한 정보는 기초 모델 튜닝을 위한 데이터 형식을 참고하세요.
API가 사용할 수 있도록 훈련 데이터 파일을 준비하십시오. 데이터 어셈블리를 생성할 수 있습니다

다음 중 하나를 수행할 수 있습니다.
- UI 방식
  
  JSON 또는 JSONL 파일을 업로드하려면 API에서 참조할 파일 추가 하기의 단계를 따르세요.
- API 방식
  
  Data and AI Common Core API 를 사용하여 연결 또는 데이터 자산을 생성합니다.
REST API 요청 본문의 섹션을 training_data_references 추가할 때 자산 ID와 훈련 데이터 파일 정보를 사용하게 됩니다.

watsonx.ai API를 사용하여 훈련 실험을 생성하세요. ‘미세 조정 작업 생성’ 방법을 참조하십시오.

다음 엔드포인트로 POST 요청을 전송하십시오:

curl --request POST 'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/fine_tunings?version=2025-02-14' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${TOKEN}' \

페이로드의 FineTuningParameters 다양한 매개변수 값을 설정하여 실험을 맞춤 구성하세요. 자세한 내용은 ‘튜닝할 모델 선택 ’ 및 ‘기초 모델 튜닝 매개변수’를 참조하십시오.

auto_update_model 를 true 로 설정하면 나중에 조정된 기초 모델을 배포할 때 사용할 수 있는 자산으로 생성된 출력을 저장할 수 있습니다. asset_id 그렇지 않으면, 실험을 통해 생성된 조정된 모델 또는 어댑터를 저장소에 저장해야 배포에 사용할 수 있습니다.

다음은 전체 미세 조정 실험을 생성하는 요청 본문의 예시입니다:

{
  "project_id": "<project-id>",
  "name": "my fft experiment",
  "auto_update_model": true,
  "tuned_model_name": "my-fine-tuned-model",
  "parameters": {
    "base_model": {
      "model_id": "ibm/granite-3-1-8b-base" },
    "task_id": "classification",
    "num_epochs": 10,
    "learning_rate": 0.00001,
    "batch_size": 5,
    "max_seq_length": 1024,
    "accumulate_steps": 1,
    "gpu": {
      "num": 4
    }
  },
  "results_reference": {
    "location": {
      "path": "full_fine_tuning/results" },
    "type": "fs"
  },
  "training_data_references": [
    {
    "location": {
      "href":"/v2/assets/1e6591a2-c69d-4716-92e3-73e8c2270956project_id=<project-id>",
      "id":"1e6591a2-c69d-4716-92e3-73e8c2270956" },
    "type": "data_asset"
    }
  ]
}

다음 예시는 API 요청 결과를 보여줍니다:

{
  "entity": {
    "auto_update_model": true,
    "parameters": {
      "accumulate_steps": 1,
      "base_model": {
        "model_id": "ibm/granite-3-1-8b-base"
      },
      "batch_size": 5,
      "gpu": {
        "num": 4
      },
      "learning_rate": 0.00001,
      "max_seq_length": 1024,
      "num_epochs": 10,
      "response_template": "\n### Response:",
      "task_id": "classification",
      "verbalizer": "### Input:  \n\n### Response: "
    },
    "results_reference": {
      "location": {
        "path": "/projects/<project-id>/assets/full_fine_tuning/results",
        "notebooks_path": "/projects/<project-id>/assets/full_fine_tuning/results/63e98673-a2c0-45c1-8ac6-e26a47ec1914/notebooks",
        "training": "/projects/<project-id>/assets/full_fine_tuning/results/63e98673-a2c0-45c1-8ac6-e26a47ec1914",
        "training_status": "/projects/<project-id>/assets/full_fine_tuning/results/63e98673-a2c0-45c1-8ac6-e26a47ec1914/training-status.json",
        "assets_path": "/projects/<project-id>/assets/full_fine_tuning/results/63e98673-a2c0-45c1-8ac6-e26a47ec1914/assets"
      },
      "type": "fs"
    },
    "status": {
      "state": "pending"
    },
    "training_data_references": [
      {
        "location": {
          "href": "/v2/assets/1e6591a2-c69d-4716-92e3-73e8c2270956project_id=<project-id>",
          "id": "1e6591a2-c69d-4716-92e3-73e8c2270956"
        },
        "type": "data_asset"
      }
    ],
    "tuned_model": {
      "name": "my-fine-tuned-model-63e98673-a2c0-45c1-8ac6-e26a47ec1914"
    }
  },
  "metadata": {
    "created_at": "2025-02-14T20:49:03.959Z",
    "id": "63e98673-a2c0-45c1-8ac6-e26a47ec1914",
    "modified_at": "2025-02-14T20:49:03.959Z",
    "name": "my fft experiment",
    "project_id": "<project-id>"
  }
}

다음의 샘플 요청 본문은 미세 조정 실험( LoRA )을 만듭니다.

{
  "project_id": "<project-id>",
  "name": "my LoRA experiment",
  "auto_update_model": true,
  "tuned_model_name": "my-lora-tuned-model",
  "parameters": {
    "base_model": {
      "model_id": "ibm/granite-3-1-8b-base" },
    "task_id": "classification",
    "num_epochs": 10,
    "learning_rate": 0.00001,
    "batch_size": 5,
    "max_seq_length": 4096,
    "accumulate_steps": 1,
    "gpu": {
      "num": 1
    },
    "peft_parameters": {
      "type": "lora",
      "rank": 8,
      "lora_alpha": 32,
      "lora_dropout": 0.05,
      "target_modules": ["all-linear"]
    }
  },
  "results_reference": {
    "location": {
      "path": "fine_tuning/results" },
    "type": "fs"
  },
  "training_data_references": [
    {
    "location": {
      "href":"/v2/assets/1e6591a2-c69d-4716-92e3-73e8c2270956project_id=<project-id>",
      "id":"1e6591a2-c69d-4716-92e3-73e8c2270956" },
    "type": "data_asset"
    }
  ]
}

다음 예시는 API 요청 결과를 보여줍니다:

{
  "entity": {
    "auto_update_model": true,
    "parameters": {
      "accumulate_steps": 1,
      "base_model": {
        "model_id": "ibm/granite-3-1-8b-base"
      },
      "batch_size": 5,
      "gpu": {
        "num": 1
      },
      "learning_rate": 0.00001,
      "max_seq_length": 1024,
      "num_epochs": 10,
      "peft_parameters": {
        "lora_alpha": 32,
        "lora_dropout": 0.05,
        "rank": 8,
        "target_modules": [
          "all-linear"
        ],
        "type": "lora"
      },
      "response_template": "\n### Response:",
      "task_id": "classification",
      "verbalizer": "### Input:  \n\n### Response: "
    },
    "results_reference": {
      "location": {
        "path": "/projects/<project-id>/assets/fine_tuning/results",
        "notebooks_path": "/projects/<project-id>/assets/fine_tuning/results/2491b2d9-bf96-4d3f-9ea7-8604861471e1/notebooks",
        "training": "/projects/<project-id>/assets/fine_tuning/results/2491b2d9-bf96-4d3f-9ea7-8604861471e1",
        "training_status": "/projects/<project-id>/assets/fine_tuning/results/2491b2d9-bf96-4d3f-9ea7-8604861471e1/training-status.json",
        "assets_path": "/projects/<project-id>/assets/fine_tuning/results/2491b2d9-bf96-4d3f-9ea7-8604861471e1/assets"
      },
      "type": "fs"
    },
    "status": {
      "state": "pending"
    },
    "training_data_references": [
      {
        "location": {
          "href": "/v2/assets/1e6591a2-c69d-4716-92e3-73e8c2270956?project_id=<project-id>",
          "id": "1e6591a2-c69d-4716-92e3-73e8c2270956"
        },
        "type": "data_asset"
      }
    ],
    "tuned_model": {
      "name": "my-lora-tuned-model-2491b2d9-bf96-4d3f-9ea7-8604861471e1"
    }
  },
  "metadata": {
    "created_at": "2025-02-14T19:47:36.629Z",
    "id": "2491b2d9-bf96-4d3f-9ea7-8604861471e1",
    "modified_at": "2025-02-14T19:47:36.629Z",
    "name": "My LoRA experiment",
    "project_id": "<project-id>"
  }
}

다음의 샘플 요청 본문은 미세 조정 실험( QLoRA )을 만듭니다.

{
  "project_id": "<project-id>",
  "name": "my QLoRA experiment",
  "auto_update_model": true,
  "tuned_model_name": "my-qlora-tuned-model",
  "parameters": {
    "base_model": {
      "model_id": "meta-llama/llama-3-1-70b-gptq" },
    "task_id": "classification",
    "num_epochs": 10,
    "learning_rate": 0.00001,
    "batch_size": 5,
    "max_seq_length": 1024,
    "accumulate_steps": 1,
    "gpu": {
      "num": 1
    },
    "peft_parameters": {
      "type": "qlora",
      "rank": 8,
      "lora_alpha": 32,
      "lora_dropout": 0.05,
      "target_modules": []
    }
  },
  "results_reference": {
    "location": {
      "path": "fine_tuning/results" },
    "type": "fs"
  },
  "training_data_references": [
    {
    "location": {
      "href":"/v2/assets/1e6591a2-c69d-4716-92e3-73e8c2270956project_id=<project-id>",
      "id":"1e6591a2-c69d-4716-92e3-73e8c2270956" },
    "type": "data_asset"
    }
  ]
}

다음 예시는 API 요청 결과를 보여줍니다:

{
  "entity": {
    "auto_update_model": true,
    "parameters": {
      "accumulate_steps": 1,
      "base_model": {
        "model_id": "meta-llama/llama-3-1-70b-gptq"
      },
      "batch_size": 5,
      "gpu": {
        "num": 1
      },
      "learning_rate": 0.00001,
      "max_seq_length": 1024,
      "num_epochs": 10,
      "peft_parameters": {
        "lora_alpha": 32,
        "lora_dropout": 0.05,
        "rank": 8,
        "target_modules": [],
        "type": "qlora"
      },
      "response_template": "\n### Response:",
      "task_id": "classification",
      "verbalizer": "### Input:  \n\n### Response: "
    },
    "results_reference": {
      "location": {
        "path": "/projects/<project-id>/assets/fine_tuning/results",
        "notebooks_path": "/projects/<project-id>/assets/fine_tuning/results/2491b2d9-bf96-4d3f-9ea7-8604861471e1/notebooks",
        "training": "/projects/<project-id>/assets/fine_tuning/results/2491b2d9-bf96-4d3f-9ea7-8604861471e1",
        "training_status": "/projects/<project-id>/assets/fine_tuning/results/2491b2d9-bf96-4d3f-9ea7-8604861471e1/training-status.json",
        "assets_path": "/projects/<project-id>/assets/fine_tuning/results/2491b2d9-bf96-4d3f-9ea7-8604861471e1/assets"
      },
      "type": "fs"
    },
    "status": {
      "state": "pending"
    },
    "training_data_references": [
      {
        "location": {
          "href": "/v2/assets/1e6591a2-c69d-4716-92e3-73e8c2270956?project_id=<project-id>",
          "id": "1e6591a2-c69d-4716-92e3-73e8c2270956"
        },
        "type": "data_asset"
      }
    ],
    "tuned_model": {
      "name": "my-qlora-tuned-model-2491b2d9-bf96-4d3f-9ea7-8604861471e1"
    }
  },
  "metadata": {
    "created_at": "2025-02-14T19:47:36.629Z",
    "id": "2491b2d9-bf96-4d3f-9ea7-8604861471e1",
    "modified_at": "2025-02-14T19:47:36.629Z",
    "name": "My QLoRA experiment",
    "project_id": "<project-id>"
  }
}

사용자 정의 매개변수 사용

파인 튜닝 API는 훈련 페이로드에서 선택적 custom 객체를 지원하며, 이를 통해 임의의 매개변수를 기본 트레이너(fms-hf-tuning)에 직접 전달할 수 있습니다. 이 고급 기능은 표준 옵션 이상의 훈련 매개변수를 구성해야 하는 숙련된 사용자에게 유연성을 제공합니다.

중요: 사용자 정의 매개변수 사용은 기본적으로 활성화되어 있지 않습니다. 사용자 지정 매개변수를 사용하기 전에, 클러스터 관리자가 이 기능을 활성화했는지 확인하십시오.

동작

이 옵션이 활성화되면 : 내의 custom.parameters 값들이 생성된 트레이너 구성에 병합됩니다. 키가 표준 매개변수와 충돌하는 경우, 사용자 정의 값이 우선 적용됩니다(재정의 순서: custom.parameters > parameters).
비활성화 시 : 해당 custom 객체는 저장되며 API 응답에 반환되지만, custom.parameters 훈련에는 아무런 영향을 미치지 않습니다.
검증 : 사용자 정의 매개변수에 대해서는 검증이 수행되지 않습니다. 호환되지 않는 매개변수를 사용하면 트레이너가 제출 시점이 아닌 실행 시점에 오류가 발생합니다.

경고 메세지

사용자 정의 매개변수가 사용될 경우, API는 배열 system.warnings 형태로 경고를 반환합니다:

기능 활성화됨 : custom_parameters_warning - "사용자 지정 훈련 매개변수를 사용할 경우, 그 결과는 전적으로 사용자의 책임입니다. 사용자 정의 매개변수는 충돌하는 표준 훈련 매개변수를 우선 적용하며, 호환되지 않을 수 있어 훈련이 실패할 수 있습니다
비활성화된 기능 : custom_parameters_unsupported_warning - "사용자 지정 훈련 매개변수는 지원되지 않으며 무시됩니다."

사용자 정의 매개변수가 포함된 요청 예시

다음 예제는 사용자 정의 매개변수가 포함된 LoRA 파인 튜닝 요청을 보여줍니다:

{
  "name": "my-lora-fine-tuning",
  "space_id": "<space-id>",
  "auto_update_model": true,
  "parameters": {
    "base_model": {
      "model_id": "google/flan-t5-xl"
    },
    "task_id": "classification",
    "accumulate_steps": 1,
    "num_epochs": 5,
    "learning_rate": 0.00005,
    "batch_size": 16,
    "max_seq_length": 2048,
    "response_template": "\n### Response:",
    "verbalizer": "### Input:  \n\n### Response: ",
    "gpu": {
      "num": 1
    },
    "peft_parameters": {
      "type": "lora",
      "rank": 16,
      "target_modules": ["all-linear"],
      "lora_alpha": 32,
      "lora_dropout": 0.05
    },
    "gradient_checkpointing": true
  },
  "custom": {
    "parameters": {
      "data_formatter_template": "Custom ### Input:  \n\n### Response: ",
      "num_train_epochs": 10,
      "use_flash_attn": true
    }
  },
  "results_reference": {
    "connection": {},
    "location": {
      "path": "fine-tuning/experiment1"
    },
    "type": "container"
  },
  "training_data_references": [
    {
      "connection": {},
      "type": "data_asset",
      "location": {
        "href": "https://api.dataplatform.cloud.ibm.com/v2/assets/<asset-id>?space_id=<space-id>",
        "id": "<asset-id>"
      }
    }
  ]
}

사용자 정의 매개변수가 포함된 응답 예시**

응답에는 객체와 custom 배열에 system.warnings 포함된 경고 메시지가 포함되어 있습니다:

{
  "entity": {
    "custom": {
      "parameters": {
        "data_formatter_template": "Custom ### Input:  \n\n### Response: ",
        "num_train_epochs": 10,
        "use_flash_attn": true
      }
    },
    "parameters": {
      "accumulate_steps": 1,
      "base_model": { "model_id": "google/flan-t5-xl" },
      "batch_size": 16,
      "gpu": { "num": 1 },
      "gradient_checkpointing": true,
      "learning_rate": 0.00005,
      "max_seq_length": 2048,
      "num_epochs": 5,
      "peft_parameters": {
        "type": "lora",
        "rank": 16,
        "target_modules": ["all-linear"],
        "lora_alpha": 32,
        "lora_dropout": 0.05
      },
      "response_template": "\n### Response:",
      "task_id": "classification",
      "verbalizer": "### Input:  \n\n### Response: "
    },
    "results_reference": {
      "connection": {},
      "location": {
        "path": "fine-tuning/experiment1",
        "training": "fine-tuning/experiment1/<training-id>",
        "training_status": "fine-tuning/experiment1/<training-id>/training-status.json",
        "assets_path": "fine-tuning/experiment1/<training-id>/assets",
        "model_path": "fine-tuning/experiment1/<training-id>/model",
        "training_log": "fine-tuning/experiment1/<training-id>/data/fine_tunings/training.log"
      },
      "type": "container"
    },
    "status": {
      "state": "pending"
    },
    "training_data_references": [
      {
        "connection": {},
        "type": "data_asset",
        "location": {
          "href": "https://api.dataplatform.cloud.ibm.com/v2/assets/<asset-id>?space_id=<space-id>",
          "id": "<asset-id>"
        }
      }
    ],
    "tuned_model": {
      "name": "my-lora-fine-tuning-<training-id>"
    }
  },
  "metadata": {
    "created_at": "2025-10-14T20:17:50.445Z",
    "id": "<training-id>",
    "name": "my-lora-fine-tuning",
    "space_id": "<space-id>"
  },
  "system": {
    "warnings": [
      {
        "id": "custom_parameters_warning",
        "message": "Custom training parameters are used at your own risk. Custom parameters will override conflicting standard training parameters and may be incompatible, potentially causing training to fail."
      }
    ]
  }
}

중요: 사용자 정의 매개변수는 신중하게 사용하십시오. 이들은 검증 과정 없이 기본 트레이너로 직접 전달되며, 호환되지 않는 값이 제공될 경우 훈련이 실패할 수 있습니다. 충돌이 발생할 경우 사용자 정의 매개변수가 표준 매개변수보다 우선 적용됩니다.

훈련 작업 상태 확인

교육 작업의 상태를 확인하려면 다음 요청을 사용하십시오.

POST 요청에 반환된 metadata.id 를 사용하여 요청의 ID 경로 매개변수의 값으로 포함하십시오.
```
curl --request GET 'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/fine_tunings/2491b2d9-bf96-4d3f-9ea7-8604861471e1?project_id=<project-id>&version=2025-02-14'
```
API 참조는 미세 조정 작업 가져오기를 참고하세요.

튜닝 실험은 상태가 completed 일 때 완료됩니다.

"auto_update_model": true 를 요청에 포함시킨 경우, GET 요청의 응답에 entity.tuned_model.id 필드에 튜닝된 모델 또는 어댑터의 모델 자산 ID가 나열됩니다. 모델 자산 ID를 메모해 두세요.
watsonx.ai 의 API를 사용하여 조정된 모델을 배포하십시오.

조정된 모델을 배포하려면, 사용된 조정 방법에 적합한 단계를 완료해야 합니다.
- 저차 적응 또는 양자화된 저차 적응: 다음 작업을 완료하십시오
  1. 기본 모델 자산을 만듭니다.
    
    모델 자산은 기본 모델로 사용될 기초 모델의 메타데이터를 정의합니다. 모델 자산 만들기 참조.
  2. 기본 기초 모델을 배치합니다.
    
    추론 시에 사용할 수 있는 기본 기초 모델의 전용 인스턴스가 필요합니다. 기본 모델 배포를 참조하세요.
  3. 조정 실험을 통해 생성된 저급 어댑터 자산을 배치합니다.
    
    추론 시에 기본 모델 가중치를 조정할 수 있는 어댑터를 배치하여 작업에 대한 출력을 사용자 정의하십시오. LoRA 어댑터 모델 자산 배포를 참조하십시오.
- 완전한 미세 조정: 미세 조정된 모델 배포하기를 참조하세요.
조정된 모델을 호스팅하는 배포 환경의 고유 ID가 포함된 추론 엔드포인트를 사용하여 조정된 파운데이션 모델을 추론합니다.

Python

IBM watsonx.ai 에서 기초 모델을 프로그래밍 방식으로 미세 조정할 수 있습니다. TuneExperiment Python 라이브러리의 클래스입니다. 자세한 내용은 ‘ TuneExperiment 사용’ 및 ‘ FineTuner ’을 참조하십시오.

이 FoundationModelsManager 클래스에는 조정 가능한 파운데이션 모델 목록을 가져오는 데 사용할 수 있는 여러 헬퍼 메서드가 있습니다. 자세한 내용은 파운데이션 모델 헬퍼 메서드를 참조하십시오.

시작하려면 다음 샘플 노트북을 참고하세요:

Node.js

IBM watsonx.ai 에서 기초 모델을 프로그래밍 방식으로 미세 조정할 수 있습니다. createFineTuning Python 라이브러리의 클래스입니다. 자세한 정보는 다음 사이트를 참조하십시오.

자세한 내용은 코드 예제를 참조하세요.