Implementation:Openai Openai python File Search Tool Model

Knowledge Sources	Openai_Openai_python OpenAI API Reference
Domains	API_Types, Python
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete type for representing a file search tool response model provided by the openai-python SDK.

Description

FileSearchTool is a Pydantic model class that represents a tool for searching relevant content from uploaded files. It extends BaseModel and includes a type field fixed to "file_search", a required vector_store_ids list of vector store identifiers to search, an optional filters field (a union of ComparisonFilter or CompoundFilter for metadata-based filtering), an optional max_num_results integer (between 1 and 50 inclusive), and optional RankingOptions for controlling search ranking. The RankingOptions model supports a ranker selector, a score_threshold (0 to 1), and RankingOptionsHybridSearch weights that balance semantic embedding matches versus sparse keyword matches.

Usage

Import this type when deserializing or inspecting file search tool definitions returned in API responses. The model provides typed access to all configuration options for the file search tool including vector store selection, filtering, result limits, and ranking parameters.

Code Reference

Source Location

• Repository: openai-python
• File: src/openai/types/responses/file_search_tool.py

Signature

Filters: TypeAlias = Union[ComparisonFilter, CompoundFilter, None]

class RankingOptionsHybridSearch(BaseModel):
    """Weights for reciprocal rank fusion."""
    embedding_weight: float
    text_weight: float

class RankingOptions(BaseModel):
    """Ranking options for search."""
    hybrid_search: Optional[RankingOptionsHybridSearch] = None
    ranker: Optional[Literal["auto", "default-2024-11-15"]] = None
    score_threshold: Optional[float] = None

class FileSearchTool(BaseModel):
    """A tool that searches for relevant content from uploaded files."""
    type: Literal["file_search"]
    vector_store_ids: List[str]
    filters: Optional[Filters] = None
    max_num_results: Optional[int] = None
    ranking_options: Optional[RankingOptions] = None

Import

from openai.types.responses import FileSearchTool

I/O Contract

Fields (FileSearchTool)

Name	Type	Required	Description
type	Literal["file_search"]	Yes	The type of the file search tool. Always "file_search".
vector_store_ids	List[str]	Yes	The IDs of the vector stores to search.
filters	Optional[Union[ComparisonFilter, CompoundFilter]]	No	A filter to apply to search results.
max_num_results	Optional[int]	No	Maximum number of results to return (1 to 50 inclusive).
ranking_options	Optional[RankingOptions]	No	Ranking options for search results.

Fields (RankingOptions)

Name	Type	Required	Description
hybrid_search	Optional[RankingOptionsHybridSearch]	No	Weights for reciprocal rank fusion balancing embedding vs keyword matches.
ranker	Optional[Literal["auto", "default-2024-11-15"]]	No	The ranker to use for the file search.
score_threshold	Optional[float]	No	Score threshold (0 to 1). Higher values return fewer but more relevant results.

Fields (RankingOptionsHybridSearch)

Name	Type	Required	Description
embedding_weight	float	Yes	The weight of the embedding in reciprocal ranking fusion.
text_weight	float	Yes	The weight of the text in reciprocal ranking fusion.

Usage Examples

from openai.types.responses import FileSearchTool

# Inspect a file search tool from a response
response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["vs_abc123"],
        "max_num_results": 10,
    }],
    input="Find relevant documents about machine learning",
)

for tool in response.tools:
    if isinstance(tool, FileSearchTool):
        print(f"Searching vector stores: {tool.vector_store_ids}")
        if tool.max_num_results:
            print(f"Max results: {tool.max_num_results}")
        if tool.ranking_options and tool.ranking_options.score_threshold:
            print(f"Score threshold: {tool.ranking_options.score_threshold}")

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus