Cortex Analyst의 커스텀 지침

커스텀 지침을 사용하면 SQL 생성에 대한 더 큰 제어가 가능합니다. 자연어로 Cortex Analyst에게 시맨틱 모델 YAML 파일 내에서 SQL 쿼리를 정확히 어떻게 생성할지 알려줄 수 있습니다. 예를 들어 커스텀 지침을 사용해 performance 또는 financial year가 무엇을 의미하는지 Cortex Analyst에게 알려줄 수 있습니다. 이렇게 하면 커스텀 로직이나 추가 요소를 통합해 생성된 SQL의 정확도를 개선할 수 있습니다.

더 세분화된 제어를 위해 SQL 생성 파이프라인의 개별 모듈에 대한 커스텀 지침을 지정할 수도 있습니다. 모듈 커스텀 지침 을 참고하세요.

출처: Snowflake 문서

본문

커스텀 지침의 작동 방식

Cortex Analyst는 custom_instructions 필드를 시맨틱 모델 YAML 파일에 도입합니다. 이 필드를 사용해 SQL 생성에 대한 정의적 수정 또는 추가를 적용할 수 있습니다.

시맨틱 모델 구문에 대한 자세한 내용은 SQL 명령으로 시맨틱 뷰 생성 및 관리 를 참고하세요.

예시

커스텀 지침의 가능한 사용 사례를 살펴보려면 다음 예시를 고려하세요.

데이터 출력 형식 지정

출력의 모든 숫자가 소수점 둘째 자리로 반올림되도록 하세요.

시맨틱 모델 YAML 파일의 `custom_instructions` 필드

custom_instructions: "Ensure that all numeric columns are rounded to 2 decimal points in the output."

생성된 SQL 쿼리

SELECT
  ROUND(column_name, 2) AS column_name,
  ...
FROM
  your_table;

백분율 조정

일관성을 위해 백분율 또는 비율 계산을 자동으로 100으로 곱하세요.

시맨틱 모델 YAML 파일의 `custom_instructions` 필드

custom_instructions: "For any percentage or rate calculation, multiply the result by 100."

생성된 SQL 쿼리

SELECT
  (column_a / column_b) * 100 AS percentage_rate,
  ...
FROM
  your_table;

기본 필터 추가

사용자가 필터를 지정하지 않으면 필터를 적용하세요 (예: 기본적으로 지난 해로).

시맨틱 모델 YAML 파일의 `custom_instructions` 필드

custom_instructions: "If no date filter is provided, apply a filter for the last year."

생성된 SQL 쿼리

SELECT
  ...
FROM
  your_table
WHERE
  date_column >= DATEADD(YEAR, -1, CURRENT_DATE);

열 필터 연결

사용자 입력을 기반으로 관련 열에 추가 필터를 적용하세요.

시맨틱 모델 YAML 파일의 `custom_instructions` 필드

custom_instructions: "If a filter is applied on column X, ensure that the same filter is applied to dimension Y."

생성된 SQL 쿼리

SELECT
  ...
FROM
  your_table
WHERE
  column_x = 'filter_value' AND
  dimension_y = 'filter_value';

모듈 커스텀 지침

시맨틱 모델의 최상위 수준에 module_custom_instructions 키를 설정해 SQL 생성 파이프라인의 특정 컴포넌트에 대한 커스텀 지침을 정의하세요. 이 기능은 다음과 같은 사용 사례에 유용합니다.

SQL이 생성되기 전에 사용자 질문이 해석되는 방식에 영향을 주는 로직 정의
Analyst 워크플로우의 다른 부분에 대해 별도의 더 구조화된 지침을 유지 관리
사용량이 늘어남에 따라 기존 custom_instructions에서 더 모듈식 형식으로 전환

현재 module_custom_instructions는 다음 컴포넌트를 지원합니다.

question_categorization: Cortex Analyst가 사용자 질문을 분류하는 방식을 정의합니다 (예: 특정 주제 차단 또는 사용자 동작 안내).
sql_generation: SQL이 생성되는 방식을 지정합니다 (예: 데이터 형식 및 필터링).

module_custom_instructions 키 아래에 이 컴포넌트 중 하나 또는 둘 다에 대한 지침을 설정할 수 있습니다.

중요

다음 예시와 같이 기존 custom_instructions를 sql_generation 컴포넌트로 마이그레이션하세요.

기존 커스텀 지침 마이그레이션

모델에 이미 custom_instructions 필드가 있다면 그 내용을 module_custom_instructions 아래의 sql_generation 필드로 마이그레이션하세요.

custom_instructions: "Ensure that all numeric columns are rounded to 2 decimal points."

이후:

module_custom_instructions:
  sql_generation: |
     "Ensure that all numeric columns are rounded to 2 decimal points."

특정 주제에 대한 질문 차단

question_categorization 컴포넌트를 사용해 특정 주제에 대한 질문을 차단할 수 있습니다. 예를 들어 사용자에 대한 질문을 차단하려면 다음 지침을 설정할 수 있습니다. 그러면 Cortex Analyst는 관리자에게 문의하라는 메시지와 함께 사용자에 대한 질문을 거부합니다.

module_custom_instructions:
  question_categorization: |
     Reject all questions asking about users. Ask users to contact their admin.

또한 질문 분류 지침을 사용해 누락된 세부 정보를 요청할 수도 있습니다. 다음 예시에서 Cortex Analyst는 사용자에 대해 묻지만 특정 유형을 지정하지 않으면 제품 유형을 제공하도록 사용자에게 요청합니다.

module_custom_instructions:
  question_categorization: |
    - If the question asks for users without providing a product_type, consider this question UNCLEAR and ask the user to specify product_type.

Cortex Agents를 통한 커스텀 지침

Cortex Analyst가 Cortex Agent 내의 도구로 사용될 때, 에이전트는 커스텀 지침을 더 높은 충실도로 따릅니다. 이 모드에서 에이전트는 UNCLEAR 같은 특정 상태 키워드에 의존하지 않고 자연어 지침을 직접 해석합니다.

분류 상태를 참조하지 않고 평범한 언어로 커스텀 지침을 작성할 수 있습니다. 예를 들어:

module_custom_instructions:
  question_categorization: |
    - If the question asks for users without providing a product_type, ask the user to specify product_type.
    - Reject all questions about salary data and tell the user this information is not available.

분류 상태 키워드(예: UNCLEAR)는 Cortex Analyst API를 직접 사용할 때 계속 작동합니다. 그러나 시맨틱 모델이 Cortex Agent를 통해 접근될 때는, 에이전트가 미묘한 지침을 더 정확하게 따를 수 있으므로 평범한 자연어로 지침을 작성하는 것이 권장됩니다.

모범 사례

구체적으로 설명하세요. 수정 사항을 명확히 설명하세요; 예를 들어 "Add a column with a fixed value of 42" 또는 "Include a sum calculation for column X."
작게 시작하세요. 정적 열이나 기본 필터 추가 같은 간단한 수정부터 시작하고 더 복잡한 시나리오로 이동하세요.
생성된 SQL 쿼리를 미리 보세요. 지침이 의도한 대로 적용되고 생성된 SQL 쿼리가 올바른지 확인하세요.
점진적으로 반복하세요. 기능에 대한 친숙도가 커짐에 따라 더 복잡한 사용 사례를 실험하세요.

Cortex Analyst의 커스텀 지침