Hugging Face's logo

Transformers documentation

GraniteDocling

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.23.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

이 모델은 2026-11-12에 Hugging Face Transformers에 기여되었습니다.

FlashAttention SDPA

GraniteDocling

GraniteDocling은 문서 변환을 위한 비전-언어 모델입니다. 페이지 이미지가 주어지면 DocLang (<doclang>)을 생성합니다. 이는 읽기 순서대로 배치된 레이아웃 요소와 해당 바운딩 박스, 그리고 그 안에 포함된 텍스트, 표, 수식 및 코드를 나타냅니다. DocLang은 마크업이며, Docling (docling-core)은 예측 결과를 Markdown, HTML, JSON 및 기타 형식으로 내보낼 수 있는 문서로 파싱합니다.

512x512 픽셀 크기의 타일로 페이지가 분할되며, 이 타일들은 페이지의 종횡비에 가장 잘 맞는 그리드에 배치됩니다. 타일이 하나 이상인 경우 전체 페이지의 썸네일도 포함됩니다. 비전 인코더는 모든 타일을 임베딩하고, 픽셀 셔플 커넥터는 비전 패치를 이미지 토큰으로 매핑합니다. 중간 비전 인코더 상태도 투영되어 첫 번째 디코더 레이어 이후에 이미지 토큰에 추가됩니다. 이후 밀집형 Granite 스타일 텍스트 디코더가 DocLang을 생성합니다.

GraniteDocling은 두 가지 모델로 출시됩니다. 500M 모델은 타일당 64개의 이미지 토큰을 사용하며, 라우터가 페이지별로 판단하여 밀도가 높은 페이지의 경우 256개로 전환할 수 있습니다. 2B 모델은 픽셀 셔플 비율 2를 사용하여 타일당 256개의 이미지 토큰을 사용하며, 이는 500M 모델의 fine 경로와 동일한 밀도입니다.

Docling 프로젝트가 GraniteDocling을 만들었습니다. 두 모델 모두 IBM Granite 조직에 게시되어 있습니다.

GraniteDocling은 granite-docling-258M과 다른 아키텍처이며, Idefics3를 통해 로드됩니다.

이 모델은 Docling 팀에 의해 기여되었습니다.

GraniteDocling 모델을 적용하여 다양한 문서 변환 작업을 수행하는 방법에 대한 추가 예제는 오른쪽 사이드바의 GraniteDocling 모델에서 확인하세요.

사용 팁

  • 채팅 템플릿을 통해 모델에 프롬프트를 입력합니다. <doclang>은 전체 페이지를 변환합니다. 요소의 부분 집합을 요청하려면 괄호 목록을 추가합니다. 예를 들어 <doclang> [<ocr>] 또는 <doclang> [<ocr>, <layout>, <picture>]와 같이 사용할 수 있습니다.
  • 문자열을 DocLang로 파싱할 경우 skip_special_tokens=False로 디코딩하세요. 그렇지 않으면 전용 마크업 토큰이 제거됩니다.
  • 500M 모델에서는 밀집된 페이지(작은 글씨, 긴 표, 다중 열 텍스트)의 경우 fine_route=True를 전달하세요. 해당 경로는 이미지 토큰을 4배 많이 사용하므로 프롬프트가 길어지고 추론 속도가 느려집니다. 2B 모델은 이미 해당 토큰 밀도를 사용하며 두 번째 경로가 없으므로, fine_route=True를 전달하면 오류가 발생합니다.
  • 500M 모델에는 밀도 라우터가 포함되어 있으며, 이는 해당 작업을 대신 수행합니다: predict_fine_route()는 배치 중 어떤 페이지가 fine path가 필요한지 반환합니다.

아래 예시들은 Docling Technical Report (arXiv:2408.09869)의 1페이지를 변환합니다. 텍스트 프롬프트만 변경하면 작업을 전환할 수 있으며, 모델은 요청된 요소로 필터링된 DocLang을 반환합니다.

작업프롬프트
전체 페이지<doclang>
OCR<doclang> [<ocr>]
레이아웃<doclang> [<layout>]
테이블<doclang> [<table>]
수식<doclang> [<formula>]
코드<doclang> [<code>]
차트<doclang> [<chart>]
이미지<doclang> [<picture>]
결합<doclang> [<ocr>, <layout>, <picture>]

전체 페이지

<doclang>은 레이아웃, 텍스트, 표, 수식, 코드, 차트, 이미지 등 페이지 전체를 변환합니다.

Pipeline
AutoModel
from transformers import pipeline

pipe = pipeline(
    task="image-text-to-text",
    model="ibm-granite/granite-for-docling-500m",
)
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/ibm-granite/granite-for-docling-500m/resolve/main/docling_technical_report_p1.png"},
            {"type": "text", "text": "<doclang>"},
        ],
    }
]
pipe(text=messages, max_new_tokens=4096, return_full_text=False, skip_special_tokens=False)

일부 요소만 변환하려면 텍스트 프롬프트를 위 표의 항목 중 하나로 변경하세요. 예를 들어 <doclang> [<ocr>, <layout>, <picture>]처럼요. 나머지는 그대로 유지됩니다.

Dense 페이지: 정밀한 경로

fine connector 경로는 타일당 이미지 토큰을 4배 더 사용하며, 이는 작은 글씨, 긴 표, 여러 열의 텍스트에서 도움이 됩니다. 호출별로 fine_route=True를 선택하세요:

inputs = processor.apply_chat_template(
    conversation,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    processor_kwargs={"fine_route": True},
).to(model.device)
output = model.generate(**inputs, max_new_tokens=4096)

500M 모델(config.density_router_hidden_size이 설정됨)은 기본 이미지 토큰에서 어떤 페이지가 fine path가 필요한지 예측합니다:

needs_fine = model.model.predict_fine_route(inputs["pixel_values"], inputs["pixel_attention_mask"])  # (batch_size,) bool
if needs_fine[0]:
    inputs = processor.apply_chat_template(
        conversation,
        add_generation_prompt=True,
        tokenize=True,
        return_dict=True,
        return_tensors="pt",
        processor_kwargs={"fine_route": True},
    ).to(model.device)
output = model.generate(**inputs, max_new_tokens=4096)

배치 추론

페이지마다 타일 그리드가 다르므로 pixel_values는 배치 내 최대 타일 수로 패딩됩니다. pixel_attention_mask는 실제 타일을 표시하며 모델은 패딩을 폐기합니다.

pages = [
    "https://huggingface.co/ibm-granite/granite-for-docling-500m/resolve/main/docling_technical_report_p1.png",
    "https://huggingface.co/ibm-granite/granite-for-docling-500m/resolve/main/docling_technical_report_p1.png",
]
conversations = [
    [{"role": "user", "content": [{"type": "image", "url": url}, {"type": "text", "text": "<doclang>"}]}]
    for url in pages
]
inputs = processor.apply_chat_template(
    conversations,
    add_generation_prompt=True,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    processor_kwargs={"padding": True},
).to(model.device)

output = model.generate(**inputs, max_new_tokens=4096)
for row in output:
    doclang = processor.decode(row[inputs["input_ids"].shape[1] :], skip_special_tokens=False)
    print(doclang.removesuffix(processor.tokenizer.eos_token).strip())

processor_kwargs에 "fine_route": True를 추가하면 배치 전체가 fine 경로를 통해 라우팅되며, 프로세서가 tile_fine_mask를 반환합니다. 배치는 하나의 경로만 사용하므로, 라우터가 fine 경로로 보낸 페이지를 별도의 배치로 실행하세요.

Docling으로 DocLang 내보내기

docling-core는 AutoModel 예시의 doclang 문자열을 DoclingDocument로 파싱하며, 이를 원하는 형태로 직렬화할 수 있습니다.

from pathlib import Path
from docling_core.transforms.deserializer.doclang import DocLangDocDeserializer

document = DocLangDocDeserializer().deserialize_str(doclang)

