AI_EXTRACT

AI_EXTRACT

AI_EXTRACT() 함수는 입력 문자열이나 파일에서 정보를 추출해요.

출처: Snowflake SQL Reference

본문

문법

입력 문자열에서 정보 추출:

AI_EXTRACT( <text>, <responseFormat> )

AI_EXTRACT( text => <text>,
            responseFormat => <responseFormat>,
            [ scores => TRUE | FALSE ] )

파일에서 정보 추출:

AI_EXTRACT( <file>, <responseFormat> )

AI_EXTRACT( file => <file>,
            responseFormat => <responseFormat>,
            [ config => <config_object> ],
            [ scores => TRUE | FALSE ] )

인자

text — 추출할 입력 문자열이에요.

file — 추출할 FILE이에요. 지원되는 파일 형식:

• PDF
• PNG
• PPTX, PPT
• EML
• DOC, DOCX
• JPEG, JPG
• HTM, HTML
• TEXT, TXT
• TIF, TIFF
• BMP, GIF, WEBP
• MD

파일은 100 MB 미만이어야 해요.

responseFormat — 추출할 정보예요. 형식은 추출 유형에 따라 달라져요.

엔티티 추출 형식 (Entity extraction formats)

단일 값을 추출하려면 다음 형식 중 하나를 제공하세요.

레이블과 추출할 정보를 매핑하는 단순 객체 스키마:

{'name': 'What is the last name of the employee?', 'address': 'What is the address of the employee?'}

추출할 정보를 담은 문자열 배열:

['What is the last name of the employee?', 'What is the address of the employee?']

두 문자열(레이블과 추출할 정보)을 담은 배열의 배열:

[['name', 'What is the last name of the employee?'], ['address', 'What is the address of the employee?']]

하위 객체에 'type': 'string'이 있는 JSON 스키마:

{
  'schema': {
 'type': 'object',
 'properties': {
   'title': {
     'description': 'What is the title of the document?',
     'type': 'string'
   }
 }
  }
}

목록 추출 형식 (List extraction format)

하위 객체에 'type': 'array'가 있는 JSON 스키마로 값 배열을 추출해요:

{
  'schema': {
    'type': 'object',
    'properties': {
      'employees': {
        'description': 'What are the names of employees?',
        'type': 'array'
      }
    }
  }
}

테이블 추출 형식 (Table extraction format)

'type': 'object'와 column_ordering이 있는 JSON 스키마로 표 형식 데이터를 추출해요. 각 열은 'type': 'array'를 가진 중첩 속성으로 정의되며, 설명은 파일의 열 이름과 일치해요:

{
  'schema': {
    'type': 'object',
    'properties': {
      'income_table': {
        'description': 'Income for FY2026Q2',
        'type': 'object',
        'column_ordering': ['month', 'income'],
        'properties': {
          'month': {
            'description': 'Month',
            'type': 'array'
          },
          'income': {
            'description': 'Income',
            'type': 'array'
          }
        }
      }
    }
  }
}

참고: JSON 스키마 형식을 다른 응답 형식과 결합할 수 없어요. responseFormat에 schema 키가 포함되면 모든 질문을 JSON 스키마 안에서 정의해야 해요. 추가 키는 지원되지 않아요.

모델은 특정 형태의 JSON 스키마만 받아들여요. 최상위 type은 항상 object여야 하며, 독립적으로 추출된 하위 객체들을 포함해요. 하위 객체는 테이블(열을 나타내는 문자열 목록의 객체), 문자열 목록, 또는 문자열일 수 있어요.

현재 지원되는 유일한 스칼라 타입은 string이에요.

description 필드를 사용해 모델에 맥락을 제공하세요. 예를 들어 모델이 문서에서 올바른 테이블을 찾도록 도울 수 있어요. 열 머리글 이름을 입력하거나 다른 방식으로 열을 설명할 수 있어요.

column_ordering 필드를 사용해 추출된 테이블의 모든 열 순서를 지정하세요. column_ordering 필드는 대소문자를 구분하며 properties 필드에 정의된 열 이름과 일치해야 해요. 순서는 문서의 열 순서를 반영해야 해요.

scores (선택) — 위에 표시된 명명 인자 문법에서만 지원돼요. 함수가 추출된 값에 대한 점수를 반환할지 제어하는 BOOLEAN이에요. 기본값은 FALSE예요. TRUE일 때 JSON 결과는 response에 더해 채점(scoring) 객체를 포함해요. 출력 형식, SQL 예제, 제한 사항은 Extraction scores 참고.

