数据模型

nlql.model —— 模态无关的数据模型：Payload / Document / Unit / Vector。从第一天起对文本 / 图像 / 二进制通用，Payload{modality} 携带模态标签。

model

Modality-agnostic data model: Payload, Document, Unit, Vector.

UnitKind module-attribute

UnitKind = Literal['document', 'chunk', 'sentence', 'span']

Vector module-attribute

Vector = np.ndarray

__all__ module-attribute

__all__ = ['Modality', 'Payload', 'Document', 'Unit', 'UnitKind', 'Span', 'Vector', 'as_array', 'normalize', 'to_list']

Document dataclass

Document(id: str, payloads: list[Payload], metadata: dict[str, Any] = dict(), source: str | None = None)

A source document to be ingested.

参数：

名称	类型	描述	默认
id	str	Stable, caller-provided identifier. Must be unique within a store.	必需
payloads	list[Payload]	One or more content payloads (usually a single text payload).	必需
metadata	dict[str, Any]	Opaque business metadata, addressed in queries via meta.*.	dict()
source	str | None	Optional provenance hint (file path, URL, …).	None

id instance-attribute

id: str

payloads instance-attribute

payloads: list[Payload]

metadata class-attribute instance-attribute

metadata: dict[str, Any] = field(default_factory=dict)

source class-attribute instance-attribute

source: str | None = None

__post_init__

__post_init__() -> None

源代码位于： src/nlql/model/document.py

def __post_init__(self) -> None:
    if not self.payloads:
        raise ValueError("Document must have at least one payload")

from_text classmethod

from_text(text: str, *, id: str, metadata: dict[str, Any] | None = None, source: str | None = None) -> Document

Build a single-payload text document.

源代码位于： src/nlql/model/document.py

@classmethod
def from_text(
    cls,
    text: str,
    *,
    id: str,
    metadata: dict[str, Any] | None = None,
    source: str | None = None,
) -> Document:
    """Build a single-payload text document."""
    return cls(id=id, payloads=[Payload.text(text)], metadata=metadata or {}, source=source)

Modality

Bases: StrEnum

The kind of content a payload carries.

A StrEnum so it compares and serializes as a plain string.

TEXT class-attribute instance-attribute

TEXT = 'text'

IMAGE class-attribute instance-attribute

IMAGE = 'image'

BLOB class-attribute instance-attribute

BLOB = 'blob'

Payload dataclass

Payload(modality: Modality, data: str | bytes, mime: str | None = None)

A single piece of content plus its modality.

参数：

名称	类型	描述	默认
modality	Modality	What kind of data data holds.	必需
data	str | bytes	str for text; bytes or a URI str for image / blob.	必需
mime	str | None	Optional MIME type (e.g. "image/png"), useful for adapters.	None

modality instance-attribute

modality: Modality

data instance-attribute

data: str | bytes

mime class-attribute instance-attribute

mime: str | None = None

is_text property

is_text: bool

as_text property

as_text: str

Return textual data, or "" for non-text payloads.

__post_init__

__post_init__() -> None

源代码位于： src/nlql/model/payload.py

def __post_init__(self) -> None:
    if self.modality is Modality.TEXT and not isinstance(self.data, str):
        raise TypeError("TEXT payload data must be a str")

text classmethod

text(s: str) -> Payload

Convenience constructor for a text payload.

源代码位于： src/nlql/model/payload.py

@classmethod
def text(cls, s: str) -> Payload:
    """Convenience constructor for a text payload."""
    return cls(modality=Modality.TEXT, data=s)

Span dataclass

Span(center: int, start: int, end: int, char_start: int | None = None, char_end: int | None = None)

Context-window info for kind="span" units.

Indices are positions within the parent document's ordered unit sequence (of the base granularity that was expanded), inclusive on both ends.

center instance-attribute

center: int

start instance-attribute

start: int

end instance-attribute

end: int

char_start class-attribute instance-attribute

char_start: int | None = None

