LLM, Embedders 및 Rerankers

이 페이지에서는 LLM, 임베더 및 순위 재지정기를 Oracle 에이전트 메모리에 연결하는 데 사용되는 추상적 인터페이스를 제공합니다.

LLM 인터페이스

클래스 oracleagentmemory.apis.llms.ILlm

기준: ABC

LLM 호출에 대한 추상 인터페이스입니다.

method generate(개요)

LLM에서 동기적으로 응답을 생성합니다.

method generate_async(개요, 비동기)

LLM에서 비동기적으로 응답을 생성합니다.

LLM 응답

클래스 oracleagentmemory.apis.llms.LlmResponse

기준: object

ILlm에서 반환된 작은 정규화된 응답입니다.

텍스트

기본 생성 텍스트 콘텐츠입니다.

임베더 인터페이스

클래스 oracleagentmemory.apis.IEmbedder

기준: ABC

텍스트 내장자에 대한 추상 인터페이스입니다.

method embed(개요)

텍스트 배치를 2D float32 NumPy 배열에 포함시킵니다.

method embed_async(개요, 비동기)

텍스트 배치를 2D float32 NumPy 배열에 포함시킵니다.

등록 정보 embedding_dimension

포함 너비가 구성 또는 제공자 메타데이터에서 알려진 경우 하위 클래스가 이 속성을 무효화할 수 있습니다. 기본 구현은 embed()를 한 번 프로브하고 결과 크기를 캐시합니다.

등록 정보 max_input_tokens

모델의 입력 예산이 구성 또는 제공자 메타데이터에서 알려진 경우 하위 클래스가 이 속성을 무효화할 수 있습니다. 기본 구현은 예상되는 512 입력 토큰으로 크기가 지정된 프로브를 한 번 검증하고 512를 보수적 폴백으로 캐시합니다. 로컬에서 모델 토큰화기를 실행하지 않으므로 호출자는 모델의 실제 입력 예산을 알고 있을 때 수동으로 max_input_tokens를 설정해야 합니다.

순위 재지정 인터페이스

클래스 oracleagentmemory.apis.IReranker

기준: ABC

동기 및 비동기 문서 순위 변경을 위한 추상 인터페이스입니다.

구현은 모든 입력 문서에 대해 하나의 결과를 반환해야 합니다. 각 0 기반 입력 인덱스는 정확히 한 번 표시되어야 합니다. relevance_score는 유한해야 하며 점수가 높을수록 관련성이 높아야 합니다. 결과는 최고 점수부터 최저 점수까지 정렬되어야 합니다.

방법 rerank

rerank_async에 위임하여 문서를 동기적으로 순위 지정합니다.

method rerank_async(개요, 비동기)

쿼리와 관련된 문서 순위를 비동기적으로 지정합니다.

클래스 oracleagentmemory.apis.RerankResponse

기준: object

관련성 점수를 내림차순으로 문서 순위를 지정합니다.

클래스 oracleagentmemory.apis.RerankResponseResult

기준: object

한 문서의 순위 재지정 결과입니다.

LiteLLM 어댑터

클래스 oracleagentmemory.core.llms.LlmApiType

기준: str, Enum

Llm에 대해 지원되는 OpenAI 호환 API 제품군입니다.

CHAT_COMPLETIONS = 'CHAT_COMPLETIONS'

응답 = 'RESPONSES'

클래스 oracleagentmemory.core.llms.Llm

기준: ILlm

모델 응답을 생성하기 위한 어댑터입니다.

LLM 어댑터를 만듭니다.

예제

OCI Generative AI 모델은 LiteLLM의 "oci/..." 모델 식별자를 사용합니다. 일반적인 설정은 LiteLLM 특정 키워드 인수를 통해 표준 OCI 구성 파일에서 OCI API 키 인증 세부 정보를 전달하는 것입니다. OCI Python SDK는 이 패키지에 의해 설치되지 않습니다. 이미 종속된 애플리케이션이 oci_signer 객체를 전달할 수도 있습니다.