print(document.export_to_markdown())
print(document.export_to_html())
print(document.export_to_dict())

document.save_as_markdown(Path("page.md"))
document.save_as_html(Path("page.html"))
document.save_as_json(Path("page.json"))

DocLang 스펙과 doclang 툴킷(validate / pack)은 doclang-project/doclang에 있습니다. 역직렬화기와 DoclingDocument 내보내기기는 docling-core에 있습니다.

The input is a single word "Notes". 참고

  • 전체 페이지는 길이가 길므로, DocLang이 조용히 잘리지 않도록 max_new_tokens를 수천 단위로 설정하세요.
  • Tiles은 512x512 크기로, 페이지의 종횡비에 가장 잘 맞는 그리드에 배치되며, max_patches(기본값 32) 및 한 변당 16개 타일 수로 제한됩니다. 하나의 타일에 들어가는 페이지에는 섬네일이 생성되지 않습니다.
  • 체크포인트는 이미지 프로세서 설정에 스프레드 규칙을 포함할 수 있습니다: 넓은 풍경 페이지(dense_min_aspect < width/height <= dense_max_aspect)의 경우 max_patches 대신 dense_max_patches 타일을 사용합니다. 이는 max_patches 그리드가 dense_max_scale 미만으로 축소하는 경우입니다. 신문 스프레드가 일반적인 사례입니다. 이 규칙은 기본적으로 비활성화되어 있으며(dense_max_patches=0), 체크포인트가 학습될 때 사용된 값과 일치해야 합니다.
  • 500M 모델에서 fine 경로는 타일당 이미지 토큰을 64개에서 256개로 4배 증가시킵니다. 이는 밀집된 페이지에만 사용하거나, predict_fine_route()를 사용하여 라우터가 결정하도록 하십시오. 2B 모델은 전체적으로 타일당 256개의 이미지 토큰을 사용합니다(픽셀 셔플 비율 2).

GraniteDoclingConfig

클래스 transformers.GraniteDoclingConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonevision_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneimage_token_id: int = 100337tie_word_embeddings: bool = Trueuse_cache: bool = Truepad_token_id: int | None = 100256density_router_hidden_size: int | None = Nonedensity_router_threshold: float = 0.4density_router_loss_weight: float = 0.1 )

매개변수

  • text_config (Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 텍스트 백본의 config 객체 또는 사전입니다.
  • vision_config (Union[dict, ~configuration_utils.PreTrainedConfig], 선택) — 비전 백본의 config 객체 또는 사전입니다.
  • image_token_id (int, 선택 사항, 기본값 100337) — 입력 이미지의 플레이스홀더로 사용되는 이미지 토큰 인덱스입니다.
  • tie_word_embeddings (bool, 선택, 기본값 True) — 모델의 tied_weights_keys 매핑에 따라 가중치 임베딩을 묶을지 여부.
  • use_cache (bool, 선택 사항, 기본값 True) — 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음). config.is_decoder=True인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다.
  • pad_token_id (int, 선택 사항, 기본값 100256) — 어휘에서 패딩에 사용되는 토큰 ID입니다.
  • density_router_hidden_size (int, 선택 사항) — 비전 인코더 특징을 기반으로 페이지가 fine connector 경로를 필요로 하는지 예측하는 density router의 hidden size입니다. None인 경우 라우터가 생성되지 않습니다.
  • density_router_threshold (float, 선택 사항, 기본값 0.4) — 밀도 라우터가 fine connector 경로를 선택하는 임계 확률입니다.
  • density_router_loss_weight (float, 선택 사항, 기본값 0.1) — router_labels이 주어졌을 때 밀도 라우터 손실의 가중치.

이것은 GraniteDoclingModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Granite Docling 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 ibm-granite/granite-for-docling-500m와 유사한 구성이 생성됩니다.

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

GraniteDoclingTextConfig

class transformers.GraniteDoclingTextConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 133800hidden_size: int = 1024intermediate_size: int = 2048num_hidden_layers: int = 28num_attention_heads: int = 16num_key_value_heads: int | None = 4hidden_act: str = 'silu'max_position_embeddings: int = 32768initializer_range: float = 0.02rms_norm_eps: float = 1e-05use_cache: bool = Truepad_token_id: int | None = 100256bos_token_id: int | None = 100257eos_token_id: int | list[int] | None = 100257tie_word_embeddings: bool = Truerope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: float | int = 0.0mlp_bias: bool = Falseembedding_multiplier: float | int = 12.0logits_scaling: float | int = 4.0residual_multiplier: float | int = 0.263attention_multiplier: float | int = 0.015625 )

매개변수

  • vocab_size (int, 선택 사항, 기본값 133800) — 모델의 어휘 크기입니다. input_ids로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다.
  • hidden_size (int, 선택 사항, 기본값 1024) — 숨겨진 표현의 차원입니다.
  • intermediate_size (int, 선택 사항, 기본값 2048) — MLP 표현의 차원입니다.
  • num_hidden_layers (int, 선택 사항, 기본값 28) — Transformer decoder의 숨겨진 레이어 수.
  • num_attention_heads (int, 선택 사항, 기본값 16) — Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다.
  • num_key_value_heads (int, 선택 사항, 기본값 4) — Grouped Query Attention 구현에 사용할 key_value 헤드 수입니다. num_key_value_heads=num_attention_heads이면 모델은 Multi Head Attention(MHA)을 사용하고, num_key_value_heads=1이면 Multi Query Attention(MQA)을 사용하며, 그 외에는 GQA를 사용합니다. 멀티 헤드 체크포인트를 GQA 체크포인트로 변환할 때, 각 그룹의 key 및 value 헤드는 해당 그룹 내 모든 원래 헤드를 평균 풀링(meanpooling)하여 구성해야 합니다. 자세한 내용은 이 논문을 참고하세요. 지정되지 않으면 num_attention_heads가 기본값으로 사용됩니다.
  • hidden_act (str, 선택 사항, 기본값 silu) — 디코더의 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어, "gelu", "relu", "silu" 등이 있습니다.
  • max_position_embeddings (int, 선택 사항, 기본값 32768) — 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다.
  • initializer_range (float, 선택 사항, 기본값 0.02) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.
  • rms_norm_eps (float, 선택 사항, 기본값 1e-05) — rms 정규화 레이어에서 사용되는 epsilon 값입니다.
  • use_cache (bool, 선택 사항, 기본값 True) — 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음). config.is_decoder=True인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다.
  • pad_token_id (int, 선택 사항, 기본값 100256) — 어휘에서 패딩에 사용되는 토큰 ID입니다.
  • bos_token_id (int, 선택 사항, 기본값 100257) — 어휘에서 스트림 시작에 사용되는 토큰 ID입니다.
  • eos_token_id (Union[int, list[int]], 선택 사항, 기본값 100257) — 어휘에서 스트림 종료에 사용되는 토큰 id입니다.
  • tie_word_embeddings (bool, 선택, 기본값 True) — 모델의 tied_weights_keys 매핑에 따라 가중치 임베딩을 묶을지 여부.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], 선택) — RoPE 임베딩의 구성 매개변수를 포함하는 사전입니다. 사전에는 rope_theta 값이 포함되어야 하며, 더 긴 max_position_embeddings로 RoPE를 사용하려는 경우 스케일링에 사용되는 매개변수를 선택적으로 포함할 수 있습니다.
  • attention_bias (bool, 선택 사항, 기본값 False) — 자기 주의(self-attention) 시 query, key, value 및 출력 투영 계층에 bias를 사용할지 여부입니다.
  • attention_dropout (Union[float, int], 선택 사항, 기본값 0.0) — Attention 확률에 적용할 dropout 비율입니다.
  • mlp_bias (bool, 선택 사항, 기본값 False) — MLP 레이어의 up_proj, down_proj, gate_proj 레이어에 bias를 사용할지 여부.
  • embedding_multiplier (Union[float, int], 선택 사항, 기본값 12.0) — 워드 임베딩에 적용되는 스케일링 계수입니다. 히든 사이즈에 대한 임베딩의 상대적 크기를 조절하는 데 사용됩니다.
  • logits_scaling (Union[float, int], 선택 사항, 기본값 4.0) — 확률 분포를 계산하기 전에 출력 logits에 적용되는 스케일링 계수입니다.
  • residual_multiplier (Union[float, int], 선택 사항, 기본값 0.263) — 잔차 연결에 적용되는 스케일링 계수입니다.
  • attention_multiplier (Union[float, int], 선택 사항, 기본값 0.015625) — Attention weights에 적용되는 스케일링 계수입니다.