char_end class-attribute instance-attribute

char_end: int | None = None

Unit dataclass

Unit(id: str, doc_id: str, kind: UnitKind, payload: Payload, metadata: dict[str, Any] = dict(), vector: Vector | None = None, span: Span | None = None, scores: dict[str, float] = dict(), ordinal: int = 0, vectors: dict[str, Vector] = dict())

The atomic unit of retrieval and of results.

参数：

名称	类型	描述	默认
id	str	Stable unit id (unique within a store).	必需
doc_id	str	Owning document id.	必需
kind	UnitKind	Granularity of this unit.	必需
payload	Payload	The unit's content.	必需
metadata	dict[str, Any]	Inherited business metadata from the document (read-only view).	dict()
vector	Vector | None	Embedding, computed at ingestion; None before embedding.	None
span	Span | None	Present when kind == "span".	None
scores	dict[str, float]	Named scalar scores attached during query (e.g. {"relevance": .87}).	dict()
ordinal	int	Position of this unit within its document's sequence, used for stable ordering and SPAN window expansion.	0

id instance-attribute

id: str

doc_id instance-attribute

doc_id: str

kind instance-attribute

kind: UnitKind

payload instance-attribute

payload: Payload

metadata class-attribute instance-attribute

metadata: dict[str, Any] = field(default_factory=dict)

vector class-attribute instance-attribute

vector: Vector | None = None

span class-attribute instance-attribute

span: Span | None = None

scores class-attribute instance-attribute

scores: dict[str, float] = field(default_factory=dict)

ordinal class-attribute instance-attribute

ordinal: int = 0

vectors class-attribute instance-attribute

vectors: dict[str, Vector] = field(default_factory=dict)

content property

content: str

Text content when the payload is textual; "" otherwise.

get_vector

get_vector(name: str = 'default') -> Vector | None

Return a named vector; "default" / "content" map to the primary vector.

A unit may carry several modality vectors (e.g. a text and an image vector), queried separately via SIMILARITY(vec.<name>, "…").

源代码位于： src/nlql/model/unit.py

def get_vector(self, name: str = "default") -> Vector | None:
    """Return a named vector; ``"default"`` / ``"content"`` map to the primary ``vector``.

    A unit may carry several modality vectors (e.g. a ``text`` and an ``image`` vector),
    queried separately via ``SIMILARITY(vec.<name>, "…")``.
    """
    if name in ("default", "content"):
        return self.vector
    return self.vectors.get(name)

as_array

as_array(v: Sequence[float] | ndarray, dtype: type = float32) -> ndarray

Coerce a sequence / array into a contiguous 1-D array of dtype.

源代码位于： src/nlql/model/vector.py

def as_array(v: Sequence[float] | np.ndarray, dtype: type = np.float32) -> np.ndarray:
    """Coerce a sequence / array into a contiguous 1-D array of ``dtype``."""
    arr: np.ndarray = np.asarray(v, dtype=dtype)
    if arr.ndim != 1:
        arr = arr.reshape(-1)
    return np.ascontiguousarray(arr)

normalize

normalize(v: Sequence[float] | ndarray) -> ndarray

Return the unit-normalized vector; a zero vector is returned unchanged.

源代码位于： src/nlql/model/vector.py

def normalize(v: Sequence[float] | np.ndarray) -> np.ndarray:
    """Return the unit-normalized vector; a zero vector is returned unchanged."""
    arr = as_array(v)
    norm = float(np.linalg.norm(arr))
    if norm == 0.0:
        return arr
    return arr / norm

to_list

to_list(v: Sequence[float] | ndarray) -> list[float]

Convert a vector to a plain list[float] (e.g. for JSON / transport).

源代码位于： src/nlql/model/vector.py

def to_list(v: Sequence[float] | np.ndarray) -> list[float]:
    """Convert a vector to a plain ``list[float]`` (e.g. for JSON / transport)."""
    return [float(x) for x in as_array(v)]