import configparser
from pathlib import Path
parser = configparser.RawConfigParser()
parser.read(Path("~/.oci/config").expanduser())
cfg = parser["DEFAULT"]
key_file = Path(cfg["key_file"]).expanduser()
oci_llm = Llm(
    model="oci/openai.gpt-oss-120b",
    oci_compartment_id="ocid1.compartment.oc1..example",
    oci_region=cfg.get("region", "us-chicago-1"),
    oci_user=cfg["user"],
    oci_fingerprint=cfg["fingerprint"],
    oci_tenancy=cfg["tenancy"],
    oci_key_file=str(key_file),
)
oci_llm.generate("Reply with OK.")

OpenAI 호스트 모델은 "openai/gpt-5.1" 및 OpenAI API 키와 같은 LiteLLM 모델 식별자를 사용합니다. 채팅 완료가 기본 API 패밀리입니다.

openai_llm = Llm(
    model="openai/gpt-5.1",
    api_key="sk-example",
    temperature=0,
    max_tokens=128,
)
openai_llm.model
'openai/gpt-5.1'
openai_llm.generate("Reply with OK.")

채팅 완료 대신 OpenAI 응답 API를 통해 대상 모델을 호출해야 하는 경우 api_type=LlmApiType.RESPONSES를 사용합니다.

responses_llm = Llm(
    model="openai/gpt-5.4",
    api_key="sk-example",
    api_type=LlmApiType.RESPONSES,
    reasoning_effort="high",
    stream=True,
)
responses_llm.model
'openai/gpt-5.4'

vLLM을 포함하여 자체 호스트된 OpenAI 호환 서버는 "openai/..." 모델 식별자와 서버의 /v1 기본 URL로 호출됩니다. 엔드포인트에서 인증을 강제 적용하지 않는 경우 명목상 api_key(예: "none")를 전달합니다.

vllm_llm = Llm(
    model="openai/openai/gpt-oss-120b",
    api_base="http://localhost:8000/v1",
    api_key="none",
    stream=True,
)
vllm_llm.model
'openai/openai/gpt-oss-120b'
vllm_llm.generate("Reply with OK.")

방법 generate

응답을 생성합니다.

method generate_async(비동기)

비동기적으로 응답을 생성합니다.

등록 정보 supports_vision

클래스 oracleagentmemory.core.embedders.Embedder

기준: IEmbedder

공급자 지원 임베더입니다.

공급자 지원 임베더를 생성합니다.

예제

OCI Generative AI 임베딩 모델은 "oci/..." 모델 식별자를 사용합니다. 일반적인 설정은 LiteLLM 특정 키워드 인수를 통해 표준 OCI 구성 파일에서 OCI API 키 인증 세부 정보를 전달하는 것입니다. OCI Python SDK는 이 패키지에 의해 설치되지 않습니다. 이미 종속된 애플리케이션이 oci_signer 객체를 전달할 수도 있습니다.

import configparser
from pathlib import Path
parser = configparser.RawConfigParser()
parser.read(Path("~/.oci/config").expanduser())
cfg = parser["DEFAULT"]
key_file = Path(cfg["key_file"]).expanduser()
oci_embedder = Embedder(
    model="oci/cohere.embed-english-v3.0",
    oci_compartment_id="ocid1.compartment.oc1..example",
    oci_region=cfg.get("region", "us-chicago-1"),
    oci_user=cfg["user"],
    oci_fingerprint=cfg["fingerprint"],
    oci_tenancy=cfg["tenancy"],
    oci_key_file=str(key_file),
)
oci_embedder.embed(["hello world"])

OpenAI 호스팅 임베딩 모델은 OpenAI API 키와 함께 "openai/text-embedding-3-small"와 같은 식별자를 사용합니다.

openai_embedder = Embedder(
    model="openai/text-embedding-3-small",
    api_key="sk-example",
    truncate_prompt_tokens=8192,
)
openai_embedder.model
'openai/text-embedding-3-small'
openai_embedder.embed(["hello world"])

vLLM을 포함하여 자체 호스트된 OpenAI 호환 임베딩 서버는 "hosted_vllm/..." 제공자 접두어를 서버의 /v1 기본 URL과 함께 사용합니다.

vllm_embedder = Embedder(
    model="hosted_vllm/sentence-transformers/all-MiniLM-L6-v2",
    api_base="http://localhost:8000/v1",
)
vllm_embedder.model
'hosted_vllm/sentence-transformers/all-MiniLM-L6-v2'
vllm_embedder.embed(["hello world"])

방법 embed

구성된 제공자를 사용하여 텍스트 일괄 처리를 포함합니다.