config (선택) — 구성 설정을 지정하는 OBJECT 값이에요. OBJECT 상수를 사용해 이 객체를 지정할 수 있어요. 이 객체에서 다음 키-값 쌍을 지정할 수 있어요.

키	설명
scale_factor	1.0부터 4.0까지의 숫자 값. 기본 모델이 처리하기 전에 입력 파일의 페이지를 조정해 OCR 품질을 높이고 추출 결과를 개선할 수 있음. 다음 시나리오에서 예기치 않거나 불명확한 응답을 받으면 scale_factor를 사용하세요. - A4보다 큰 페이지 크기의 문서 - 작은 텍스트, 세밀한 시각 요소, 밀집된 레이아웃을 포함하는 문서 - 추출된 텍스트에 오타나 문자 수준 OCR 오류가 있음. 생략하면 AI_EXTRACT는 기본값('scale_factor': 1.0)을 사용함.

반환

추출된 정보를 담은 JSON 객체를 반환해요. 응답의 구조는 추출 유형에 따라 달라져요.

엔티티 추출

각 추출 엔티티에 대한 키-값 쌍을 담은 JSON 객체를 반환해요:

{
  "error": null,
  "response": {
    "title": "Financial report"
  }
}

목록 추출

추출된 값의 배열을 담은 JSON 객체를 반환해요:

{
  "error": null,
  "response": {
    "employees": [
      "Smith",
      "Johnson",
      "Doe"
    ]
  }
}

테이블 추출

추출된 테이블을 나타내는 열 배열을 담은 JSON 객체를 반환해요:

{
  "error": null,
  "response": {
    "income_table": {
      "income": ["$120 678","$130 123","$150 998"],
      "month": ["February", "March", "April"]
    }
  }
}

결합 추출

단일 호출에서 엔티티, 목록, 테이블을 추출하면 응답에 모든 추출 유형이 포함돼요:

{
  "error": null,
  "response": {
    "employees": [
      "Smith",
      "Johnson",
      "Doe"
    ],
    "income_table": {
      "income": ["$120 678","$130 123","$150 998"],
      "month": ["February", "March", "April"]
    },
    "title": "Financial report"
  }
}

추출 점수 (Extraction scores)

AI_EXTRACT를 사용할 때 각 추출 값에 대한 모델의 확신도를 나타내는 점수를 요청할 수 있어요. 이 점수를 사용해 사람 검토를 위해 낮은 점수의 추출을 플래그 지정하는 등 비즈니스 로직의 임계값을 설정할 수 있어요.

점수가 높을수록 추출된 값이 정확할 가능성이 높아요. 서로 다른 문서에서 특정 엔티티 추출에 대한 점수를 비교해 어느 값이 더/덜 신뢰할 수 있는지 파악하고, 임계값, 폴백 메커니즘, 사람 개입 워크플로 같은 결정적 처리 로직을 구축하는 데 사용할 수 있어요.

점수 작동 방식

scores 매개변수를 TRUE로 설정하면 AI_EXTRACT는 표준 response 객체와 함께 채점 객체를 반환해요. 채점 객체는 각 추출 필드에 대한 점수를 담고 있어요. scores 매개변수는 선택 사항이며 기본값은 FALSE예요. Arguments에 표시된 명명 인자 문법에서 선택적 scores 인자를 사용하세요.

채점 출력 형식

scores => TRUE일 때 반환된 JSON에는 채점 객체가 포함돼요:

{
  "response": {
    "name": "John Smith",
    "address": "123 Main St, San Francisco"
  },
  "scoring": {
    "scores": {
      "name": {
        "score": 0.95
      },
      "address": {
        "score": 0.82
      }
    }
  },
  "error": null
}

scoring.scores의 각 필드는 response의 필드에 대응하며 0과 1 사이의 점수 값을 담고 있어요.

목록 추출의 경우 채점 객체는 전체 목록에 대한 집계 점수를 반환해요:

{
  "response": {
    "employees": ["Smith", "Johnson", "Doe"]
  },
  "scoring": {
    "scores": {
      "employees": {
        "score": 0.77
      }
    }
  },
  "error": null
}

테이블 추출의 경우 채점 객체는 전체 테이블에 대한 집계 점수를 반환해요:

{
  "response": {
    "income_table": {
      "month": ["February", "March", "April"],
      "income": ["$120 678", "$130 123", "$150 998"]
    }
  },
  "scoring": {
    "scores": {
      "income_table": {
        "score": 0.85
      }
    }
  },
  "error": null
}

