Hugging Face's logo

Transformers documentation

GraniteDocling

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] = Nonepast_key_values: 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란 무엇인가요?

  • past_key_values (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는 past_key_values 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

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

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

    past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만 입력해야 하며, 이때의 shape은 (batch_size, unprocessed_length)입니다. shape이 (batch_size, sequence_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), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 GraniteDoclingImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 GraniteDoclingImageProcessor.call()를 참조하세요 (GraniteDoclingProcessor는 이미지 처리에 GraniteDoclingImageProcessor를 사용합니다).
  • 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인 경우)로, 구성(GraniteDoclingConfig)과 입력에 따라 다양한 요소를 포함합니다.

모델에 전달되는 입력에는 임의 개수의 이미지가 포함될 수 있습니다. 이를 반영하기 위해 모델에 전달되는 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 시퀀스입니다.

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

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

  • 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] = Nonepast_key_values: 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란 무엇인가요?

  • past_key_values (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는 past_key_values 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

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

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

    past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만 입력해야 하며, 이때의 shape은 (batch_size, unprocessed_length)입니다. shape이 (batch_size, sequence_length)인 전체 input_ids를 입력하지 않습니다.

  • inputs_embeds (torch.FloatTensor, shape (batch_size, sequence_length, hidden_size), 선택) — input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 input_ids 인덱스를 관련 벡터로 변환하는 방식에 대한 더 세밀한 제어가 필요한 경우 유용합니다.
  • use_cache (bool, 선택 사항) — True로 설정하면 past_key_values 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다( past_key_values 참조).
  • 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)

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

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

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

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

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

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

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

  • 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] = Nonepast_key_values: 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란 무엇인가요?

  • past_key_values (~cache_utils.Cache, 선택 사항) — 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(self-attention 블록과 cross-attention 블록의 key 및 value). 일반적으로 이는 past_key_values 디코딩의 이전 단계에서 모델이 반환한 use_cache=True 또는 config.use_cache=True.

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

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

    past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은 input_ids만 입력해야 하며, 이때의 shape은 (batch_size, unprocessed_length)입니다. shape이 (batch_size, sequence_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), 선택 사항) — 입력 이미지에 해당하는 텐서입니다. 픽셀 값은 GraniteDoclingImageProcessor를 사용하여 얻을 수 있습니다. 자세한 내용은 GraniteDoclingImageProcessor.call()를 참조하세요 (GraniteDoclingProcessor는 이미지 처리에 GraniteDoclingImageProcessor를 사용합니다).
  • 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로 설정하면 past_key_values 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다( past_key_values 참조).
  • 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인 경우)로, 구성(GraniteDoclingConfig)과 입력에 따라 다양한 요소를 포함합니다.

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

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

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

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

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

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

  • 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→