method embed_async(비동기)

구성된 제공자를 사용하여 텍스트 일괄 처리를 비동기적으로 포함합니다.

등록 정보 embedding_dimension

노트

생성자가 제공한 값은 제공자에게 연락하지 않고 반환됩니다. 그렇지 않으면 등록 정보가 한 번 프로브되고 결과가 캐시됩니다.

등록 정보 max_input_tokens

노트

생성자가 제공한 값은 제공자에게 연락하지 않고 반환됩니다. 그렇지 않으면 이 등록 정보는 예상되는 512 입력 토큰에 대한 공급자 프로브 크기를 검증하고 512를 보수적 폴백으로 캐시합니다. 로컬에서 모델 토큰화기를 실행하지 않으므로 정밀도가 중요한 경우 모델의 문서화된 입력 예산에서 max_input_tokens를 수동으로 설정합니다.

클래스 oracleagentmemory.core.Reranker

기준: IReranker

공급자 중립 순위 재지정 인터페이스가 지원하는 순위 재지정자입니다.

예제

reranker = Reranker(
    model="your-reranker-model",
    api_base="https://your-reranker-endpoint/v1",
    api_key="your-api-key",
)
reranker.rerank("favorite food", ["The user likes pasta."])
oci_reranker = Reranker(
    model="oci/cohere.rerank-v4.0-fast",
    oci_compartment_id="ocid1.compartment...",
    oci_region="your-region",
    oci_user="ocid1.user...",
    oci_fingerprint="aa:bb:cc",
    oci_tenancy="ocid1.tenancy...",
    oci_key_file="~/.oci/oci_api_key.pem",
)
oci_reranker.rerank("favorite food", ["The user likes pasta."])

제공자 지원 순위 변경자를 생성합니다.

method rerank_async(비동기)

쿼리와 관련된 문서 순위를 비동기적으로 지정합니다.

Oracle DB 임베더

클래스 oracleagentmemory.core.embedders.OracleDBEmbedder

기준: IEmbedder

Oracle AI Database 임베딩 SQL을 호출하여 텍스트를 포함합니다.

이 임베더는 SQL을 통해 임베딩 생성을 데이터베이스에 위임하면서 패키지의 기존 임베더 계약을 그대로 유지합니다. 직접 임베딩은 데이터베이스 상주 모델 구성에 대해 VECTOR_EMBEDDING를 선호하며 벡터라이저 구성에 JSON 제공자 매개변수 표면이 필요한 경우 DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING로 폴백됩니다.

Oracle AI Database SQL 실행이 지원하는 임베더를 생성합니다.

예제

Oracle 연결 풀 및 DB 상주 포함 모델을 사용합니다.

import oracledb
pool = oracledb.create_pool(
    user="scott",
    password="tiger",
    dsn="dbhost.example.com/orclpdb",
)
embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
embedder.embed(["hello world"])

스키마 한정 모델 이름은 연결된 스키마에 다른 스키마가 소유한 모델에 대한 권한이 있는 경우 사용할 수 있습니다.

shared_embedder = OracleDBEmbedder(
    connection=pool,
    model="MY_OTHER_SCHEMA.MY_ONNX_MODEL",
    embedding_dimension=768,
)
shared_embedder.embed(["hello world"])

다음 예에서는 OpenAI, vLLM, Cohere 및 기타 제공업체를 통해 Oracle AI Database 임베딩을 구성하는 방법을 보여줍니다.

OpenAI 예:

openai_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="text-embedding-3-small",
    provider_options={
        "credential_name": "OPENAI_CRED",
        "url": "https://api.openai.example.com/embeddings",
    },
)
openai_embedder.embed(["hello world"])

Cohere 예제:

cohere_embedder = OracleDBEmbedder(
    connection=pool,
    provider="cohere",
    model="embed-english-v3.0",
    provider_options={
        "credential_name": "COHERE_CRED",
        "url": "https://api.cohere.example.com/embed",
        "input_type": "search_document",
    },
)
cohere_embedder.embed(["hello world"])

vLLM과 같은 OpenAI 호환 서비스도 "openai" 제공자를 사용합니다. 끝점에 Oracle AI Database 인증서가 필요하지 않은 경우 host를 "local"로 설정합니다.