채점 사용 노트

• 점수를 요청해도 추가 비용이 발생하지 않아요. AI_EXTRACT 비용에 대한 일반 정보는 Cost considerations 참고.
• 개별 목록 항목과 테이블 셀에 대한 요소별 점수는 제공되지 않아요.
• 점수는 파인튜닝된 모델에서 지원돼요.

추출 점수 예제

다음 예제는 파일에서 정보를 추출하고 각 추출 필드에 대한 점수를 반환해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'document.pdf'),
  responseFormat => {'name': 'What is the last name of the employee?', 'date': 'What is the inspection date?'},
  scores => TRUE
);

결과:

{
  "response": {
    "date": "2022-04-01",
    "name": "Johnson"
  },
  "scoring": {
    "scores": {
      "date": {
        "score": 0.96
      },
      "name": {
        "score": 0.99
      }
    }
  },
  "error": null
}

다음 예제는 구매자 이름 목록을 추출하고 집계 점수를 반환해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'agreement.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'buyer_list': {
          'description': 'What are the buyer names?',
          'type': 'array'
        }
      }
    }
  },
  scores => TRUE
);

결과:

{
  "response": {
    "buyer_list": [
      "John Davis",
      "Jane Davis"
    ]
  },
  "scoring": {
    "scores": {
      "buyer_list": {
        "score": 0.91
      }
    }
  },
  "error": null
}

다음 예제는 테이블을 추출하고 집계 점수를 반환해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'income_table': {
          'description': 'Income for FY2026Q2',
          'type': 'object',
          'column_ordering': ['month', 'income'],
          'properties': {
            'month': {
              'description': 'Month',
              'type': 'array'
            },
            'income': {
              'description': 'Income',
              'type': 'array'
            }
          }
        }
      }
    }
  },
  scores => TRUE
);

결과:

{
  "response": {
    "income_table": {
      "income": ["$120 678", "$130 123", "$150 998"],
      "month": ["February", "March", "April"]
    }
  },
  "scoring": {
    "scores": {
      "income_table": {
        "score": 0.88
      }
    }
  },
  "error": null
}

접근 제어 요구사항

사용자는 SNOWFLAKE.CORTEX_USER 데이터베이스 역할이 부여된 역할을 사용해야 해요. 이 권한 부여에 대한 정보는 Cortex LLM 권한을 참고하세요.

사용 노트

AI_EXTRACT는 디지털에서 만들어진 문서와 스캔된 문서 모두에 최적화되어 있어요.

같은 함수 호출에서 text와 file 매개변수를 동시에 사용할 수 없어요.

자연어로 질문하거나 추출할 정보(예: 도시, 거리, 우편번호)를 설명할 수 있어요. 예:

{'address': 'City, street, ZIP', 'name': 'First and last name'}

다음 언어가 지원돼요: 아랍어, 벵골어, 버마어, 세부아노어, 중국어, 체코어, 네덜란드어, 영어, 프랑스어, 독일어, 히브리어, 힌디어, 인도네시아어, 이탈리아어, 일본어, 크메르어, 한국어, 라오어, 말레이어, 페르시아어, 폴란드어, 포르투갈어, 러시아어, 스페인어, 타갈로그어, 태국어, 터키어, 우르두어, 베트남어.

문서는 최대 125페이지여야 해요.

단일 AI_EXTRACT 호출에서 엔티티 추출에 최대 100개, 테이블 추출에 최대 10개의 질문을 할 수 있어요.

테이블 추출 질문 하나는 엔티티 추출 질문 10개와 같아요. 예를 들어 단일 AI_EXTRACT 호출에서 테이블 추출 질문 4개와 엔티티 추출 질문 60개를 할 수 있어요.

엔티티 추출의 최대 출력 길이는 질문당 512토큰이에요. 테이블 추출의 경우 모델은 최대 4096토큰의 답변을 반환해요.

명명 인자와 scores => TRUE를 전달해 선택적 추출 점수를 요청할 수 있어요. 자세한 내용은 Extraction scores 참고.

AI_EXTRACT는 클라이언트 측 또는 서버 측 암호화를 사용하는 스테이지의 문서를 지원하며, PrivateLink나 스테이지에 대한 공용 네트워크 접근을 제한하는 기타 네트워크 정책을 사용하는 계정도 포함해요. Snowflake에서 구성한 클라이언트 측 암호화(예: COPY INTO 문 사용)를 사용하는 외부 스테이지의 파일도 지원돼요.