이것은 GraniteDoclingModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Granite Docling 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 ibm-granite/granite-for-docling-500m와 유사한 구성이 생성됩니다.

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

>>> from transformers import GraniteDoclingTextModel, GraniteDoclingTextConfig

>>> # Initializing a GraniteDoclingText granite_docling_text-3b style configuration
>>> configuration = GraniteDoclingTextConfig()

>>> # Initializing a model from the granite_docling_text-7b style configuration
>>> model = GraniteDoclingTextModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

GraniteDoclingVisionConfig

class transformers.GraniteDoclingVisionConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 768intermediate_size: int = 3072num_hidden_layers: int = 12num_attention_heads: int = 12num_channels: int = 3image_size: int | list[int] | tuple[int, int] = 512patch_size: int | list[int] | tuple[int, int] = 16hidden_act: str = 'gelu_pytorch_tanh'layer_norm_eps: float = 1e-06attention_dropout: float | int = 0.0initializer_range: float = 0.02out_hidden_size: int = 1024scale_factor: int = 4deepstack_visual_indexes: list[int] | None = Noneuse_fine_route: bool = True )

매개변수

  • hidden_size (int, 선택 사항, 기본값 768) — 숨겨진 표현의 차원입니다.
  • intermediate_size (int, 선택 사항, 기본값 3072) — MLP 표현의 차원입니다.
  • num_hidden_layers (int, 선택 사항, 기본값 12) — Transformer 디코더의 숨겨진 레이어 수.
  • num_attention_heads (int, 선택 사항, 기본값 12) — Transformer decoder의 각 attention layer에 사용할 attention head의 수입니다.
  • num_channels (int, 선택 사항, 기본값 3) — 입력 채널의 수입니다.
  • image_size (Union[int, list[int], tuple[int, int]], 선택 사항, 기본값 512) — 각 이미지의 크기(해상도)입니다.
  • patch_size (Union[int, list[int], tuple[int, int]], 선택 사항, 기본값 16) — 각 패치의 크기(해상도)입니다.
  • hidden_act (str, 선택 사항, 기본값 gelu_pytorch_tanh) — 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어, "gelu", "relu", "silu" 등이 있습니다.
  • layer_norm_eps (float, 선택 사항, 기본값 1e-06) — 레이어 정규화 레이어에서 사용되는 epsilon 값입니다.
  • attention_dropout (Union[float, int], 선택 사항, 기본값 0.0) — Attention 확률에 적용할 dropout 비율입니다.
  • initializer_range (float, 선택 사항, 기본값 0.02) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.
  • out_hidden_size (int, 선택 사항, 기본값 1024) — 커넥터가 투영하는 텍스트 디코더의 히든 크기입니다.
  • scale_factor (int, 선택 사항, 기본값 4) — 커넥터의 픽셀 셔플 팩터입니다. (image_size // patch_size) ** 2개의 비전 토큰으로 구성된 각 타일은 scale_factor ** 2로 축소됩니다.
  • deepstack_visual_indexes (list[int], 선택 사항, 기본값 [3, 7, 10]) — DeepStack 머저에 의해 투영되는 비전 인코더 레이어의 인덱스입니다. 인덱스 0은 첫 번째 레이어의 출력을 나타냅니다.
  • use_fine_route (bool, 선택 사항, 기본값 True) — scale_factor의 절반만큼 픽셀을 섞는 fine connector 경로를 생성할지 여부입니다. 이 경로는 타일당 이미지 토큰을 4배로 증가시킵니다. 500M 체크포인트에는 해당 경로가 있지만, 2B 체크포인트에는 없습니다.

페이지의 모든 512x512 타일을 임베딩하는 SigLIP 스타일 비전 인코더와, 그 출력을 이미지 토큰으로 변환하는 커넥터의 구성입니다.

예:

>>> from transformers import GraniteDoclingVisionConfig, GraniteDoclingVisionModel

>>> # Initializing a GraniteDoclingVisionConfig with ibm-granite/granite-for-docling-500m style configuration
>>> configuration = GraniteDoclingVisionConfig()

>>> # Initializing a GraniteDoclingVisionModel (with random weights) from the ibm-granite/granite-for-docling-500m style configuration
>>> model = GraniteDoclingVisionModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

GraniteDoclingImageProcessor

class transformers.GraniteDoclingImageProcessor

< >

( **kwargs: *<class 'transformers.models.granite_docling.image_processing_granite_docling.GraniteDoclingImageProcessorKwargs'> )

매개변수

  • do_convert_rgb (bool, kwargs, 선택 사항, 기본값 True) — 이미지를 RGB로 변환할지 여부.
  • do_resize (bool, kwargs, 선택 사항, 기본값 True) — 이미지를 리사이즈할지 여부.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, 기본값 {'height' -- 512, 'width': 512}): 모델에 전달되는 최대 입력 차원을 설명합니다.
  • default_to_square (bool, kwargs, 선택 사항, 기본값 True) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부입니다.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — center_crop을 적용한 후 출력 이미지의 크기.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, 기본값 3) — 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. PILImageResampling enum 중 하나를 사용할 수 있습니다. do_resize가 True로 설정된 경우에만 효과가 있습니다.
  • do_rescale (bool, kwargs, 선택, 기본값 True) — 이미지를 다시 스케일링할지 여부.
  • rescale_factor (float, kwargs, 선택 사항, 기본값 0.00392156862745098) — do_rescale이 True로 설정된 경우 이미지를 재조정(rescale)하는 데 사용할 재조정 계수입니다.
  • do_normalize (bool, kwargs, 선택, 기본값 True) — 이미지를 정규화할지 여부.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, 선택, 기본값 [0.48145466, 0.4578275, 0.40821073]) — 정규화에 사용할 이미지 평균입니다. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, 선택, 기본값 [0.26862954, 0.26130258, 0.27577711]) — 정규화에 사용할 이미지 표준 편차입니다. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
  • do_pad (bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할 {"height": int, "width" int} 크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다. pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다. do_pad=True.일 때만 적용됩니다.
  • do_center_crop (bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:
    • "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
    • "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지.
    • "none" 또는 ChannelDimension.NONE: (height, width) 형식의 이미지.
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.
  • disable_grouping (bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다.
  • image_seq_length (int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.
  • crop_to_patches (bool, kwargs, 선택 사항, 기본값 True) — 페이지를 가로세로 비율에 가장 잘 맞는 그리드(한 변당 최대 16개 타일)에 배치된 512x512 타일로 분할할지 여부입니다. preprocess 메서드의 crop_to_patches 매개변수로 재정의할 수 있습니다.
  • min_patches (int, kwargs, 선택 사항, 기본값 1) — 페이지당 타일의 최소 개수입니다. crop_to_patches가 True로 설정된 경우에만 효과가 있습니다. preprocess 메서드의 min_patches 매개변수로 재정의할 수 있습니다.
  • max_patches (int, kwargs, 선택 사항, 기본값 32) — 페이지당 타일의 최대 수입니다. crop_to_patches가 True로 설정된 경우에만 효과가 있습니다. preprocess 메서드의 max_patches 매개변수로 재정의할 수 있습니다.
  • fine_route (bool, kwargs, 선택 사항, 기본값 False) — 페이지가 타일당 4배의 이미지 토큰을 생성하는 fine connector 경로를 사용하는지 여부.
  • dense_max_patches (int, kwargs, optional, 기본값 0) — 스프레드 규칙이 선택한 페이지에 대해 허용되는 최대 타일 수입니다(0이면 규칙 비활성화). max_patches 그리드가 dense_max_scale 미만으로 축소하고, 너비/높이 비율이 dense_min_aspect를 초과할 때(설정된 경우 dense_max_aspect 이하), max_patches 대신 최대 dense_max_patches개의 타일로 페이지가 타일링됩니다. 체크포인트는 동일한 규칙으로 학습되었어야 합니다.
  • dense_max_scale (float, kwargs, optional, 기본값 0.0) — max_patches에서 타일 캔버스 너비와 페이지 너비의 비율이 이 값보다 작으면 해당 페이지를 저해도로 간주합니다. 0이면 이 테스트를 건너뜁니다.
  • dense_min_aspect (float, kwargs, 선택 사항, 기본값 0.0) — dense_max_patches를 적용받기 위해 페이지가 초과해야 하는 너비/높이 비율입니다. 0이면 이 테스트를 건너뜁니다.
  • dense_max_aspect (float, kwargs, optional, 기본값 0.0) — dense_max_patches를 적용받기 위해 페이지가 초과할 수 없는 너비/높이 비율입니다. 이를 통해 단일 수식 줄과 같은 스트립이 max_patches에 유지됩니다. 0은 상한선이 없음을 의미합니다.

페이지를 종횡비와 가장 잘 일치하는 그리드에 따라 512x512 타일로 분할합니다(crop_to_patches, 최대 max_patches개의 타일, 한 변당 16개). 타일이 하나 이상인 경우 전체 페이지의 섬네일을 추가하고, 배치의 샘플을 동일한 타일 수로 패딩합니다. pixel_attention_mask는 실제 타일을 표시합니다. fine_route=True는 fine connector 경로를 위한 샘플을 표시하며(tile_fine_mask, 샘플당 하나의 값),

preprocess

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]*argsimage_like_kwargs: dict[str, typing.Any] | None = None**kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> ) → ~image_processing_base.BatchFeature

매개변수

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — 전처리할 이미지. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 사이인 이미지를 전달하는 경우 do_rescale=False로 설정하세요.
  • image_like_kwargs (dict[str, Any], 선택) — 추가 이미지 유사 입력을 전처리할 때 사용하는 개발자용 플래그입니다. 입력을 kwarg로 전달하는 것이 작동하지 않는 경우에만 사용하세요. 예를 들어, preprocess(images, masks=masks)가 권장되는 옵션이지만 일부 모델에서는 인자 우선순위 문제가 발생할 수 있습니다. 이러한 경우 대신 preprocess(images, image_like_inputs={"masks": masks})를 사용할 수 있습니다.
  • do_convert_rgb (bool, kwargs, 선택 사항) — 이미지를 RGB로 변환할지 여부입니다.
  • do_resize (bool, kwargs, 선택) — 이미지를 리사이즈할지 여부.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 모델의 최대 입력 차원을 설명합니다.
  • default_to_square (bool, kwargs, 선택 사항) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — center_crop을 적용한 후 출력 이미지의 크기.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 이미지를 리사이즈할 경우 사용할 리샘플링 필터입니다. 이는 PILImageResampling enum 중 하나일 수 있습니다. do_resize가 True로 설정된 경우에만 효과가 있습니다.
  • do_rescale (bool, kwargs, 선택 사항) — 이미지를 다시 스케일링할지 여부입니다.
  • rescale_factor (float, kwargs, optional) — do_rescale이 True로 설정된 경우 이미지를 리스케일하기 위한 리스케일 팩터입니다.
  • do_normalize (bool, kwargs, optional) — 이미지를 정규화할지 여부.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 평균입니다. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 표준 편차. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
  • do_pad (bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할 {"height": int, "width" int} 크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다. pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다. do_pad=True.일 때만 적용됩니다.
  • do_center_crop (bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:
    • "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
    • "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지.
    • "none" 또는 ChannelDimension.NONE: (height, width) 형식의 이미지.
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.
  • disable_grouping (bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다.
  • image_seq_length (int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.

반환값

~image_processing_base.BatchFeature

  • data (dict) — call 메서드가 반환하는 리스트/배열/텐서 딕셔너리(‘pixel_values’ 등).
  • tensor_type (Union[None, str, TensorType], 선택 사항) — 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type를 지정할 수 있습니다.

이미지 또는 이미지 배치(batch)를 전처리합니다.

GraniteDoclingImageProcessorPil

class transformers.GraniteDoclingImageProcessorPil

< >

( **kwargs: *<class 'transformers.models.granite_docling.image_processing_pil_granite_docling.GraniteDoclingImageProcessorKwargs'> )

매개변수

  • do_convert_rgb (bool, kwargs, 선택 사항, 기본값 True) — 이미지를 RGB로 변환할지 여부.
  • do_resize (bool, kwargs, 선택 사항, 기본값 True) — 이미지를 리사이즈할지 여부.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs, 기본값 {'height' -- 512, 'width': 512}): 모델에 전달되는 최대 입력 차원을 설명합니다.
  • default_to_square (bool, kwargs, 선택 사항, 기본값 True) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부입니다.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — center_crop을 적용한 후 출력 이미지의 크기.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs, 기본값 3) — 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. PILImageResampling enum 중 하나를 사용할 수 있습니다. do_resize가 True로 설정된 경우에만 효과가 있습니다.
  • do_rescale (bool, kwargs, 선택, 기본값 True) — 이미지를 다시 스케일링할지 여부.
  • rescale_factor (float, kwargs, 선택 사항, 기본값 0.00392156862745098) — do_rescale이 True로 설정된 경우 이미지를 재조정(rescale)하는 데 사용할 재조정 계수입니다.
  • do_normalize (bool, kwargs, 선택, 기본값 True) — 이미지를 정규화할지 여부.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, 선택, 기본값 [0.48145466, 0.4578275, 0.40821073]) — 정규화에 사용할 이미지 평균입니다. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, 선택, 기본값 [0.26862954, 0.26130258, 0.27577711]) — 정규화에 사용할 이미지 표준 편차입니다. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
  • do_pad (bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할 {"height": int, "width" int} 크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다. pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다. do_pad=True.일 때만 적용됩니다.
  • do_center_crop (bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:
    • "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
    • "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지.
    • "none" 또는 ChannelDimension.NONE: (height, width) 형식의 이미지.
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.
  • disable_grouping (bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다.
  • image_seq_length (int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.
  • crop_to_patches (bool, kwargs, 선택 사항, 기본값 True) — 페이지를 가로세로 비율에 가장 잘 맞는 그리드(한 변당 최대 16개 타일)에 배치된 512x512 타일로 분할할지 여부입니다. preprocess 메서드의 crop_to_patches 매개변수로 재정의할 수 있습니다.
  • min_patches (int, kwargs, 선택 사항, 기본값 1) — 페이지당 타일의 최소 개수입니다. crop_to_patches가 True로 설정된 경우에만 효과가 있습니다. preprocess 메서드의 min_patches 매개변수로 재정의할 수 있습니다.
  • max_patches (int, kwargs, 선택 사항, 기본값 32) — 페이지당 타일의 최대 수입니다. crop_to_patches가 True로 설정된 경우에만 효과가 있습니다. preprocess 메서드의 max_patches 매개변수로 재정의할 수 있습니다.
  • fine_route (bool, kwargs, 선택 사항, 기본값 False) — 페이지가 타일당 4배의 이미지 토큰을 생성하는 fine connector 경로를 사용하는지 여부.
  • dense_max_patches (int, kwargs, optional, 기본값 0) — 스프레드 규칙이 선택한 페이지에 대해 허용되는 최대 타일 수입니다(0이면 규칙 비활성화). max_patches 그리드가 dense_max_scale 미만으로 축소하고, 너비/높이 비율이 dense_min_aspect를 초과할 때(설정된 경우 dense_max_aspect 이하), max_patches 대신 최대 dense_max_patches개의 타일로 페이지가 타일링됩니다. 체크포인트는 동일한 규칙으로 학습되었어야 합니다.
  • dense_max_scale (float, kwargs, optional, 기본값 0.0) — max_patches에서 타일 캔버스 너비와 페이지 너비의 비율이 이 값보다 작으면 해당 페이지를 저해도로 간주합니다. 0이면 이 테스트를 건너뜁니다.
  • dense_min_aspect (float, kwargs, 선택 사항, 기본값 0.0) — dense_max_patches를 적용받기 위해 페이지가 초과해야 하는 너비/높이 비율입니다. 0이면 이 테스트를 건너뜁니다.
  • dense_max_aspect (float, kwargs, optional, 기본값 0.0) — dense_max_patches를 적용받기 위해 페이지가 초과할 수 없는 너비/높이 비율입니다. 이를 통해 단일 수식 줄과 같은 스트립이 max_patches에 유지됩니다. 0은 상한선이 없음을 의미합니다.

GraniteDoclingImageProcessor의 PIL 백엔드: 동일한 512x512 타일링, 썸네일 및 타일 패딩.

preprocess

< >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]*argsimage_like_kwargs: dict[str, typing.Any] | None = None**kwargs: *<class 'transformers.processing_utils.ImagesKwargs'> ) → ~image_processing_base.BatchFeature

매개변수

  • images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — 전처리할 이미지. 픽셀 값이 0에서 255 범위로 이루어진 단일 이미지 또는 배치 이미지를 기대합니다. 픽셀 값이 0에서 1 사이인 이미지를 전달하는 경우 do_rescale=False로 설정하세요.
  • image_like_kwargs (dict[str, Any], 선택) — 추가 이미지 유사 입력을 전처리할 때 사용하는 개발자용 플래그입니다. 입력을 kwarg로 전달하는 것이 작동하지 않는 경우에만 사용하세요. 예를 들어, preprocess(images, masks=masks)가 권장되는 옵션이지만 일부 모델에서는 인자 우선순위 문제가 발생할 수 있습니다. 이러한 경우 대신 preprocess(images, image_like_inputs={"masks": masks})를 사용할 수 있습니다.
  • do_convert_rgb (bool, kwargs, 선택 사항) — 이미지를 RGB로 변환할지 여부입니다.
  • do_resize (bool, kwargs, 선택) — 이미지를 리사이즈할지 여부.
  • size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 모델의 최대 입력 차원을 설명합니다.
  • default_to_square (bool, kwargs, 선택 사항) — size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부.
  • crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — center_crop을 적용한 후 출력 이미지의 크기.
  • resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 이미지를 리사이즈할 경우 사용할 리샘플링 필터입니다. 이는 PILImageResampling enum 중 하나일 수 있습니다. do_resize가 True로 설정된 경우에만 효과가 있습니다.
  • do_rescale (bool, kwargs, 선택 사항) — 이미지를 다시 스케일링할지 여부입니다.
  • rescale_factor (float, kwargs, optional) — do_rescale이 True로 설정된 경우 이미지를 리스케일하기 위한 리스케일 팩터입니다.
  • do_normalize (bool, kwargs, optional) — 이미지를 정규화할지 여부.
  • image_mean (Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 평균입니다. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
  • image_std (Union[float, list[float], tuple[float, ...]], kwargs, 선택) — 정규화에 사용할 이미지 표준 편차. do_normalize가 True로 설정된 경우에만 효과가 있습니다.
  • do_pad (bool, kwargs, optional) — 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.
  • pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 이미지를 패딩할 {"height": int, "width" int} 크기를 지정합니다. 전처리용으로 제공된 모든 이미지 크기보다 커야 합니다. pad_size가 제공되지 않으면, 배치 내 가장 큰 높이와 너비로 패딩됩니다. do_pad=True.일 때만 적용됩니다.
  • do_center_crop (bool, kwargs, 선택) — 이미지를 중앙으로 크롭할지 여부.
  • data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — ChannelDimension.FIRST만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.
  • input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 선택 사항) — 입력 이미지의 채널 차원 형식입니다. 설정되지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다:
    • "channels_first" 또는 ChannelDimension.FIRST: (num_channels, height, width) 형식의 이미지.
    • "channels_last" 또는 ChannelDimension.LAST: (height, width, num_channels) 형식의 이미지.
    • "none" 또는 ChannelDimension.NONE: (height, width) 형식의 이미지.
  • device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 동영상을 처리할 장치입니다. 설정되지 않은 경우, 입력 동영상에서 장치를 추론합니다.
  • return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 'pt'로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.
  • disable_grouping (bool, kwargs, 선택 사항) — 이미지를 크기에 따라 그룹화하는 것을 비활성화하여 배치 대신 개별적으로 처리할지 여부입니다. None인 경우, 이미지가 CPU에 있으면 True, 그렇지 않으면 False로 설정됩니다. 이 선택은 https://github.com/huggingface/transformers/pull/38157에 자세히 설명된 경험적 관찰에 기반합니다.
  • image_seq_length (int, kwargs, 선택 사항) — 입력에서 각 이미지에 사용할 이미지 토큰의 수입니다. 하위 호환성을 위해 추가되었지만, 향후 모델에서는 프로세서 속성으로 설정해야 합니다.

반환값

~image_processing_base.BatchFeature

  • data (dict) — call 메서드가 반환하는 리스트/배열/텐서 딕셔너리(‘pixel_values’ 등).
  • tensor_type (Union[None, str, TensorType], 선택 사항) — 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type를 지정할 수 있습니다.

이미지 또는 이미지 배치(batch)를 전처리합니다.

GraniteDoclingProcessor

class transformers.GraniteDoclingProcessor

< >

( image_processortokenizer = Noneimage_seq_len: int = 64chat_template: str | None = None**kwargs )

매개변수

  • image_processor (GraniteDoclingImageProcessor) — 이미지 프로세서가 필수 입력입니다.
  • tokenizer (tokenizer_class) — 토크나이저는 필수 입력값입니다.
  • image_seq_len (int, 선택 사항, 기본값 64) — coarse path에서 타일당 <image> 토큰의 수입니다. image_seq_len = int(((image_size // patch_size) ** 2) / (scale_factor**2))로 계산됩니다.
  • chat_template (str, 선택) — 채팅의 메시지 목록을 토큰화 가능한 문자열로 변환하는 Jinja 템플릿입니다.

이미지 프로세서와 토크나이저를 단일 프로세서로 래핑하는 GraniteDoclingProcessor를 생성합니다.

GraniteDoclingProcessor는 GraniteDoclingImageProcessor와 tokenizer_class의 모든 기능을 제공합니다. 자세한 내용은 ~GraniteDoclingImageProcessor와 ~tokenizer_class를 참고하세요.

__call__

< >

( images = Nonetext = None**kwargs ) → BatchEncoding

매개변수

  • images (`) -- Image to preprocess. Expects a single or batch of images with pixel values ranging from 0 to 255. If passing in images with pixel values between 0 and 1, set do_rescale=False`.
  • text (`) -- The sequence or batch of sequences to be encoded. Each sequence can be a string or a list of strings (pretokenized string). If you pass a pretokenized input, set is_split_into_words=True` to avoid ambiguity with batched inputs.
  • return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, 특정 프레임워크의 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
    • 'pt': PyTorch torch.Tensor 객체를 반환합니다.
    • 'np': NumPy np.ndarray 객체를 반환합니다.

반환값

BatchEncoding

pixel_values와 pixel_attention_mask가 포함된 토큰화된 프롬프트, 그리고 fine_route=True인 경우 tile_fine_mask가 반환됩니다. 타일 그리드는 프롬프트를 구성하는 데만 사용되며 반환되지 않습니다.

GraniteDoclingVisionModel

class transformers.GraniteDoclingVisionModel

< >

( config: GraniteDoclingVisionConfig )

매개변수

  • config (GraniteDoclingVisionConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

GraniteDocling의 비전 인코더와 그 위에 있는 커넥터: 페이지의 타일을 임베딩하고 모든 타일의 이미지 토큰과 투영된 DeepStack 특징을 함께 반환합니다.

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< >

( pixel_values: FloatTensorfine: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )

매개변수

  • pixel_values (torch.FloatTensor, shape (num_tiles, num_channels, image_size, image_size)) — 패딩 타일 없이 배치 전체에 걸쳐 평탄화(flatten)된 타일.
  • fine (bool, 선택 사항, 기본값 False) — 타일이 타일당 4배의 이미지 토큰을 생성하는 fine connector 경로를 사용하는지 여부.

GraniteDoclingVisionModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신 Module 인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.

GraniteDoclingModel

class transformers.GraniteDoclingModel

< >

( config: GraniteDoclingConfig )

매개변수

  • config (GraniteDoclingConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

비전 인코더, 커넥터, 텍스트 디코더로 구성된 GraniteDocling 모델로, 상단에 특정 헤드가 없이 원시 히든 상태를 출력합니다.

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonecache: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonepixel_values: typing.Optional[torch.FloatTensor] = Nonetile_fine_mask: typing.Optional[torch.BoolTensor] = Nonepixel_attention_mask: typing.Optional[torch.BoolTensor] = Nonemm_encoder_outputs: dict | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → GraniteDoclingBaseModelOutputWithPast or tuple(torch.Tensor)

매개변수

  • input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.

    AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

    입력 ID란 무엇인가요?

  • attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    어텐션 마스크란 무엇인가요?

  • position_ids (torch.LongTensor 의 shape (batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위 [0, config.n_positions - 1].

    포지션 ID란 무엇인가요?

  • cache (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key와 value)입니다. 이는 일반적으로 cache 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

    입력으로 Cache 인스턴스만 허용되며, kv cache guide를 참고하세요. cache가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.

    모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.

    cache가 사용되는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만, 즉 (batch_size, sequence_length) 모양의 모든 input_ids 대신 (batch_size, unprocessed_length) 모양의 처리되지 않은 input_ids를 입력해야 합니다.

  • inputs_embeds (torch.FloatTensor, shape (batch_size, sequence_length, hidden_size), 선택) — input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 input_ids 인덱스를 관련 벡터로 변환하는 방식에 대한 더 세밀한 제어가 필요한 경우 유용합니다.
  • pixel_values (torch.FloatTensor, shape (batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 image_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은 image_processor_class.__call__를 참조하세요 (processor_class는 이미지 처리에 image_processor_class를 사용합니다).
  • tile_fine_mask (torch.BoolTensor, shape (batch_size,), 선택 사항) — 프로세서가 fine_route=True로 호출되면 모든 값이 True입니다. 이 경우 배치에 fine connector 경로가 적용되어 타일당 이미지 토큰 수가 4배로 증가합니다.
  • pixel_attention_mask (torch.BoolTensor, shape (batch_size, num_tiles), 선택 사항) — 프로세서가 반환하는 실제 타일입니다. 패딩 타일은 false입니다. pixel_values와 함께 필수입니다.
  • mm_encoder_outputs (dict, 선택 사항) — 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 딕셔너리입니다. 각 인코딩된 출력은 (pooler_output, 선택 사항: last_hidden_states, 선택 사항: hidden_states, 선택 사항: attentions) pooler_output의 형태가 (batch_size, sequence_length, hidden_size), 선택 사항)인 튜플로, 인코더의 멀티모달 특징을 텍스트 임베딩에 병합한 시퀀스입니다.

반환값

GraniteDoclingBaseModelOutputWithPast 또는 tuple(torch.Tensor)

GraniteDoclingBaseModelOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되거나 config.return_dict=False인 경우)로, 구성(None)과 입력에 따라 다양한 요소를 포함합니다.

모델에 전달되는 입력에는 임의 개수의 이미지가 포함될 수 있습니다. 이를 반영하기 위해 모델에 전달되는 pixel_values에는 이미지 패딩이 적용되어 (batch_size, max_num_tiles, 3, image_size, image_size) 형태를 가지며, 여기서 max_num_tiles는 배치 내 batch_size개 샘플 중 최대 타일 수를 의미합니다. 패딩된 타일은 pixel_attention_mask에서 false로 표시되며, 비전 인코더로 전달되기 전에 제거됩니다.

  • last_hidden_state (torch.Tensor, shape (batch_size, sequence_length, hidden_size), 선택 사항) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  • cache (~cache_utils.Cache, 선택 사항, use_cache=True가 전달되거나 config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv 캐시 가이드를 참조하세요.

    순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록의 key와 value, 그리고 config.is_encoder_decoder=True인 경우 크로스-어텐션 블록의 key와 value)를 포함합니다(사용 방법은 cache 입력을 참조).

  • hidden_states (tuple[torch.Tensor], 선택 사항, output_hidden_states=True가 전달되거나 config.output_hidden_states=True인 경우 반환됨) — torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 (batch_size, sequence_length, hidden_size)입니다.

    각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

  • attentions (tuple[torch.Tensor], 선택 사항, output_attentions=True가 전달되었거나 config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된 torch.Tensor의 튜플로, 모양은 (batch_size, num_heads, sequence_length, sequence_length)입니다.

    self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.

  • image_hidden_states (tuple[torch.Tensor], shape (batch_size, num_images, sequence_length, hidden_size), 선택 사항) — 비전 인코더가 생성한 모델의 이미지 hidden states로, 마지막 hidden state를 투영한 후의 값입니다.

  • router_logits (torch.FloatTensor, shape (batch_size,), 선택 사항) — 밀도 라우터의 로짓으로, 샘플당 하나씩 반환됩니다. 모델에 라우터가 있고 pixel_values가 제공된 경우 반환됩니다.

get_image_features

< >

( pixel_values: FloatTensorpixel_attention_mask: BoolTensortile_fine_mask: typing.Optional[torch.BoolTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → GraniteDoclingImageFeaturesOutput or tuple(torch.Tensor)

매개변수

  • pixel_values (torch.FloatTensor, shape (batch_size, num_tiles, num_channels, image_size, image_size)) — 입력 이미지 타일에 해당하는 텐서입니다.
  • pixel_attention_mask (torch.BoolTensor, shape (batch_size, num_tiles)) — 프로세서가 반환하는 실제 타일입니다. 패딩 타일은 false입니다.
  • tile_fine_mask (torch.BoolTensor, shape (batch_size,), 선택 사항) — fine_route=True로 호출된 프로세서가 필요합니다: 배치에 fine connector 경로가 적용되며, 타일당 이미지 토큰이 4배 생성됩니다.

반환값

GraniteDoclingImageFeaturesOutput 또는 tuple(torch.Tensor)

GraniteDoclingImageFeaturesOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(GraniteDoclingConfig)과 입력에 따라 다양한 요소를 포함합니다.

  • last_hidden_state (torch.Tensor, shape (batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  • pooler_output (tuple[torch.FloatTensor], 길이 batch_size) — 타일 순서대로 배치된 각 샘플의 이미지 토큰을 텍스트 hidden size로 투영한 값입니다. 각 텐서의 shape은 (num_image_tokens, hidden_size)입니다. 타일 하나당 coarse connector 경로에서는 image_seq_len개의 토큰을, fine 경로에서는 그 4배에 해당하는 수의 토큰을 생성합니다. Generation 과정에서는 이러한 샘플별 텐서를 beam에 걸쳐 반복합니다.

  • hidden_states (tuple(torch.Tensor), 선택 사항, output_hidden_states=True가 전달되거나 config.output_hidden_states=True인 경우 반환됨) — torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 (batch_size, sequence_length, hidden_size)입니다.

    각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

  • attentions (tuple(torch.Tensor), 선택 사항, output_attentions=True가 전달되었거나 config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된 torch.Tensor의 튜플로, 모양은 (batch_size, num_heads, sequence_length, sequence_length)입니다.

    self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.

  • deepstack_features (list[tuple[torch.FloatTensor]], 선택 사항) — config.deepstack_visual_indexes의 각 항목에 대해 투영된 중간 비전 인코더 숨겨진 상태 하나. 각 항목은 샘플별로 분할되며, pooler_output와 동일한 레이아웃을 가집니다.

  • router_logits (torch.FloatTensor, shape (batch_size,), 선택 사항) — 밀도 라우터의 로짓으로, 샘플당 하나씩 반환됩니다. 모델에 라우터가 있는 경우 반환됩니다.

predict_fine_route

< >

( pixel_values: FloatTensorpixel_attention_mask: BoolTensor ) → torch.BoolTensor of shape (batch_size,)

매개변수

  • pixel_values (torch.FloatTensor, shape (batch_size, num_tiles, num_channels, image_size, image_size)) — 입력 이미지 타일에 해당하는 텐서입니다.
  • pixel_attention_mask (torch.BoolTensor, shape (batch_size, num_tiles)) — 프로세서가 반환하는 실제 타일입니다.

반환값

(batch_size,) 모양의 torch.BoolTensor

True는 fine connector 경로가 필요한 샘플에 대해 설정됩니다.

밀도 라우터(density router)를 사용하여 fine connector 경로가 필요한 샘플을 예측합니다. fine_route=True를 지정하여 프로세서를 다시 호출함으로써 라우팅을 수행합니다.

GraniteDoclingTextModel

class transformers.GraniteDoclingTextModel

< >

( config: GraniteDoclingTextConfig )

매개변수

  • config (GraniteDoclingTextConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 순수 Granite Docling Text Model

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonecache: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Noneuse_cache: bool | None = Nonevisual_pos_masks: typing.Optional[torch.BoolTensor] = Nonedeepstack_visual_embeds: list[torch.Tensor] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPast or tuple(torch.Tensor)

매개변수

  • input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.

    AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

    입력 ID란 무엇인가요?

  • attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    어텐션 마스크란 무엇인가요?

  • position_ids (torch.LongTensor 의 shape (batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위 [0, config.n_positions - 1].

    포지션 ID란 무엇인가요?

  • cache (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key와 value)입니다. 이는 일반적으로 cache 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

    입력으로 Cache 인스턴스만 허용되며, kv cache guide를 참고하세요. cache가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.

    모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.

    cache가 사용되는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만, 즉 (batch_size, sequence_length) 모양의 모든 input_ids 대신 (batch_size, unprocessed_length) 모양의 처리되지 않은 input_ids를 입력해야 합니다.

  • inputs_embeds (torch.FloatTensor, shape (batch_size, sequence_length, hidden_size), 선택) — input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 input_ids 인덱스를 관련 벡터로 변환하는 방식에 대한 더 세밀한 제어가 필요한 경우 유용합니다.
  • use_cache (bool, 선택 사항) — True로 설정하면 cache 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다( cache 참조).
  • visual_pos_masks (torch.BoolTensor, shape (batch_size, sequence_length), 선택 사항) — DeepStack 기능을 받는 이미지 토큰의 위치입니다.
  • deepstack_visual_embeds (list[torch.Tensor], 선택 사항) — 각각의 shape이 (num_image_tokens, hidden_size)인 DeepStack 특징입니다. i번째 항목은 decoder layer i 이후에 visual_pos_masks의 hidden states에 추가됩니다.

반환값

BaseModelOutputWithPast 또는 tuple(torch.Tensor)

None 및 입력에 따라 구성이 달라지는 여러 요소로 구성된 BaseModelOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되거나 config.return_dict=False인 경우).

GraniteDoclingTextModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신 Module 인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.

  • last_hidden_state (torch.Tensor, shape (batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

    cache가 사용되면 (batch_size, 1, hidden_size) 모양의 시퀀스의 마지막 hidden-state만 출력됩니다.

  • cache (Cache, 선택 사항, use_cache=True가 전달되거나 config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.

    순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록의 key와 value, 그리고 config.is_encoder_decoder=True인 경우 크로스-어텐션 블록의 key와 value)를 포함합니다(사용 방법은 cache 입력을 참조).

  • hidden_states (tuple(torch.Tensor), 선택 사항, output_hidden_states=True가 전달되거나 config.output_hidden_states=True인 경우 반환됨) — torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 (batch_size, sequence_length, hidden_size)입니다.

    각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

  • attentions (tuple(torch.Tensor), 선택 사항, output_attentions=True가 전달되었거나 config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된 torch.Tensor의 튜플로, 모양은 (batch_size, num_heads, sequence_length, sequence_length)입니다.

    self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.

GraniteDoclingForConditionalGeneration

class transformers.GraniteDoclingForConditionalGeneration

< >

( config: GraniteDoclingConfig )

매개변수

  • config (GraniteDoclingConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

언어 모델링 헤드가 있는 GraniteDocling 모델입니다. 비전 인코더, 커넥터, 텍스트 디코더로 구성되며, 그 위에 언어 모델링 헤드가 있습니다.

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonecache: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.FloatTensor] = Nonepixel_values: typing.Optional[torch.FloatTensor] = Nonetile_fine_mask: typing.Optional[torch.BoolTensor] = Nonepixel_attention_mask: typing.Optional[torch.BoolTensor] = Nonemm_encoder_outputs: dict | None = Nonelabels: typing.Optional[torch.LongTensor] = Nonerouter_labels: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → GraniteDoclingCausalLMOutputWithPast or tuple(torch.Tensor)

매개변수

  • input_ids (torch.LongTensor 형상이 (batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.

    AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.

    입력 ID란 무엇인가요?

  • attention_mask (torch.Tensor 형상이 (batch_size, sequence_length), 선택 사항) — 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크. [0, 1]에서 선택된 마스크 값: 마스크되지 않은 토큰은 1, 마스크된 토큰은 0. attention mask란 무엇인가요? [0, 1]:
    • 마스크되지 않은 토큰에 대해 1
    • 마스크된 토큰에 대해 0

    어텐션 마스크란 무엇인가요?

  • position_ids (torch.LongTensor 의 shape (batch_size, sequence_length), , 선택 사항) — 위치 임베딩에서 각 입력 시퀀스 토큰의 위치 인덱스. 범위 [0, config.n_positions - 1].

    포지션 ID란 무엇인가요?

  • cache (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key와 value)입니다. 이는 일반적으로 cache 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

    입력으로 Cache 인스턴스만 허용되며, kv cache guide를 참고하세요. cache가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.

    모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.

    cache가 사용되는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만, 즉 (batch_size, sequence_length) 모양의 모든 input_ids 대신 (batch_size, unprocessed_length) 모양의 처리되지 않은 input_ids를 입력해야 합니다.

  • inputs_embeds (torch.FloatTensor, shape (batch_size, sequence_length, hidden_size), 선택) — input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 input_ids 인덱스를 관련 벡터로 변환하는 방식에 대한 더 세밀한 제어가 필요한 경우 유용합니다.
  • pixel_values (torch.FloatTensor, shape (batch_size, num_channels, image_size, image_size), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 image_processor_class를 사용하여 얻을 수 있습니다. 자세한 내용은 image_processor_class.__call__를 참조하세요 (processor_class는 이미지 처리에 image_processor_class를 사용합니다).
  • tile_fine_mask (torch.BoolTensor, shape (batch_size,), 선택 사항) — 프로세서가 fine_route=True로 호출되면 모든 값이 True입니다. 이 경우 배치에 fine connector 경로가 적용되어 타일당 이미지 토큰 수가 4배로 증가합니다.
  • pixel_attention_mask (torch.BoolTensor, shape (batch_size, num_tiles), 선택 사항) — 프로세서가 반환하는 실제 타일입니다. 패딩 타일은 false입니다. pixel_values와 함께 필수입니다.
  • mm_encoder_outputs (dict, 선택 사항) — 키가 지원되는 모달리티이고 값이 해당 모달리티의 인코딩된 출력인 딕셔너리입니다. 각 인코딩된 출력은 (pooler_output, 선택 사항: last_hidden_states, 선택 사항: hidden_states, 선택 사항: attentions) pooler_output의 형태가 (batch_size, sequence_length, hidden_size), 선택 사항)인 튜플로, 인코더의 멀티모달 특징을 텍스트 임베딩에 병합한 시퀀스입니다.
  • labels (torch.LongTensor, shape (batch_size, sequence_length), 선택 사항) — 마스크 언어 모델링 손실을 계산하는 데 사용되는 라벨입니다. 인덱스는 [0, ..., config.vocab_size] 범위 내이거나 model.image_token_id여야 합니다(여기서 model은 GraniteDoclingForConditionalGeneration의 인스턴스입니다). 인덱스가 model.image_token_id로 설정된 토큰은 무시(마스크)되며, 손실은 [0, ..., config.vocab_size] 범위의 라벨을 가진 토큰에 대해서만 계산됩니다.
  • router_labels (torch.Tensor, shape (batch_size,), 선택 사항) — 밀도 라우터의 타깃으로, fine connector 경로가 필요한 샘플은 1 (또는 True), 그 외에는 0입니다. float, bool 또는 int로 주어지며, 라우터 손실은 logits에 대한 binary cross-entropy입니다.
  • use_cache (bool, 선택 사항) — True로 설정하면 cache 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다( cache 참조).
  • logits_to_keep (Union[int, torch.Tensor], 선택 사항, 기본값 0) — int인 경우, 마지막 logits_to_keep 토큰에 대한 logits를 계산합니다. 0인 경우, 모든 input_ids에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다. torch.Tensor인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 패킹된 텐서 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

반환값

GraniteDoclingCausalLMOutputWithPast 또는 tuple(torch.Tensor)

GraniteDoclingCausalLMOutputWithPast 또는 torch.Tensor의 튜플(return_dict=False가 전달되거나 config.return_dict=False인 경우)로, 구성(None)과 입력에 따라 다양한 요소를 포함합니다.

GraniteDoclingForConditionalGeneration의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신 Module 인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.

  • loss (torch.FloatTensor, shape (1,), 선택, labels이 제공될 때 반환됨) — 언어 모델링 손실(다음 토큰 예측용).

  • logits (torch.FloatTensor, shape (batch_size, sequence_length, config.vocab_size)) — 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).

  • cache (~cache_utils.Cache, 선택 사항, use_cache=True가 전달되거나 config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv 캐시 가이드를 참조하세요.

    순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프-어텐션 블록의 key와 value, 그리고 config.is_encoder_decoder=True인 경우 크로스-어텐션 블록의 key와 value)를 포함합니다(사용 방법은 cache 입력을 참조).

  • hidden_states (tuple[torch.Tensor], 선택 사항, output_hidden_states=True가 전달되거나 config.output_hidden_states=True인 경우 반환됨) — torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 (batch_size, sequence_length, hidden_size)입니다.

    각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

  • attentions (tuple[torch.Tensor], 선택 사항, output_attentions=True가 전달되었거나 config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된 torch.Tensor의 튜플로, 모양은 (batch_size, num_heads, sequence_length, sequence_length)입니다.

    self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.

  • image_hidden_states (tuple[torch.Tensor], shape (batch_size, num_images, sequence_length, hidden_size), 선택 사항) — 비전 인코더가 생성한 모델의 이미지 hidden states로, 마지막 hidden state를 투영한 후의 값입니다.

  • router_logits (torch.FloatTensor, shape (batch_size,), 선택 사항) — 밀도 라우터의 로짓으로, 샘플당 하나씩 반환됩니다. 모델에 라우터가 있고 pixel_values가 제공된 경우 반환됩니다.

예:

>>> from transformers import AutoProcessor, AutoModelForImageTextToText
>>> from transformers.image_utils import load_image

>>> image = load_image("https://huggingface.co/ibm-granite/granite-for-docling-500m/resolve/main/docling_technical_report_p1.png")

>>> processor = AutoProcessor.from_pretrained("ibm-granite/granite-for-docling-500m")
>>> model = AutoModelForImageTextToText.from_pretrained("ibm-granite/granite-for-docling-500m", device_map="auto")

>>> messages = [
...     {
...         "role": "user",
...         "content": [
...             {"type": "image"},
...             {"type": "text", "text": "<doclang>"},
...         ],
...     }
... ]
>>> prompt = processor.apply_chat_template(messages, add_generation_prompt=True)
>>> inputs = processor(text=prompt, images=image, return_tensors="pt").to(model.device)

>>> generated_ids = model.generate(**inputs, max_new_tokens=4096)
>>> print(processor.decode(generated_ids[0, inputs["input_ids"].shape[1] :], skip_special_tokens=False))

get_image_features

< >

( pixel_values: Tensorpixel_attention_mask: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)

매개변수

  • pixel_values (torch.Tensor, shape (batch_size, num_channels, image_size, image_size)) — 입력 이미지에 해당하는 텐서입니다.
  • pixel_attention_mask (torch.LongTensor, 선택 사항) — 이미지의 패딩된 영역을 나타내는 어텐션 마스크입니다.

반환값

BaseModelOutputWithPooling 또는 tuple(torch.Tensor)

torch.Tensor의 튜플 또는 BaseModelOutputWithPooling (return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(GraniteDoclingConfig)과 입력에 따라 다양한 요소를 포함합니다.

  • last_hidden_state (torch.Tensor, shape (batch_size, sequence_length, hidden_size)) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  • pooler_output (torch.Tensor, shape (batch_size, hidden_size)) — 보조 사전 학습 작업을 위해 사용되는 레이어들을 통해 추가 처리된 시퀀스의 첫 번째 토큰(분류 토큰)의 마지막 레이어 hidden-state입니다. 예를 들어 BERT 계열 모델의 경우, 선형 레이어와 tanh 활성화 함수를 통해 처리된 후의 분류 토큰을 반환합니다. 선형 레이어의 가중치는 사전 학습 동안 다음 문장 예측(분류) 목적 함수를 통해 학습됩니다.

  • hidden_states (tuple(torch.Tensor), 선택 사항, output_hidden_states=True가 전달되거나 config.output_hidden_states=True인 경우 반환됨) — torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은 (batch_size, sequence_length, hidden_size)입니다.

    각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.

  • attentions (tuple(torch.Tensor), 선택 사항, output_attentions=True가 전달되었거나 config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된 torch.Tensor의 튜플로, 모양은 (batch_size, num_heads, sequence_length, sequence_length)입니다.

    self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치.

예:

>>> from PIL import Image
>>> from transformers import AutoProcessor, GraniteDoclingForConditionalGeneration

>>> model = GraniteDoclingForConditionalGeneration.from_pretrained("ibm-granite/granite-for-docling-500m")
>>> processor = AutoProcessor.from_pretrained("ibm-granite/granite-for-docling-500m")

>>> messages = [
...     {
...         "role": "user", "content": [
...             {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"},
...             {"type": "text", "text": "Where is the cat standing?"},
...         ]
...     },
... ]

>>> inputs = processor.apply_chat_template(
...     messages,
...     tokenize=True,
...     return_dict=True,
...     return_tensors="pt",
...     add_generation_prompt=True
... )
>>> # Generate
>>> generate_ids = model.generate(**inputs)
>>> processor.batch_decode(generate_ids, skip_special_tokens=True)[0]
Update on GitHub

←Granite4Vision GraniteVision→