vllm_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="BAAI/bge-small-en-v1.5",
    provider_options={
        "url": "http://localhost:8080/v1/embeddings",
        "host": "local",
    },
)
vllm_embedder.embed(["hello world"])

Gemini 예제:

gemini_embedder = OracleDBEmbedder(
    connection=pool,
    provider="googleai",
    model="gemini-embedding-001",
    provider_options={
        "credential_name": "GOOGLEAI_CRED",
        "url": "https://googleapis.example.com/models/",
    },
)
gemini_embedder.embed(["hello world"])

포옹 얼굴 예:

huggingface_embedder = OracleDBEmbedder(
    connection=pool,
    provider="huggingface",
    model=(
        "sentence-transformers/all-MiniLM-L6-v2"
    ),
    provider_options={
        "credential_name": "HF_CRED",
        "url": "https://router.huggingface.example.com/",
    },
)
huggingface_embedder.embed(["hello world"])

저장소 API를 변경하지 않고 질의별 접두어를 구성할 수 있습니다.

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    query_prefix="search_document: ",
)
embedder.embed(["pizza"], is_query=True)

방법 embed

Oracle AI Database에서 SQL을 실행하여 텍스트 일괄 처리를 내장합니다.

예제

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
)
matrix = embedder.embed(["alpha", "beta"])
matrix.shape[0]
2

method embed_async(비동기)

Oracle AI Database SQL을 사용하여 텍스트 일괄 처리를 비동기식으로 내장합니다.

예제

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
)
matrix = await embedder.embed_async(["hello"])
matrix.shape
(1, 384)

등록 정보 embedding_dimension

노트

생성자가 제공한 값은 데이터베이스 모델에 연결하지 않고 반환됩니다. 그렇지 않으면 등록 정보가 한 번 프로브되고 이후 액세스에 대한 결과가 캐시됩니다.

예제

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
embedder.embedding_dimension
768

방법 get_vectorizer_config_json

이 DB 모델에 대한 Oracle 벡터화기 환경설정 JSON을 반환합니다.

동일한 모델 구성이 직접 임베딩 및 관리되는 하이브리드 인덱스에 의해 사용됩니다. 직접 임베딩은 이를 사용하여 VECTOR_EMBEDDING가 구성된 데이터베이스 모델을 나타낼 수 있는지 아니면 제공자 JSON에 DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING이 필요한지 여부를 결정합니다. 하이브리드 인덱싱은 이를 DBMS_VECTOR_CHAIN.CREATE_PREFERENCE에 전달한 다음 Oracle의 벡터화기 파이프라인은 해당 인덱스에 대한 임베딩 작업을 소유합니다.

예제

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
embedder.get_vectorizer_config_json()
'{"model":"DOC_MODEL"}'
custom_embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    input_name="TEXT",
    embedding_dimension=768,
)
custom_embedder.get_vectorizer_config_json()
'{"model":"DOC_MODEL","input_name":"TEXT"}'
shared_embedder = OracleDBEmbedder(
    connection=pool,
    model="MY_OTHER_SCHEMA.MY_ONNX_MODEL",
    embedding_dimension=768,
)
shared_embedder.get_vectorizer_config_json()
'{"model":"MY_OTHER_SCHEMA.MY_ONNX_MODEL"}'
remote_embedder = OracleDBEmbedder(
    connection=pool,
    provider="openai",
    model="text-embedding-3-small",
    provider_options={"host": "local", "url": "http://localhost:8080/v1/embeddings"},
)
remote_embedder.get_vectorizer_config_json()
'{"embedder_spec":{"host":"local","url":"http://localhost:8080/v1/embeddings","provider":"openai","model":"text-embedding-3-small"}}'

등록 정보 max_input_tokens

노트

생성자가 제공한 값은 데이터베이스 모델에 연결하지 않고 반환됩니다. 그렇지 않으면 이 등록 정보는 예상되는 512 입력 토큰에 맞게 크기 조정된 데이터베이스 모델 프로브를 검증하고 512를 보수적 폴백으로 캐시합니다. 로컬에서 모델 토큰화기를 실행하지 않으므로 정밀도가 중요한 경우 모델의 문서화된 입력 예산에서 max_input_tokens를 수동으로 설정합니다.

예제

embedder = OracleDBEmbedder(
    connection=pool,
    model="DOC_MODEL",
    max_input_tokens=2048,
)
embedder.max_input_tokens
2048