비용 고려사항 (Cost considerations)

Cortex AI_EXTRACT 함수는 문서당 페이지 수, 입력 프롬프트 토큰, 처리된 출력 토큰에 따라 컴퓨팅 비용이 발생해요.

• 페이지 형식 파일(PDF, DOCX, TIF, TIFF)의 경우 각 페이지는 970토큰으로 계산돼요.
• 이미지 형식 파일(JPEG, JPG, PNG)의 경우 각 개별 이미지 파일은 페이지로 청구되며 970토큰으로 계산돼요.

scale_factor 매개변수를 사용하면 소비되는 토큰 수와 호출당 처리 가능한 페이지 수가 달라져요.

• 소비되는 입력 토큰 수는 scale_factor에 비례해 증가해요.
• AI_EXTRACT가 처리할 수 있는 문서당 최대 페이지 수는 scale_factor만큼 감소해요.

scale_factor와 토큰·페이지 수의 관계:

scale_factor 값	페이지당 토큰 수	문서당 최대 페이지 수
2	970 * 2 = 1940 토큰	125/2 = 62.5 (내림해 62)
2.5	970 * 2.5 = 2425 토큰	125/2.5 = 50
4	970 * 4 = 3880 토큰	125/4 = 31.25 (내림해 31)

Snowflake는 Cortex AI_EXTRACT 함수를 호출하는 쿼리를 MEDIUM보다 크지 않은 더 작은 웨어하우스에서 실행할 것을 권장해요. 더 큰 웨어하우스는 성능을 높이지 않아요.

지역 가용성 (Regional availability)

AI_EXTRACT는 다음 지역의 계정에서 사용할 수 있어요.

클라우드 플랫폼	지역 이름
Amazon Web Services (AWS)	US East (N. Virginia), US West (Oregon), Canada (Central), South America (Sao Paulo), EU (Ireland), EU (Frankfurt), Asia Pacific (Tokyo), Asia Pacific (Sydney)
Microsoft Azure	East US 2 (Virginia), West US 2 (Washington), South Central US (Texas), North Europe (Ireland), West Europe (Netherlands), Southeast Asia (Singapore), Australia East (New South Wales), Central India (Pune), Japan East (Tokyo)
Google Cloud Platform	Middle East Central2 (Dammam)

AI_EXTRACT는 크로스 리전 지원이 있어요. Cortex AI 크로스 리전 지원 활성화에 대한 정보는 Cross-region inference 문서를 참고하세요.

오류 조건 (Error conditions)

AI_EXTRACT는 다음 오류 메시지를 낼 수 있어요.

메시지	설명
Internal error.	시스템 오류 발생. 잠시 기다렸다 다시 시도. 오류가 지속되면 Snowflake 지원에 문의.
Not found. / Provided file cannot be found.	파일을 찾을 수 없음.
Provided file cannot be accessed.	현재 사용자에게 파일 접근 권한이 충분하지 않음.
The provided file format {file_extension} isn't supported.	문서가 지원되지 않는 형식임.
The provided file isn't in the expected format or is corrupted.	문서가 손상되었거나 지원되지 않는 형식임.
Empty request.	제공된 매개변수가 없음.
Missing or empty response format.	제공된 응답 형식이 없음.
Invalid response format.	응답 형식이 유효한 JSON이 아님.
Duplicate feature name found: {feature_name}.	응답 형식에 하나 이상의 중복 기능 이름이 있음.
Too many questions: {number} complex and {number} simple = {number} total, complex question weight {number}.	질문 수가 허용 한도를 초과함.
Maximum number of 125 pages exceeded. The document has {actual_pages} pages.	문서가 125페이지 한도를 초과함.
Page size in pixels exceeds 10000x10000. The page size is {actual_px} pixels.	이미지 입력 또는 변환된 문서 페이지가 지원되는 크기보다 큼.
Page size in inches exceeds 50x50 (3600x3600 pt). The page size is {actual_in} inches ({actual_pt} pt).	페이지가 지원되는 크기보다 큼.
Maximum file size of 104857600 bytes exceeded. The file size is {actual_size} bytes.	문서가 100 MB보다 큼.

예제

엔티티 추출

다음 예제는 간단한 객체 스키마를 사용해 입력 텍스트에서 엔티티를 추출해요:

SELECT AI_EXTRACT(
  text => 'John Smith lives in San Francisco and works for Snowflake',
  responseFormat => {'name': 'What is the first name of the employee?', 'city': 'What is the address of the employee?'}
);

다음 예제는 입력 텍스트에서 엔티티를 추출하고 파싱해요:

SELECT AI_EXTRACT(
  text => 'John Smith lives in San Francisco and works for Snowflake',
  responseFormat => PARSE_JSON('{"name": "What is the first name of the employee?", "address": "What is the address of the employee?"}')
);

다음 예제는 document.pdf 파일에서 엔티티를 추출해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files','document.pdf'),
  responseFormat => [['name', 'What is the first name of the employee?'], ['city', 'Where does the employee live?']]
);

다음 예제는 스테이지의 디렉토리에 있는 모든 파일에서 엔티티를 추출해요:

참고: 디렉토리 테이블을 활성화해야 해요. 자세한 내용은 Manage directory tables 문서 참고.

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', relative_path),
  responseFormat => [
 'What is the document ID?',
 'What is the address of the company?'
  ]
) FROM DIRECTORY (@db.schema.files);

다음 예제는 JSON 스키마를 사용해 report.pdf 파일에서 title 엔티티를 추출해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
 'schema': {
   'type': 'object',
   'properties': {
     'title': {
       'description': 'What is the title of document?',
       'type': 'string'
     }
   }
 }
  }
);

목록 추출

다음 예제는 report.pdf 파일에서 employees 목록을 추출해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'employees': {
          'description': 'What are the surnames of employees?',
          'type': 'array'
        }
      }
    }
  }
);

테이블 추출

다음 예제는 report.pdf 파일에서 income_table 테이블을 추출해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'income_table': {
          'description': 'Income for FY2026Q2',
          'type': 'object',
          'column_ordering': ['month', 'income'],
          'properties': {
            'month': {
              'description': 'Month',
              'type': 'array'
            },
            'income': {
              'description': 'Income',
              'type': 'array'
            }
          }
        }
      }
    }
  }
);

결합 추출

다음 예제는 단일 호출에서 report.pdf 파일에서 테이블(income_table), 엔티티(title), 목록(employees)을 추출해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'income_table': {
          'description': 'Income for FY2026Q2',
          'type': 'object',
          'column_ordering': ['month', 'income'],
          'properties': {
            'month': {
              'description': 'Month',
              'type': 'array'
            },
            'income': {
              'description': 'Income',
              'type': 'array'
            }
          }
        },
        'title': {
          'description': 'What is the title of document?',
          'type': 'string'
        },
        'employees': {
          'description': 'What are the surnames of employees?',
          'type': 'array'
        }
      }
    }
  }
);

사용자 지정 확대 비율로 추출

다음 예제는 스케일 팩터 2.0을 사용해 report.pdf 파일에서 employees 배열을 추출해요:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'employees': {
          'description': 'What are the surnames of employees?',
          'type': 'array'
        }
      }
    }
  },
  config => {'scale_factor': 2.0}
);

파인튜닝된 arctic-extract 모델로 추출

파인튜닝된 arctic-extract 모델을 AI_EXTRACT 함수의 추론에 사용하려면 다음 예제처럼 model 매개변수로 모델을 지정하세요:

SELECT AI_EXTRACT(
  model => 'db.schema.my_tuned_model',
  file => TO_FILE('@db.schema.files','document.pdf')
);

responseFormat 매개변수를 사용해 파인튜닝에 사용된 질문을 덮어쓸 수 있어요:

SELECT AI_EXTRACT(
  model => 'db.schema.my_tuned_model',
  file => TO_FILE('@db.schema.files','document.pdf'),
  responseFormat => [['name', 'What is the first name of the employee?'], ['city', 'Where does the employee live?']]
);

다음 예제는 파인튜닝된 arctic-extract 모델과 스케일 팩터 2.0을 사용해 invoice.pdf 파일에서 데이터를 추출해요:

SELECT AI_EXTRACT(
  model => 'db.schema.my_tuned_model',
  file => TO_FILE('@db.schema.files', 'invoice.pdf'),
  config => {'scale_factor': 2.0}
);

자세한 내용은 arctic-extract 모델 파인튜닝 문서를 참고하세요.

참고: AI_EXTRACT는 EXTRACT_ANSWER의 갱신된 버전이에요. 최신 기능을 사용하려면 AI_EXTRACT를 사용하세요.

법적 고지

법적 고지는 Snowflake AI and ML을 참고하세요.

더 알아보기 (Learn more)

• Snowflake Cortex AI 함수
• TO_FILE